o3

package module
v0.0.0-...-2f9fc2c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2019 License: GPL-3.0 Imports: 31 Imported by: 0

README

Go Report Card

o3

Re-implementation of the Threema protocol. GoDoc here, better documentation will follow.

Documentation

Overview

Package o3 central communication unit responsible for complete exchanges (like handshake and subsequent message reception). Uses functions in packethandler and packetdispatcher to deal with incoming and outgoing messages. Errors in underlying functions bubble up as panics and have to be re- covered here, converted to go errors and returned.

Package o3 functions to prepare and send packets. All preparation required to transmit a packet takes place in the packet's respective dispatcher function. Functions from packetserializer are used to convert from struct to byte buffer form that can then be transmitted on the wire. Errors from packetserializer bubble up here in the form of panics that have to be passed on to communicationhandler for conversion to go errors.

Package o3 handler functions for individual incoming packets. All functions here are called from communicationhandler. Functions in here use packetparser to parse packets into their respective structs. Any action required upon receiving a specific packet is then per- formed within its handler like updating nonces and storing keys in the session context. Errors in underlying functions bubble up to here in the form of panics and are passed on to communicationhandler for central conversion to go errors.

Index

Constants

View Source 
const GroupMessageHeaderLenght = 16

Variables

This section is empty.

Functions

func NewMsgID 

func NewMsgID() uint64

NewMsgID returns a randomly generated message ID (not cryptographically secure!) TODO: Why mrand?

func ReadPassword 

func ReadPassword() ([]byte, error)

ReadPassword uses gopass to read a password from the command line without echoing it

Types

type AddressBook 

type AddressBook struct {
	// contains filtered or unexported fields
}

AddressBook is the register of ThreemaContacts

func (*AddressBook) Add 

func (a *AddressBook) Add(c ThreemaContact)

Add takes a ThreemaContact and adds it to the AddressBook

func (AddressBook) Contacts 

func (a AddressBook) Contacts() map[string]ThreemaContact

Contacts returns the map of id strings to contact structs of all contacts in the address book

func (AddressBook) Get 

func (a AddressBook) Get(id string) (ThreemaContact, bool)

Get returns a ThreemaContact to a given ID. It returns an empty ThreemaContact if no entry is found. The second parameter can be used to check if retrieval was successful

func (*AddressBook) Import 

func (a *AddressBook) Import(contacts [][]string) error

Import takes a two-dimensional slice of strings and imports it field by field into the address book. Fields have to be in the order "ID, Name, LPK" or the function will return an error

func (*AddressBook) ImportFrom 

func (a *AddressBook) ImportFrom(filename string) error

ImportFrom imports an address book stored in a CSV file

func (AddressBook) SaveTo 

func (a AddressBook) SaveTo(filename string) error

SaveTo stores the AddressBook in the file with the given name in CSV format

type AudioMessage 

type AudioMessage struct {
	*MessageHeader
	Duration uint16
	BlobID   [16]byte
	ServerID byte
	Size     uint32
	Key      [32]byte
}

AudioMessage represents a image message as sent e2e encrypted to other threema users

func (AudioMessage) GetData 

func (m AudioMessage) GetData() ([]byte, error)

GetData return the decrypted Audio needs the recipients secret key

func (AudioMessage) MarshalBinary 

func (m AudioMessage) MarshalBinary() ([]byte, error)

Serialize returns a fully serialized byte slice of a TextMessage

func (*AudioMessage) SetData 

func (m *AudioMessage) SetData(data []byte) (err error)

SetAudioData encrypts and uploads the image. Sets the blob info in the AudioMessage. Needs the recipients public key.

func (*AudioMessage) SetDataByFile 

func (m *AudioMessage) SetDataByFile(filename string) error

SetAudio encrypts and uploads the image by file. Sets the blob info in the AudioMessage. Needs the recipients public key.

func (AudioMessage) String 

func (m AudioMessage) String() string

String returns the message text as string

func (*AudioMessage) UnmarshalBinary 

func (m *AudioMessage) UnmarshalBinary(data []byte) error

type DeliveryReceiptMessage 

type DeliveryReceiptMessage struct {
	*MessageHeader
	Status    MsgStatus
	MessageID uint64
}

DeliveryReceiptMessage represents a delivery receipt as sent e2e encrypted to other threema users when a message has been received

func (DeliveryReceiptMessage) MarshalBinary 

func (msg DeliveryReceiptMessage) MarshalBinary() ([]byte, error)

func (*DeliveryReceiptMessage) UnmarshalBinary 

func (msg *DeliveryReceiptMessage) UnmarshalBinary(data []byte) error

type Group 

type Group struct {
	CreatorID IDString
	GroupID   [8]byte
	Name      string
	Members   []IDString
}

Group represents a Threema chat group

type GroupMessageHeader 

type GroupMessageHeader struct {
	CreatorID IDString
	GroupID   [8]byte
}

func (GroupMessageHeader) MarshalBinary 

func (msg GroupMessageHeader) MarshalBinary() ([]byte, error)

func (*GroupMessageHeader) UnmarshalBinary 

func (msg *GroupMessageHeader) UnmarshalBinary(data []byte) error

type IDString 

type IDString [8]byte

IDString is a Threema ID string consisting of capital letters and digits.

func NewIDString 

func NewIDString(ids string) IDString

NewIDString creates an IDString from the input string. There is no input verification. Callers have to ensure that ids complies with Threema's ID rules.

func (IDString) String 

func (is IDString) String() string

type ImageMessage 

type ImageMessage struct {
	*MessageHeader
	*GroupMessageHeader
	BlobID   [16]byte
	ServerID byte
	Size     uint32
	Nonce    nonce
}

ImageMessage represents a image message as sent e2e encrypted to other threema users

func (ImageMessage) GetData 

func (m ImageMessage) GetData(threemaID *ThreemaID) ([]byte, error)

GetImageData return the decrypted Image needs the recipients secret key

func (ImageMessage) MarshalBinary 

func (m ImageMessage) MarshalBinary() ([]byte, error)

Serialize returns a fully serialized byte slice of a TextMessage

func (*ImageMessage) SetData 

func (m *ImageMessage) SetData(threemaID *ThreemaID, data []byte) (err error)

SetData encrypts and uploads the image. Sets the blob info in the ImageMessage. Needs the recipients public key.

func (*ImageMessage) SetDataByFile 

func (m *ImageMessage) SetDataByFile(threemaID *ThreemaID, filename string) error

SetDataByFile encrypts and uploads the image by file. Sets the blob info in the ImageMessage. Needs the recipients public key.

func (ImageMessage) String 

func (m ImageMessage) String() string

String returns the message text as string

func (*ImageMessage) UnmarshalBinary 

func (m *ImageMessage) UnmarshalBinary(data []byte) error

type Message 

type Message interface {
	encoding.BinaryMarshaler

	Header() *MessageHeader
}

type MessageHeader 

type MessageHeader struct {
	Sender    IDString
	Recipient IDString
	ID        uint64
	Time      time.Time
	PubNick   PubNick
}

Message representing the various kinds of e2e ecrypted messages threema supports

func NewMessageHeader 

func NewMessageHeader(sc *SessionContext, recipient string) *MessageHeader

func (*MessageHeader) Header 

func (mh *MessageHeader) Header() *MessageHeader

type MsgStatus 

type MsgStatus uint8

MsgStatus represents the single-byte status field of DeliveryReceiptMessage 

const (
	MSGDELIVERED   MsgStatus = 0x1 //indicates message was received by peer
	MSGREAD        MsgStatus = 0x2 //indicates message was read by peer
	MSGAPPROVED    MsgStatus = 0x3 //indicates message was approved (thumb up) by peer
	MSGDISAPPROVED MsgStatus = 0x4 //indicates message was disapproved (thumb down) by peer
)

MsgStatus mock enum

type MsgType 

type MsgType uint8

MsgType determines the type of message that is sent or received. Users usually won't use this directly and rather use message generator functions. 

const (
	MessageTypeText      MsgType = 0x1
	MessageTypeGroupText MsgType = 0x41
)

MsgType mock enum 

const MessageTypeAudio MsgType = 0x14

MsgType mock enum 

const MessageTypeDeliveryReceipt MsgType = 0x80

MsgType mock enum 

const MessageTypeGroupImage MsgType = 0x42
const MessageTypeImage MsgType = 0x2

MsgType mock enum 

const MessageTypeTypingNotification MsgType = 0x90

MsgType mock enum

type PubNick 

type PubNick [32]byte

PubNick is the representation of Threema's nickname field users can set

func NewPubNick 

func NewPubNick(pb string) PubNick

NewPubNick creates a new PubNick from the input string. Will only take the first 32 bytes of input

func (PubNick) String 

func (pn PubNick) String() string

type ReceivedMsg 

type ReceivedMsg struct {
	Msg Message
	Err error
}

ReceivedMsg is a type used to transmit messages via a channel

type SessionContext 

type SessionContext struct {
	ID ThreemaID

	ErrorChan chan error
	// contains filtered or unexported fields
}

SessionContext is a passable structure containing all established keys and nonces required for communication with the server

func NewSessionContext 

func NewSessionContext(ID ThreemaID) SessionContext

NewSessionContext returns a new SessionContext

func (*SessionContext) Run 

func (sc *SessionContext) Run() (chan<- Message, <-chan ReceivedMsg, error)

Run receives all enqueued Messages and writes the results to the channel passed as argument

type TextMessage 

type TextMessage struct {
	*MessageHeader
	*GroupMessageHeader
	Body string
}

TextMessage represents a text message as sent e2e encrypted to other threema users

func NewTextMessage 

func NewTextMessage(sc *SessionContext, recipient string, text string) (TextMessage, error)

NewTextMessage returns a TextMessage ready to be encrypted

func (TextMessage) MarshalBinary 

func (m TextMessage) MarshalBinary() ([]byte, error)

Serialize returns a fully serialized byte slice of a TextMessage

func (TextMessage) String 

func (tm TextMessage) String() string

String returns the message text as string

func (*TextMessage) UnmarshalBinary 

func (m *TextMessage) UnmarshalBinary(data []byte) error

type ThreemaContact 

type ThreemaContact struct {
	ID   [8]byte
	Name string
	LPK  [32]byte
}

ThreemaContact is the core contact type, comprising of an ID, a long-term public key, and an optional Name

func (ThreemaContact) String 

func (tc ThreemaContact) String() string

type ThreemaID 

type ThreemaID struct {
	ID       IDString
	Nick     PubNick
	LSK      [32]byte
	Contacts AddressBook
	Groups   map[IDString]map[[8]byte]Group // Groups[GroupCreator][GroupID]
}

ThreemaID is the core ID type. It contains the 8-byte ID, its corresponding 32-byte 256-bit private key, and a list of known Contacts.

func LoadIDFromFile 

func LoadIDFromFile(filename string, password []byte) (ThreemaID, error)

LoadIDFromFile will open a Threema identity backup file and parse its base32-encoded encrypted ID using the provided password into a ThreemaID

func NewThreemaID 

func NewThreemaID(id string, lsk [32]byte, contacts AddressBook) (ThreemaID, error)

NewThreemaID creates a ThreemaID from a given id strnig and a 256-bit private key

func ParseIDBackupString 

func ParseIDBackupString(idstr string, password []byte) (ThreemaID, error)

ParseIDBackupString parses the base32-encoded encrypted ID string contained in a threema backup.

func (ThreemaID) GetPubKey 

func (thid ThreemaID) GetPubKey() *[32]byte

GetPubKey generates the PK on the fly, that's ok because it's rarely needed

func (ThreemaID) SaveToFile 

func (thid ThreemaID) SaveToFile(filename string, password []byte) error

SaveToFile exports a ThreemaID to the given filename encrypted with password. It uses Threema's identity export format so the backup can be re-imported both here and in the app. Note that the result will always look different even if using the same password and ID because the salt is re-generated with each backup.

func (ThreemaID) String 

func (thid ThreemaID) String() string

type ThreemaRest 

type ThreemaRest struct {
	// contains filtered or unexported fields
}

ThreemaRest provides convenient wrappers for task that require the use of Threemas REST API

func (ThreemaRest) CreateIdentity 

func (tr ThreemaRest) CreateIdentity() (ThreemaID, error)

CreateIdentity generates a new NaCl Keypair, registers it with the Three servers and returns the assigned ID

func (ThreemaRest) GetContactByID 

func (tr ThreemaRest) GetContactByID(thIDString IDString) (ThreemaContact, error)

GetContactByID returns a ThreemaContact containing the public key as queried from the Threema servers

type TypingNotificationMessage 

type TypingNotificationMessage struct {
	*MessageHeader
	OnOff byte
}

TextMessage represents a text message as sent e2e encrypted to other threema users

func (TypingNotificationMessage) MarshalBinary 

func (msg TypingNotificationMessage) MarshalBinary() ([]byte, error)

Serialize returns a fully serialized byte slice of a TextMessage

func (*TypingNotificationMessage) String 

func (msg *TypingNotificationMessage) String() string

func (*TypingNotificationMessage) UnmarshalBinary 

func (msg *TypingNotificationMessage) UnmarshalBinary(data []byte) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.