TextSecure library and command line test client for Go

This is a Go package implementing the TextSecure push data (i.e. not encrypted SMS) protocol v3 including the Axolotl ratchet.

The included sample command line app can send and receive text messages and attachments and supports group chat.

The API presented by the package is in flux, mainly driven by the needs of

Automatically generated documentation can be found on [GoDoc] (


This command will install both the library and the test client.

go get

For more details, including setting up Go, check the [wiki] (


Copy cmd/textsecure/.config to a directory and modify it, then run the tool from that directory. It will create .storage to hold all the protocol state. Removing that dir and running the tool again will trigger a reregistration with the server.


Do not run multiple instances of the app from the same directory, it (and the server) can get confused

This will show the supported command line flags

textsecure -h

Running the command without arguments will put it in receiving mode, and once it receives a message it will be able to talk to that contact.


User and developer discussions happen on the [mailing list] (!forum/textsecure-go)

Expand ▾ Collapse ▴



    Package textsecure implements the TextSecure client protocol.



    This section is empty.


    View Source
    var EndSessionFlag uint32 = 1

      EndSessionFlag signals that this message resets the session

      View Source
      var ErrBadPublicKey = errors.New("public key not formatted correctly")

        ErrBadPublicKey is raised when a given public key is not in the expected format.

        View Source
        var ErrInvalidMACForAttachment = errors.New("invalid MAC for attachment")

          ErrInvalidMACForAttachment signals that the downloaded attachment has an invalid MAC.

          View Source
          var ErrInvalidMACForMessage = errors.New("invalid MAC for incoming message")

            ErrInvalidMACForMessage signals an incoming message with invalid MAC.

            View Source
            var ErrNotListening = errors.New("there is no listening connection to stop")

              ErrNotListening is returned when trying to stop listening when there's no valid listening connection set up

              View Source
              var ErrRemoteGone = errors.New("the remote device is gone (probably reinstalled)")

                ErrRemoteGone is returned when the peer reinstalled and lost its session state.

                View Source
                var ErrStoreBadMAC = errors.New("wrong MAC calculated, possibly due to wrong passphrase")

                  ErrStoreBadMAC occurs when MAC verification fails on the records stored using password based encryption. The probable cause is using a wrong password.

                  View Source
                  var GroupLeaveFlag uint32 = 2

                    GroupLeavelag signals that this message is a group leave message

                    View Source
                    var GroupUpdateFlag uint32 = 1

                      GroupUpdateFlag signals that this message updates the group membership or name.


                      func AddDevice

                      func AddDevice(ephemeralId, publicKey, verificationCode string) error

                        AddDevice links a new device

                        func ContactIdentityKey

                        func ContactIdentityKey(id string) ([]byte, error)

                          ContactIdentityKey returns the serialized public key of the given contact

                          func EndSession

                          func EndSession(tel string, msg string) (uint64, error)

                            EndSession terminates the session with the given peer.

                            func LeaveGroup

                            func LeaveGroup(hexid string) error

                              LeaveGroup sends a group quit message to the other members of the given group.

                              func MIMETypeFromReader

                              func MIMETypeFromReader(r io.Reader) (mime string, reader io.Reader)

                              func MyIdentityKey

                              func MyIdentityKey() []byte

                                MyIdentityKey returns our serialized public identity key

                                func NewDeviceVerificationCode

                                func NewDeviceVerificationCode() (string, error)

                                  NewDeviceVerificationCode returns the verification code for linking devices

                                  func RegisterWithUPS

                                  func RegisterWithUPS(token string) error

                                    RegisterWithUPS registers our Ubuntu push client token with the server.

                                    func SendAttachment

                                    func SendAttachment(tel, msg string, r io.Reader) (uint64, error)

                                      SendAttachment sends the contents of a reader, along with an optional message to a given contact.

                                      func SendGroupAttachment

                                      func SendGroupAttachment(hexid string, msg string, r io.Reader) (uint64, error)

                                        SendGroupAttachment sends an attachment to a given group.

                                        func SendGroupMessage

                                        func SendGroupMessage(hexid string, msg string) (uint64, error)

                                          SendGroupMessage sends a text message to a given group.

                                          func SendMessage

                                          func SendMessage(tel, msg string) (uint64, error)

                                            SendMessage sends the given text message to the given contact.

                                            func Setup

                                            func Setup(c *Client) error

                                              Setup initializes the package.

                                              func StartListening

                                              func StartListening() error

                                                StartListening connects to the server and handles incoming websocket messages.

                                                func StopListening

                                                func StopListening() error

                                                  StopListening disables the receiving of messages.

                                                  func UnlinkDevice

                                                  func UnlinkDevice(id int) error

                                                    UnlinkDevice removes a linked device

                                                    func WriteConfig

                                                    func WriteConfig(filename string, cfg *Config) error

                                                      WriteConfig saves a config to a file

                                                      func WriteContacts

                                                      func WriteContacts(filename string, contacts []Contact) error

                                                        WriteContacts saves a list of contacts to a file


                                                        type Attachment

                                                        type Attachment struct {
                                                        	R        io.Reader
                                                        	MimeType string

                                                          Attachment represents an attachment received from a peer

                                                          type Client

                                                          type Client struct {
                                                          	GetPhoneNumber      func() string
                                                          	GetVerificationCode func() string
                                                          	GetStoragePassword  func() string
                                                          	GetConfig           func() (*Config, error)
                                                          	GetLocalContacts    func() ([]Contact, error)
                                                          	MessageHandler      func(*Message)
                                                          	ReceiptHandler      func(string, uint32, uint64)
                                                          	SyncReadHandler     func(string, uint64)
                                                          	SyncSentHandler     func(*Message, uint64)
                                                          	RegistrationDone    func()

                                                            Client contains application specific data and callbacks.

                                                            type Config

                                                            type Config struct {
                                                            	Tel                string `yaml:"tel"`                // Our telephone number
                                                            	Server             string `yaml:"server"`             // The TextSecure server URL
                                                            	RootCA             string `yaml:"rootCA"`             // The TLS signing certificate of the server we connect to
                                                            	ProxyServer        string `yaml:"proxy"`              // HTTP Proxy URL if one is being used
                                                            	VerificationType   string `yaml:"verificationType"`   // Code verification method during registration (SMS/VOICE/DEV)
                                                            	StorageDir         string `yaml:"storageDir"`         // Directory for the persistent storage
                                                            	UnencryptedStorage bool   `yaml:"unencryptedStorage"` // Whether to store plaintext keys and session state (only for development)
                                                            	StoragePassword    string `yaml:"storagePassword"`    // Password to the storage
                                                            	LogLevel           string `yaml:"loglevel"`           // Verbosity of the logging messages
                                                            	UserAgent          string `yaml:"userAgent"`          // Override for the default HTTP User Agent header field
                                                            	AlwaysTrustPeerID  bool   `yaml:"alwaysTrustPeerID"`  // Workaround until proper handling of peer reregistering with new ID.

                                                              Config holds application configuration settings

                                                              func ReadConfig

                                                              func ReadConfig(fileName string) (*Config, error)

                                                                ReadConfig reads a YAML config file

                                                                type Contact

                                                                type Contact struct {
                                                                	Name  string
                                                                	Tel   string
                                                                	Photo string

                                                                  Contact contains information about a contact.

                                                                  func GetRegisteredContacts

                                                                  func GetRegisteredContacts() ([]Contact, error)

                                                                    GetRegisteredContacts returns the subset of the local contacts that are also registered with the server

                                                                    func ReadContacts

                                                                    func ReadContacts(fileName string) ([]Contact, error)

                                                                      ReadContacts reads a YAML contacts file

                                                                      type DeviceInfo

                                                                      type DeviceInfo struct {
                                                                      	ID       uint32 `json:"id"`
                                                                      	Name     string `json:"name"`
                                                                      	Created  uint64 `json:"created"`
                                                                      	LastSeen uint64 `json:"lastSeen"`

                                                                      func LinkedDevices

                                                                      func LinkedDevices() ([]DeviceInfo, error)

                                                                        LinkedDevices returns the list of linked devices

                                                                        type Group

                                                                        type Group struct {
                                                                        	ID      []byte
                                                                        	Hexid   string
                                                                        	Flags   uint32
                                                                        	Name    string
                                                                        	Members []string
                                                                        	Avatar  io.Reader `yaml:"-"`

                                                                          Group holds group metadata.

                                                                          func NewGroup

                                                                          func NewGroup(name string, members []string) (*Group, error)

                                                                            NewGroup creates a group and notifies its members. Our phone number is automatically added to members.

                                                                            func UpdateGroup

                                                                            func UpdateGroup(hexid, name string, members []string) (*Group, error)

                                                                              UpdateGroup updates the group name and/or membership. Our phone number is automatically added to members.

                                                                              type Message

                                                                              type Message struct {
                                                                              	// contains filtered or unexported fields

                                                                                Message represents a message received from the peer. It can optionally include attachments and be sent to a group.

                                                                                func (*Message) Attachments

                                                                                func (m *Message) Attachments() []*Attachment

                                                                                  Attachments returns the list of attachments on the message.

                                                                                  func (*Message) Flags

                                                                                  func (m *Message) Flags() uint32

                                                                                    Flags returns the flags in the message

                                                                                    func (*Message) Group

                                                                                    func (m *Message) Group() *Group

                                                                                      Group returns group information.

                                                                                      func (*Message) Message

                                                                                      func (m *Message) Message() string

                                                                                        Message returns the message body.

                                                                                        func (*Message) Source

                                                                                        func (m *Message) Source() string

                                                                                          Source returns the ID of the sender of the message.

                                                                                          func (*Message) Timestamp

                                                                                          func (m *Message) Timestamp() uint64

                                                                                            Timestamp returns the timestamp of the message

                                                                                            type MessageTypeNotImplementedError

                                                                                            type MessageTypeNotImplementedError struct {
                                                                                            	// contains filtered or unexported fields

                                                                                              MessageTypeNotImplementedError is raised in the unlikely event that an unhandled protocol message type is received.

                                                                                              func (MessageTypeNotImplementedError) Error

                                                                                              type RegistrationInfo

                                                                                              type RegistrationInfo struct {
                                                                                              	// contains filtered or unexported fields

                                                                                                RegistrationInfo holds the data required to be identified by and to communicate with the push server. The data is generated once at install time and stored locally.

                                                                                                type UnknownContactError

                                                                                                type UnknownContactError struct {
                                                                                                	// contains filtered or unexported fields

                                                                                                  UnknownContactError is returned when an unknown group id is encountered

                                                                                                  func (UnknownContactError) Error

                                                                                                  func (err UnknownContactError) Error() string

                                                                                                  type UnknownGroupIDError

                                                                                                  type UnknownGroupIDError struct {
                                                                                                  	// contains filtered or unexported fields

                                                                                                    UnknownGroupIDError is returned when an unknown group id is encountered

                                                                                                    func (UnknownGroupIDError) Error

                                                                                                    func (err UnknownGroupIDError) Error() string


                                                                                                    Path Synopsis
                                                                                                    Package axolotl implements the Axolotl ratchet as used by TextSecure protocol version 3.
                                                                                                    Package axolotl implements the Axolotl ratchet as used by TextSecure protocol version 3.
                                                                                                    Package curve25519sign implements a signature scheme based on Curve25519 keys.
                                                                                                    Package curve25519sign implements a signature scheme based on Curve25519 keys.