olm

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: May 16, 2022 License: MPL-2.0, Apache-2.0 Imports: 12 Imported by: 2

README

Go olm bindings

Based on Dhole/go-olm

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	EmptyInput         = errors.New("empty input")
	NoKeyProvided      = errors.New("no pickle key provided")
	NotEnoughGoRandom  = errors.New("couldn't get enough randomness from crypto/rand")
	SignatureNotFound  = errors.New("input JSON doesn't contain signature from specified device")
	InputNotJSONString = errors.New("input doesn't look like a JSON string")
)

Error codes from go-olm

View Source 
var (
	NotEnoughRandom        = errors.New("not enough entropy was supplied")
	OutputBufferTooSmall   = errors.New("supplied output buffer is too small")
	BadMessageVersion      = errors.New("the message version is unsupported")
	BadMessageFormat       = errors.New("the message couldn't be decoded")
	BadMessageMAC          = errors.New("the message couldn't be decrypted")
	BadMessageKeyID        = errors.New("the message references an unknown key ID")
	InvalidBase64          = errors.New("the input base64 was invalid")
	BadAccountKey          = errors.New("the supplied account key is invalid")
	UnknownPickleVersion   = errors.New("the pickled object is too new")
	CorruptedPickle        = errors.New("the pickled object couldn't be decoded")
	BadSessionKey          = errors.New("attempt to initialise an inbound group session from an invalid session key")
	UnknownMessageIndex    = errors.New("attempt to decode a message whose index is earlier than our earliest known session key")
	BadLegacyAccountPickle = errors.New("attempt to unpickle an account which uses pickle version 1")
	BadSignature           = errors.New("received message had a bad signature")
	InputBufferTooSmall    = errors.New("the input data was too small to be valid")
)

Error codes from olm code

Functions

func SetPickleKey 

func SetPickleKey(key []byte)

SetPickleKey sets the global pickle key used when encoding structs with Gob or JSON.

func VerifySignatureJSON 

func VerifySignatureJSON(obj interface{}, userID id.UserID, keyName string, key id.Ed25519) (bool, error)

VerifySignatureJSON verifies the signature in the JSON object _obj following the Matrix specification: https://matrix.org/speculator/spec/drafts%2Fe2e/appendices.html#signing-json This function is a wrapper over Utility.VerifySignatureJSON that creates and destroys the Utility object transparently. If the _obj is a struct, the `json` tags will be honored.

func Version 

func Version() (major, minor, patch uint8)

Version returns the version number of the olm library.

Types

type Account 

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

Account stores a device account for end to end encrypted messaging.

func AccountFromPickled 

func AccountFromPickled(pickled, key []byte) (*Account, error)

AccountFromPickled loads an Account from a pickled base64 string. Decrypts the Account using the supplied key. Returns error on failure. If the key doesn't match the one used to encrypt the Account then the error will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then the error will be "INVALID_BASE64".

func NewAccount 

func NewAccount() *Account

NewAccount creates a new Account.

func NewBlankAccount 

func NewBlankAccount() *Account

func (*Account) Clear 

func (a *Account) Clear() error

Clear clears the memory used to back this Account.

func (*Account) GenOneTimeKeys 

func (a *Account) GenOneTimeKeys(num uint)

GenOneTimeKeys generates a number of new one time keys. If the total number of keys stored by this Account exceeds MaxNumberOfOneTimeKeys then the old keys are discarded.

func (*Account) GobDecode 

func (a *Account) GobDecode(rawPickled []byte) error

func (*Account) GobEncode 

func (a *Account) GobEncode() ([]byte, error)

func (*Account) IdentityKeys 

func (a *Account) IdentityKeys() (id.Ed25519, id.Curve25519)

IdentityKeys returns the public parts of the Ed25519 and Curve25519 identity keys for the Account.

func (*Account) IdentityKeysJSON 

func (a *Account) IdentityKeysJSON() []byte

IdentityKeysJSON returns the public parts of the identity keys for the Account.

func (*Account) MarkKeysAsPublished 

func (a *Account) MarkKeysAsPublished()

MarkKeysAsPublished marks the current set of one time keys as being published.

func (*Account) MarshalJSON 

func (a *Account) MarshalJSON() ([]byte, error)

func (*Account) MaxNumberOfOneTimeKeys 

func (a *Account) MaxNumberOfOneTimeKeys() uint

MaxNumberOfOneTimeKeys returns the largest number of one time keys this Account can store.

func (*Account) NewInboundSession 

func (a *Account) NewInboundSession(oneTimeKeyMsg string) (*Session, error)

NewInboundSession creates a new in-bound session for sending/receiving messages from an incoming PRE_KEY message. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message was for an unsupported protocol version then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then then the error will be "BAD_MESSAGE_FORMAT". If the message refers to an unknown one time key then the error will be "BAD_MESSAGE_KEY_ID".

func (*Account) NewInboundSessionFrom 

func (a *Account) NewInboundSessionFrom(theirIdentityKey id.Curve25519, oneTimeKeyMsg string) (*Session, error)

NewInboundSessionFrom creates a new in-bound session for sending/receiving messages from an incoming PRE_KEY message. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message was for an unsupported protocol version then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then then the error will be "BAD_MESSAGE_FORMAT". If the message refers to an unknown one time key then the error will be "BAD_MESSAGE_KEY_ID".

func (*Account) NewOutboundSession 

func (a *Account) NewOutboundSession(theirIdentityKey, theirOneTimeKey id.Curve25519) (*Session, error)

NewOutboundSession creates a new out-bound session for sending messages to a given curve25519 identityKey and oneTimeKey. Returns error on failure. If the keys couldn't be decoded as base64 then the error will be "INVALID_BASE64"

func (*Account) OneTimeKeys 

func (a *Account) OneTimeKeys() map[string]id.Curve25519

OneTimeKeys returns the public parts of the unpublished one time keys for the Account.

The returned data is a struct with the single value "Curve25519", which is itself an object mapping key id to base64-encoded Curve25519 key. For example: 

{
    Curve25519: {
        "AAAAAA": "wo76WcYtb0Vk/pBOdmduiGJ0wIEjW4IBMbbQn7aSnTo",
        "AAAAAB": "LRvjo46L1X2vx69sS9QNFD29HWulxrmW11Up5AfAjgU"
    }
}

func (*Account) Pickle 

func (a *Account) Pickle(key []byte) []byte

Pickle returns an Account as a base64 string. Encrypts the Account using the supplied key.

func (*Account) RemoveOneTimeKeys 

func (a *Account) RemoveOneTimeKeys(s *Session) error

RemoveOneTimeKeys removes the one time keys that the session used from the Account. Returns error on failure. If the Account doesn't have any matching one time keys then the error will be "BAD_MESSAGE_KEY_ID".

func (*Account) Sign 

func (a *Account) Sign(message []byte) []byte

Sign returns the signature of a message using the ed25519 key for this Account.

func (*Account) SignJSON 

func (a *Account) SignJSON(obj interface{}) (string, error)

SignJSON signs the given JSON object following the Matrix specification: https://matrix.org/docs/spec/appendices#signing-json

func (*Account) UnmarshalJSON 

func (a *Account) UnmarshalJSON(data []byte) error

func (*Account) Unpickle 

func (a *Account) Unpickle(pickled, key []byte) error

type InboundGroupSession 

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

InboundGroupSession stores an inbound encrypted messaging session for a group.

func InboundGroupSessionFromPickled 

func InboundGroupSessionFromPickled(pickled, key []byte) (*InboundGroupSession, error)

InboundGroupSessionFromPickled loads an InboundGroupSession from a pickled base64 string. Decrypts the InboundGroupSession using the supplied key. Returns error on failure. If the key doesn't match the one used to encrypt the InboundGroupSession then the error will be "BAD_SESSION_KEY". If the base64 couldn't be decoded then the error will be "INVALID_BASE64".

func InboundGroupSessionImport 

func InboundGroupSessionImport(sessionKey []byte) (*InboundGroupSession, error)

InboundGroupSessionImport imports an inbound group session from a previous export. Returns error on failure. If the sessionKey is not valid base64 the error will be "OLM_INVALID_BASE64". If the session_key is invalid the error will be "OLM_BAD_SESSION_KEY".

func NewBlankInboundGroupSession 

func NewBlankInboundGroupSession() *InboundGroupSession

newInboundGroupSession initialises an empty InboundGroupSession.

func NewInboundGroupSession 

func NewInboundGroupSession(sessionKey []byte) (*InboundGroupSession, error)

NewInboundGroupSession creates a new inbound group session from a key exported from OutboundGroupSession.Key(). Returns error on failure. If the sessionKey is not valid base64 the error will be "OLM_INVALID_BASE64". If the session_key is invalid the error will be "OLM_BAD_SESSION_KEY".

func (*InboundGroupSession) Clear 

func (s *InboundGroupSession) Clear() error

Clear clears the memory used to back this InboundGroupSession.

func (*InboundGroupSession) Decrypt 

func (s *InboundGroupSession) Decrypt(message []byte) ([]byte, uint, error)

Decrypt decrypts a message using the InboundGroupSession. Returns the the plain-text and message index on success. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message is for an unsupported version of the protocol then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then the error will be BAD_MESSAGE_FORMAT". If the MAC on the message was invalid then the error will be "BAD_MESSAGE_MAC". If we do not have a session key corresponding to the message's index (ie, it was sent before the session key was shared with us) the error will be "OLM_UNKNOWN_MESSAGE_INDEX".

func (*InboundGroupSession) Export 

func (s *InboundGroupSession) Export(messageIndex uint32) (string, error)

Export returns the base64-encoded ratchet key for this session, at the given index, in a format which can be used by InboundGroupSession.InboundGroupSessionImport(). Encrypts the InboundGroupSession using the supplied key. Returns error on failure. if we do not have a session key corresponding to the given index (ie, it was sent before the session key was shared with us) the error will be "OLM_UNKNOWN_MESSAGE_INDEX".

func (*InboundGroupSession) FirstKnownIndex 

func (s *InboundGroupSession) FirstKnownIndex() uint32

FirstKnownIndex returns the first message index we know how to decrypt.

func (*InboundGroupSession) GobDecode 

func (s *InboundGroupSession) GobDecode(rawPickled []byte) error

func (*InboundGroupSession) GobEncode 

func (s *InboundGroupSession) GobEncode() ([]byte, error)

func (*InboundGroupSession) ID 

func (s *InboundGroupSession) ID() id.SessionID

ID returns a base64-encoded identifier for this session.

func (*InboundGroupSession) IsVerified 

func (s *InboundGroupSession) IsVerified() uint

IsVerified check if the session has been verified as a valid session. (A session is verified either because the original session share was signed, or because we have subsequently successfully decrypted a message.)

func (*InboundGroupSession) MarshalJSON 

func (s *InboundGroupSession) MarshalJSON() ([]byte, error)

func (*InboundGroupSession) Pickle 

func (s *InboundGroupSession) Pickle(key []byte) []byte

Pickle returns an InboundGroupSession as a base64 string. Encrypts the InboundGroupSession using the supplied key.

func (*InboundGroupSession) UnmarshalJSON 

func (s *InboundGroupSession) UnmarshalJSON(data []byte) error

func (*InboundGroupSession) Unpickle 

func (s *InboundGroupSession) Unpickle(pickled, key []byte) error

type OutboundGroupSession 

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

OutboundGroupSession stores an outbound encrypted messaging session for a group.

func NewBlankOutboundGroupSession 

func NewBlankOutboundGroupSession() *OutboundGroupSession

newOutboundGroupSession initialises an empty OutboundGroupSession.

func NewOutboundGroupSession 

func NewOutboundGroupSession() *OutboundGroupSession

NewOutboundGroupSession creates a new outbound group session.

func OutboundGroupSessionFromPickled 

func OutboundGroupSessionFromPickled(pickled, key []byte) (*OutboundGroupSession, error)

OutboundGroupSessionFromPickled loads an OutboundGroupSession from a pickled base64 string. Decrypts the OutboundGroupSession using the supplied key. Returns error on failure. If the key doesn't match the one used to encrypt the OutboundGroupSession then the error will be "BAD_SESSION_KEY". If the base64 couldn't be decoded then the error will be "INVALID_BASE64".

func (*OutboundGroupSession) Clear 

func (s *OutboundGroupSession) Clear() error

Clear clears the memory used to back this OutboundGroupSession.

func (*OutboundGroupSession) Encrypt 

func (s *OutboundGroupSession) Encrypt(plaintext []byte) []byte

Encrypt encrypts a message using the Session. Returns the encrypted message as base64.

func (*OutboundGroupSession) GobDecode 

func (s *OutboundGroupSession) GobDecode(rawPickled []byte) error

func (*OutboundGroupSession) GobEncode 

func (s *OutboundGroupSession) GobEncode() ([]byte, error)

func (*OutboundGroupSession) ID 

func (s *OutboundGroupSession) ID() id.SessionID

ID returns a base64-encoded identifier for this session.

func (*OutboundGroupSession) Key 

func (s *OutboundGroupSession) Key() string

Key returns the base64-encoded current ratchet key for this session.

func (*OutboundGroupSession) MarshalJSON 

func (s *OutboundGroupSession) MarshalJSON() ([]byte, error)

func (*OutboundGroupSession) MessageIndex 

func (s *OutboundGroupSession) MessageIndex() uint

MessageIndex returns the message index for this session. Each message is sent with an increasing index; this returns the index for the next message.

func (*OutboundGroupSession) Pickle 

func (s *OutboundGroupSession) Pickle(key []byte) []byte

Pickle returns an OutboundGroupSession as a base64 string. Encrypts the OutboundGroupSession using the supplied key.

func (*OutboundGroupSession) UnmarshalJSON 

func (s *OutboundGroupSession) UnmarshalJSON(data []byte) error

func (*OutboundGroupSession) Unpickle 

func (s *OutboundGroupSession) Unpickle(pickled, key []byte) error

type PkSigning added in v0.8.0 

type PkSigning struct {
	PublicKey id.Ed25519
	Seed      []byte
	// contains filtered or unexported fields
}

PkSigning stores a key pair for signing messages.

func NewBlankPkSigning added in v0.8.0 

func NewBlankPkSigning() *PkSigning

func NewPkSigning added in v0.8.0 

func NewPkSigning() (*PkSigning, error)

NewPkSigning creates a new PkSigning object, containing a key pair for signing messages.

func NewPkSigningFromSeed added in v0.8.0 

func NewPkSigningFromSeed(seed []byte) (*PkSigning, error)

NewPkSigningFromSeed creates a new PkSigning object using the given seed.

func (*PkSigning) Clear added in v0.8.0 

func (p *PkSigning) Clear()

Clear clears the underlying memory of a PkSigning object.

func (*PkSigning) Sign added in v0.8.0 

func (p *PkSigning) Sign(message []byte) ([]byte, error)

Sign creates a signature for the given message using this key.

func (*PkSigning) SignJSON added in v0.8.0 

func (p *PkSigning) SignJSON(obj interface{}) (string, error)

SignJSON creates a signature for the given object after encoding it to canonical JSON.

type SAS added in v0.7.0 

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

SAS stores an Olm Short Authentication String (SAS) object.

func NewBlankSAS added in v0.7.0 

func NewBlankSAS() *SAS

NewBlankSAS initializes an empty SAS object.

func NewSAS added in v0.7.0 

func NewSAS() *SAS

NewSAS creates a new SAS object.

func (*SAS) CalculateMAC added in v0.7.0 

func (sas *SAS) CalculateMAC(input []byte, info []byte) ([]byte, error)

CalculateMAC generates a message authentication code (MAC) based on the shared secret.

func (*SAS) GenerateBytes added in v0.7.0 

func (sas *SAS) GenerateBytes(info []byte, count uint) ([]byte, error)

GenerateBytes generates bytes to use for the short authentication string.

func (*SAS) GetPubkey added in v0.7.0 

func (sas *SAS) GetPubkey() []byte

GetPubkey gets the public key for the SAS object.

func (*SAS) SetTheirKey added in v0.7.0 

func (sas *SAS) SetTheirKey(theirKey []byte) error

SetTheirKey sets the public key of the other user.

type Session 

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

Session stores an end to end encrypted messaging session.

func NewBlankSession 

func NewBlankSession() *Session

func SessionFromPickled 

func SessionFromPickled(pickled, key []byte) (*Session, error)

SessionFromPickled loads a Session from a pickled base64 string. Decrypts the Session using the supplied key. Returns error on failure. If the key doesn't match the one used to encrypt the Session then the error will be "BAD_SESSION_KEY". If the base64 couldn't be decoded then the error will be "INVALID_BASE64".

func (*Session) Clear 

func (s *Session) Clear() error

Clear clears the memory used to back this Session.

func (*Session) Decrypt 

func (s *Session) Decrypt(message string, msgType id.OlmMsgType) ([]byte, error)

Decrypt decrypts a message using the Session. Returns the the plain-text on success. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message is for an unsupported version of the protocol then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then the error will be BAD_MESSAGE_FORMAT". If the MAC on the message was invalid then the error will be "BAD_MESSAGE_MAC".

func (*Session) Describe added in v0.10.8 

func (s *Session) Describe() string

Describe generates a string describing the internal state of an olm session for debugging and logging purposes.

func (*Session) Encrypt 

func (s *Session) Encrypt(plaintext []byte) (id.OlmMsgType, []byte)

Encrypt encrypts a message using the Session. Returns the encrypted message as base64.

func (*Session) EncryptMsgType 

func (s *Session) EncryptMsgType() id.OlmMsgType

EncryptMsgType returns the type of the next message that Encrypt will return. Returns MsgTypePreKey if the message will be a PRE_KEY message. Returns MsgTypeMsg if the message will be a normal message. Returns error on failure.

func (*Session) GobDecode 

func (s *Session) GobDecode(rawPickled []byte) error

func (*Session) GobEncode 

func (s *Session) GobEncode() ([]byte, error)

func (*Session) HasReceivedMessage 

func (s *Session) HasReceivedMessage() bool

HasReceivedMessage returns true if this session has received any message.

func (*Session) ID 

func (s *Session) ID() id.SessionID

Id returns an identifier for this Session. Will be the same for both ends of the conversation.

func (*Session) MarshalJSON 

func (s *Session) MarshalJSON() ([]byte, error)

func (*Session) MatchesInboundSession 

func (s *Session) MatchesInboundSession(oneTimeKeyMsg string) (bool, error)

MatchesInboundSession checks if the PRE_KEY message is for this in-bound Session. This can happen if multiple messages are sent to this Account before this Account sends a message in reply. Returns true if the session matches. Returns false if the session does not match. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message was for an unsupported protocol version then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then then the error will be "BAD_MESSAGE_FORMAT".

func (*Session) MatchesInboundSessionFrom 

func (s *Session) MatchesInboundSessionFrom(theirIdentityKey, oneTimeKeyMsg string) (bool, error)

MatchesInboundSessionFrom checks if the PRE_KEY message is for this in-bound Session. This can happen if multiple messages are sent to this Account before this Account sends a message in reply. Returns true if the session matches. Returns false if the session does not match. Returns error on failure. If the base64 couldn't be decoded then the error will be "INVALID_BASE64". If the message was for an unsupported protocol version then the error will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then then the error will be "BAD_MESSAGE_FORMAT".

func (*Session) Pickle 

func (s *Session) Pickle(key []byte) []byte

Pickle returns a Session as a base64 string. Encrypts the Session using the supplied key.

func (*Session) UnmarshalJSON 

func (s *Session) UnmarshalJSON(data []byte) error

func (*Session) Unpickle 

func (s *Session) Unpickle(pickled, key []byte) error

type Signatures 

type Signatures map[id.UserID]map[id.DeviceKeyID]string

Signatures is the data structure used to sign JSON objects.

type Utility 

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

Utility stores the necessary state to perform hash and signature verification operations.

func NewUtility 

func NewUtility() *Utility

NewUtility creates a new utility.

func (*Utility) Clear 

func (u *Utility) Clear() error

Clear clears the memory used to back this utility.

func (*Utility) Sha256 

func (u *Utility) Sha256(input string) string

Sha256 calculates the SHA-256 hash of the input and encodes it as base64.

func (*Utility) VerifySignature 

func (u *Utility) VerifySignature(message string, key id.Ed25519, signature string) (ok bool, err error)

VerifySignature verifies an ed25519 signature. Returns true if the verification suceeds or false otherwise. Returns error on failure. If the key was too small then the error will be "INVALID_BASE64".

func (*Utility) VerifySignatureJSON 

func (u *Utility) VerifySignatureJSON(obj interface{}, userID id.UserID, keyName string, key id.Ed25519) (bool, error)

VerifySignatureJSON verifies the signature in the JSON object _obj following the Matrix specification: https://matrix.org/speculator/spec/drafts%2Fe2e/appendices.html#signing-json If the _obj is a struct, the `json` tags will be honored.

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.