textsecure

README

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 https://github.com/janimo/textsecure-qml

Automatically generated documentation can be found on [GoDoc] (https://godoc.org/github.com/janimo/textsecure)

Installation

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

go get github.com/janimo/textsecure/cmd/textsecure

For more details, including setting up Go, check the [wiki] (https://github.com/janimo/textsecure/wiki/Installation)

Configuration

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.

Usage

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.

Discussions

User and developer discussions happen on the [mailing list] (https://groups.google.com/forum/#!forum/textsecure-go)

Documentation

Overview

Package textsecure implements the TextSecure client protocol.

Index

• Variables
• func AddDevice(ephemeralId, publicKey, verificationCode string) error
• func ContactIdentityKey(id string) ([]byte, error)
• func EndSession(tel string, msg string) (uint64, error)
• func LeaveGroup(hexid string) error
• func MIMETypeFromReader(r io.Reader) (mime string, reader io.Reader)
• func MyIdentityKey() []byte
• func NewDeviceVerificationCode() (string, error)
• func RegisterWithUPS(token string) error
• func SendAttachment(tel, msg string, r io.Reader) (uint64, error)
• func SendGroupAttachment(hexid string, msg string, r io.Reader) (uint64, error)
• func SendGroupMessage(hexid string, msg string) (uint64, error)
• func SendMessage(tel, msg string) (uint64, error)
• func Setup(c *Client) error
• func StartListening() error
• func StopListening() error
• func UnlinkDevice(id int) error
• func WriteConfig(filename string, cfg *Config) error
• func WriteContacts(filename string, contacts []Contact) error
• type Attachment
• type Client
• type Config
  • func ReadConfig(fileName string) (*Config, error)
• type Contact
  • func GetRegisteredContacts() ([]Contact, error)
  • func ReadContacts(fileName string) ([]Contact, error)
• type DeviceInfo
  • func LinkedDevices() ([]DeviceInfo, error)
• type Group
  • func NewGroup(name string, members []string) (*Group, error)
  • func UpdateGroup(hexid, name string, members []string) (*Group, error)
• type Message
  • func (m *Message) Attachments() []*Attachment
  • func (m *Message) Flags() uint32
  • func (m *Message) Group() *Group
  • func (m *Message) Message() string
  • func (m *Message) Source() string
  • func (m *Message) Timestamp() uint64
• type MessageTypeNotImplementedError
  • func (err MessageTypeNotImplementedError) Error() string
• type RegistrationInfo
• type UnknownContactError
  • func (err UnknownContactError) Error() string
• type UnknownGroupIDError
  • func (err UnknownGroupIDError) Error() string

Variables

var EndSessionFlag uint32 = 1

EndSessionFlag signals that this message resets the session

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

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

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

ErrInvalidMACForAttachment signals that the downloaded attachment has an invalid MAC.

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

ErrInvalidMACForMessage signals an incoming message with invalid MAC.

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

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

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

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.

var GroupLeaveFlag uint32 = 2

GroupLeavelag signals that this message is a group leave message

var GroupUpdateFlag uint32 = 1

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

Functions

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

Types

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

func (err MessageTypeNotImplementedError) Error() string

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