olm

package
v0.19.0-mod-2 Latest Latest
Warning

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

 Go to latest Published: Jul 31, 2024 License: MPL-2.0 Imports: 13 Imported by: 0

README

Go olm bindings

Based on Dhole/go-olm

The original project is licensed under the Apache 2.0 license.

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 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

Deprecated

func (*Account) GobEncode 

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

Deprecated

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)

Deprecated

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

Deprecated

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) ([]byte, 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

Deprecated

func (*InboundGroupSession) GobEncode 

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

Deprecated

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)

Deprecated

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

Deprecated

func (*InboundGroupSession) Unpickle 

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

type LibOlmPKDecryption 

type LibOlmPKDecryption struct {
	PublicKey []byte
	// contains filtered or unexported fields
}

func NewPkDecryption 

func NewPkDecryption(privateKey []byte) (*LibOlmPKDecryption, error)

func (*LibOlmPKDecryption) Decrypt 

func (p *LibOlmPKDecryption) Decrypt(ephemeralKey []byte, mac []byte, ciphertext []byte) ([]byte, error)

type LibOlmPKSigning 

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

LibOlmPKSigning stores a key pair for signing messages.

func (*LibOlmPKSigning) PublicKey 

func (p *LibOlmPKSigning) PublicKey() id.Ed25519

func (*LibOlmPKSigning) Seed 

func (p *LibOlmPKSigning) Seed() []byte

func (*LibOlmPKSigning) Sign 

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

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

func (*LibOlmPKSigning) SignJSON 

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

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

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

Deprecated

func (*OutboundGroupSession) GobEncode 

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

Deprecated

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)

Deprecated

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

Deprecated

func (*OutboundGroupSession) Unpickle 

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

type PKDecryption 

type PKDecryption interface {
	// PublicKey returns the public key.
	PublicKey() id.Curve25519

	// Decrypt verifies and decrypts the given message.
	Decrypt(ciphertext, mac []byte, key id.Curve25519) ([]byte, error)
}

PKDecryption is an interface for decrypting messages.

type PKSigning 

type PKSigning interface {
	// Seed returns the seed of the key.
	Seed() []byte

	// PublicKey returns the public key.
	PublicKey() id.Ed25519

	// Sign creates a signature for the given message using this key.
	Sign(message []byte) ([]byte, error)

	// SignJSON creates a signature for the given object after encoding it to
	// canonical JSON.
	SignJSON(obj any) (string, error)
}

PKSigning is an interface for signing messages.

func NewPKSigning 

func NewPKSigning() (PKSigning, error)

NewPKSigning creates a new LibOlmPKSigning object, containing a key pair for signing messages.

func NewPKSigningFromSeed 

func NewPKSigningFromSeed(seed []byte) (PKSigning, error)

NewPKSigningFromSeed creates a new PKSigning object using the given seed.

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 

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

Deprecated

func (*Session) GobEncode 

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

Deprecated

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)

Deprecated

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

Deprecated

func (*Session) Unpickle 

func (s *Session) Unpickle(pickled, key []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.