olm

README

Go olm bindings

Based on Dhole/go-olm

The original project is licensed under the Apache 2.0 license.

Documentation

Index

• Variables
• func SetPickleKey(key []byte)
• func Version() (major, minor, patch uint8)
• type Account
  • func AccountFromPickled(pickled, key []byte) (Account, error)
  • func NewAccount(r io.Reader) (Account, error)
  • func NewBlankAccount() Account
• type InboundGroupSession
  • func InboundGroupSessionFromPickled(pickled, key []byte) (InboundGroupSession, error)
  • func InboundGroupSessionImport(sessionKey []byte) (InboundGroupSession, error)
  • func NewBlankInboundGroupSession() InboundGroupSession
  • func NewInboundGroupSession(sessionKey []byte) (InboundGroupSession, error)
• type OutboundGroupSession
  • func NewBlankOutboundGroupSession() OutboundGroupSession
  • func NewOutboundGroupSession() OutboundGroupSession
  • func OutboundGroupSessionFromPickled(pickled, key []byte) (OutboundGroupSession, error)
• type PKDecryption
  • func NewPKDecryptionFromPrivateKey(privateKey []byte) (PKDecryption, error)
• type PKSigning
  • func NewPKSigning() (PKSigning, error)
  • func NewPKSigningFromSeed(seed []byte) (PKSigning, error)
• type Session
  • func NewBlankSession() Session
  • func SessionFromPickled(pickled, key []byte) (Session, error)

Variables

var (
	ErrBadSignature         = errors.New("bad signature")
	ErrBadMAC               = errors.New("bad mac")
	ErrBadMessageFormat     = errors.New("bad message format")
	ErrBadVerification      = errors.New("bad verification")
	ErrWrongProtocolVersion = errors.New("wrong protocol version")
	ErrEmptyInput           = errors.New("empty input")
	ErrNoKeyProvided        = errors.New("no key")
	ErrBadMessageKeyID      = errors.New("bad message key id")
	ErrRatchetNotAvailable  = errors.New("ratchet not available: attempt to decode a message whose index is earlier than our earliest known session key")
	ErrMsgIndexTooHigh      = errors.New("message index too high")
	ErrProtocolViolation    = errors.New("not protocol message order")
	ErrMessageKeyNotFound   = errors.New("message key not found")
	ErrChainTooHigh         = errors.New("chain index too high")
	ErrBadInput             = errors.New("bad input")
	ErrBadVersion           = errors.New("wrong version")
	ErrWrongPickleVersion   = errors.New("wrong pickle version")
	ErrValueTooShort        = errors.New("value too short")
	ErrInputToSmall         = errors.New("input too small (truncated?)")
	ErrOverflow             = errors.New("overflow")
)

Those are the most common used errors

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

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

var GetVersion func() (major, minor, patch uint8)

var InitBlankAccount func() Account

var InitBlankInboundGroupSession func() InboundGroupSession

var InitInboundGroupSessionFromPickled func(pickled, key []byte) (InboundGroupSession, error)

var InitInboundGroupSessionImport func(sessionKey []byte) (InboundGroupSession, error)

var InitNewAccount func(io.Reader) (Account, error)

var InitNewAccountFromPickled func(pickled, key []byte) (Account, error)

var InitNewBlankOutboundGroupSession func() OutboundGroupSession

var InitNewBlankSession func() Session

var InitNewInboundGroupSession func(sessionKey []byte) (InboundGroupSession, error)

var InitNewOutboundGroupSession func() OutboundGroupSession

var InitNewOutboundGroupSessionFromPickled func(pickled, key []byte) (OutboundGroupSession, error)

var InitNewPKDecryptionFromPrivateKey func(privateKey []byte) (PKDecryption, error)

var InitNewPKSigning func() (PKSigning, error)

var InitNewPKSigningFromSeed func(seed []byte) (PKSigning, error)

var InitSessionFromPickled func(pickled, key []byte) (Session, error)

var SetPickleKeyImpl func(key []byte)

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 interface {
	// Pickle returns an Account as a base64 string. Encrypts the Account using the
	// supplied key.
	Pickle(key []byte) ([]byte, error)

	// Unpickle loads an Account from a pickled base64 string. Decrypts the
	// Account using the supplied key. Returns error on failure.
	Unpickle(pickled, key []byte) error

	// IdentityKeysJSON returns the public parts of the identity keys for the Account.
	IdentityKeysJSON() ([]byte, error)

	// IdentityKeys returns the public parts of the Ed25519 and Curve25519 identity
	// keys for the Account.
	IdentityKeys() (id.Ed25519, id.Curve25519, error)

	// Sign returns the signature of a message using the ed25519 key for this
	// Account.
	Sign(message []byte) ([]byte, error)

	// 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"
	//	    }
	//	}
	OneTimeKeys() (map[string]id.Curve25519, error)

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

	// MaxNumberOfOneTimeKeys returns the largest number of one time keys this
	// Account can store.
	MaxNumberOfOneTimeKeys() 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. Reads random data from the given
	// reader, or if nil is passed, defaults to crypto/rand.
	GenOneTimeKeys(reader io.Reader, num uint) 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"
	NewOutboundSession(theirIdentityKey, theirOneTimeKey id.Curve25519) (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".
	NewInboundSession(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".
	NewInboundSessionFrom(theirIdentityKey *id.Curve25519, oneTimeKeyMsg string) (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".
	RemoveOneTimeKeys(s Session) error
}

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(r io.Reader) (Account, error)

NewAccount creates a new Account.

func NewBlankAccount

func NewBlankAccount() Account

type InboundGroupSession

type InboundGroupSession interface {
	// Pickle returns an InboundGroupSession as a base64 string.  Encrypts the
	// InboundGroupSession using the supplied key.
	Pickle(key []byte) ([]byte, error)

	// Unpickle loads an [InboundGroupSession] from a pickled base64 string.
	// Decrypts the [InboundGroupSession] using the supplied key.
	Unpickle(pickled, key []byte) error

	// Decrypt decrypts a message using the [InboundGroupSession]. Returns 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".
	Decrypt(message []byte) ([]byte, uint, error)

	// ID returns a base64-encoded identifier for this session.
	ID() id.SessionID

	// FirstKnownIndex returns the first message index we know how to decrypt.
	FirstKnownIndex() uint32

	// 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.)
	IsVerified() bool

	// 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".
	Export(messageIndex uint32) ([]byte, error)
}

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.

func InboundGroupSessionImport

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

InboundGroupSessionImport imports an inbound group session from a previous export. Returns error on failure.

func NewBlankInboundGroupSession

func NewBlankInboundGroupSession() 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.

type OutboundGroupSession

type OutboundGroupSession interface {
	// Pickle returns a Session as a base64 string. Encrypts the Session using
	// the supplied key.
	Pickle(key []byte) ([]byte, error)

	// Unpickle loads an [OutboundGroupSession] from a pickled base64 string.
	// Decrypts the [OutboundGroupSession] using the supplied key.
	Unpickle(pickled, key []byte) error

	// Encrypt encrypts a message using the [OutboundGroupSession]. Returns the
	// encrypted message as base64.
	Encrypt(plaintext []byte) ([]byte, error)

	// ID returns a base64-encoded identifier for this session.
	ID() id.SessionID

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

	// Key returns the base64-encoded current ratchet key for this session.
	Key() string
}

func NewBlankOutboundGroupSession

func NewBlankOutboundGroupSession() OutboundGroupSession

NewBlankOutboundGroupSession 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".

type PKDecryption

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

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

PKDecryption is an interface for decrypting messages.

func NewPKDecryptionFromPrivateKey

func NewPKDecryptionFromPrivateKey(privateKey []byte) (PKDecryption, error)

NewPKDecryptionFromPrivateKey creates a new PKDecryption from a base64-encoded private key.

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 PKSigning 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 interface {
	// Pickle returns a Session as a base64 string. Encrypts the Session using
	// the supplied key.
	Pickle(key []byte) ([]byte, error)

	// Unpickle loads a Session from a pickled base64 string. Decrypts the
	// Session using the supplied key.
	Unpickle(pickled, key []byte) error

	// ID returns an identifier for this Session. Will be the same for both
	// ends of the conversation.
	ID() id.SessionID

	// HasReceivedMessage returns true if this session has received any
	// message.
	HasReceivedMessage() bool

	// 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".
	MatchesInboundSession(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".
	MatchesInboundSessionFrom(theirIdentityKey, oneTimeKeyMsg string) (bool, error)

	// 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.
	EncryptMsgType() id.OlmMsgType

	// Encrypt encrypts a message using the Session. Returns the encrypted
	// message as base64.
	Encrypt(plaintext []byte) (id.OlmMsgType, []byte, error)

	// Decrypt decrypts a message using the Session. Returns 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".
	Decrypt(message string, msgType id.OlmMsgType) ([]byte, error)

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

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.