olm package

olm.account module

libolm Account module.

This module contains the account part of the olm library. It contains a single Account class which handles the creation of new accounts as well as the storing and restoring of them.

Examples

>>> acc = Account()
>>> account.identity_keys()
>>> account.generate_one_time_keys(1)

class olm.account.Account

Bases: object

libolm Account class.

classmethod from_pickle(pickle, passphrase='')

Load an previously stored olm account.

Loads an account from a pickled base64 string and returns an Account object. Decrypts the account using the supplied passphrase. Raises OlmAccountError on failure. If the passphrase doesn’t match the one used to encrypt the account then the error message for the exception will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”.

Parameters:

• pickle (bytes) – Base64 encoded byte string containing the pickled account
• passphrase (str, optional) – The passphrase used to encrypt the account.

generate_one_time_keys(count)

Generate a number of new one time keys.

If the total number of keys stored by this account exceeds max_one_time_keys() then the old keys are discarded. Raises OlmAccountError on error. If the number of random bytes is too small then the error message of the exception will be NOT_ENOUGH_RANDOM.

Parameters:count (int) – The number of keys to generate.

identity_keys

dict – Public part of the identity keys of the account.

mark_keys_as_published()

Mark the current set of one time keys as being published.

max_one_time_keys

int – The maximum number of one time keys the account can store.

one_time_keys

dict – The public part of the one time keys for this account.

pickle(passphrase='')

Store an olm account.

Stores an account as a base64 string. Encrypts the account using the supplied passphrase. Returns a byte object containing the base64 encoded string of the pickled account. Raises OlmAccountError on failure.

Parameters:passphrase (str, optional) – The passphrase to be used to encrypt the account.

remove_one_time_keys(session)

Remove used one time keys.

Removes the one time keys that the session used from the account. Raises OlmAccountError on failure. If the account doesn’t have any matching one time keys then the error message of the exception will be “BAD_MESSAGE_KEY_ID”.

Parameters:

• session (Session) – An Olm Session object that was created with this
• account. –

sign(message)

Signs a message with this account.

Signs a message with the private ed25519 identity key of this account. Returns the signature. Raises OlmAccountError on failure.

Parameters:message (str) – The message to sign.

exception olm.account.OlmAccountError

Bases: Exception

libolm Account error exception.

olm.group_session module

libolm Group session module.

This module contains the group session part of the Olm library. It contains two classes for creating inbound and outbound group sessions.

Examples

>>> outbound = OutboundGroupSession()
>>> InboundGroupSession(outbound.session_key)

class olm.group_session.InboundGroupSession(session_key)

Bases: object

Inbound group session for encrypted multiuser communication.

decrypt(ciphertext)

Decrypt a message

Returns a tuple of the decrypted plain-text and the message index of the decrypted message or raises OlmGroupSessionError on failure. On failure the error message of the exception will be:

• OLM_INVALID_BASE64 if the message is not valid base-64

• OLM_BAD_MESSAGE_VERSION if the message was encrypted with an

  unsupported version of the protocol

• OLM_BAD_MESSAGE_FORMAT if the message headers could not be

  decoded

• OLM_BAD_MESSAGE_MAC if the message could not be verified

• OLM_UNKNOWN_MESSAGE_INDEX 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)

Parameters:ciphertext (str) – Base64 encoded ciphertext containing the encrypted message

export_session(message_index)

Export an inbound group session

Export the base64-encoded ratchet key for this session, at the given index, in a format which can be used by import_session().

Raises OlmGroupSessionError on failure. The error message for the exception will be:

• OLM_UNKNOWN_MESSAGE_INDEX 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)

Parameters:message_index (int) – The message index at which the session should be exported.

first_known_index

int – The first message index we know how to decrypt.

classmethod from_pickle(pickle, passphrase='')

Load a previously stored inbound group session.

Loads a inbound group session from a pickled base64 string and returns a InboundGroupSession object. Decrypts the session using the supplied passphrase. Raises OlmSessionError on failure. If the passphrase doesn’t match the one used to encrypt the session then the error message for the exception will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”.

Parameters:

• pickle (bytes) – Base64 encoded byte string containing the pickled session
• passphrase (str, optional) – The passphrase used to encrypt the

id

str – A base64 encoded identifier for this session.

classmethod import_session(session_key)

Create a InboundGroupSession from an exported session key.

Creates a InboundGroupSession with an previously exported session key, raises OlmGroupSessionError on failure. The error message for the exception will be:

• OLM_INVALID_BASE64 if the session_key is not valid base64
• OLM_BAD_SESSION_KEY if the session_key is invalid

Parameters:session_key (str) – The exported session key with which the inbound group session will be created

pickle(passphrase='')

Store an inbound group session.

Stores a group session as a base64 string. Encrypts the session using the supplied passphrase. Returns a byte object containing the base64 encoded string of the pickled session.

Parameters:passphrase (str, optional) – The passphrase to be used to encrypt the session.

exception olm.group_session.OlmGroupSessionError

Bases: Exception

libolm Group session error exception.

class olm.group_session.OutboundGroupSession

Bases: object

Outbound group session for encrypted multiuser communication.

encrypt(plaintext)

Encrypt a message.

Returns the encrypted ciphertext.

Parameters:plaintext (str) – A string that will be encrypted using the group session.

classmethod from_pickle(pickle, passphrase='')

Load a previously stored outbound group session.

Loads a outbound group session from a pickled base64 string and returns a OutboundGroupSession object. Decrypts the session using the supplied passphrase. Raises OlmSessionError on failure. If the passphrase doesn’t match the one used to encrypt the session then the error message for the exception will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”.

Parameters:

• pickle (bytes) – Base64 encoded byte string containing the pickled session
• passphrase (str, optional) – The passphrase used to encrypt the

id

str – A base64 encoded identifier for this session.

message_index

int – The current message index of the session.

Each message is encrypted with an increasing index. This is the index for the next message.

pickle(passphrase='')

Store an outbound group session.

Stores a group session as a base64 string. Encrypts the session using the supplied passphrase. Returns a byte object containing the base64 encoded string of the pickled session.

Parameters:passphrase (str, optional) – The passphrase to be used to encrypt the session.

session_key

The base64-encoded current ratchet key for this session.

Each message is encrypted with a different ratchet key. This function returns the ratchet key that will be used for the next message.

olm.session module

libolm Session module.

This module contains the Olm Session part of the Olm library.

It is used to establish a peer to peer encrypted communication channel between two Olm accounts.

Examples

>>> alice = Account()
>>> bob = Account()
>>> bob.generate_one_time_keys(1)
>>> id_key = bob.identity_keys['curve25519']
>>> one_time = list(bob.one_time_keys["curve25519"].values())[0]
>>> session = OutboundSession(alice, id_key, one_time)
>>> s = OutboundSession(alice, id_key, one_time)

class olm.session.InboundSession(account, message, identity_key=None)

Bases: olm.session.Session

Inbound Olm session for p2p encrypted communication.

class olm.session.OlmMessage(ciphertext)

Bases: olm.session._OlmMessage

Olm message class

class olm.session.OlmPreKeyMessage(ciphertext)

Bases: olm.session._OlmMessage

Olm prekey message class

Prekey messages are used to establish an Olm session. After the first message exchange the session switches to normal messages

exception olm.session.OlmSessionError

Bases: Exception

libolm Session exception.

class olm.session.OutboundSession(account, identity_key, one_time_key)

Bases: olm.session.Session

Outbound Olm session for p2p encrypted communication.

class olm.session.Session

Bases: object

libolm Session class. This is an abstract class that can’t be instantiated except when unpickling a previously pickled InboundSession or OutboundSession object with from_pickle.

decrypt(message)

Decrypts a message using the session. Returns the plaintext string on success. Raises OlmSessionError on failure. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”. If the message is for an unsupported version of the protocol the error message will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then the error message will be “BAD_MESSAGE_FORMAT”. If the MAC on the message was invalid then the error message will be “BAD_MESSAGE_MAC”.

Parameters:

• message (OlmMessage) – The Olm message that will be decrypted. It can
• either a OlmPreKeyMessage or a OlmMessage. (be) –

encrypt(plaintext)

Encrypts a message using the session. Returns the ciphertext as an base64 encoded strin on success. Raises OlmSessionError on failure. If there weren’t enough random bytes to encrypt the message the error message for the exception will be NOT_ENOUGH_RANDOM.

Parameters:plaintext (str) – The plaintext message that will be encrypted.

classmethod from_pickle(pickle, passphrase='')

Load an previously stored olm session.

Loads a session from a pickled base64 string and returns a Session object. Decrypts the session using the supplied passphrase. Raises OlmSessionError on failure. If the passphrase doesn’t match the one used to encrypt the session then the error message for the exception will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”.

Parameters:

• pickle (bytes) – Base64 encoded byte string containing the pickled session
• passphrase (str, optional) – The passphrase used to encrypt the session.

id

str – An identifier for this session. Will be the same for both ends of the conversation.

matches(message, identity_key=None)

Checks if the PRE_KEY message is for this in-bound session. This can happen if multiple messages are sent to this session before this session sends a message in reply. Returns True if the session matches. Returns False if the session does not match. Raises OlmSessionError on failure. If the base64 couldn’t be decoded then the error message will be “INVALID_BASE64”. If the message was for an unsupported protocol version then the error message will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then then the error message will be * “BAD_MESSAGE_FORMAT”.

Parameters:

• message (OlmPreKeyMessage) – The Olm prekey message that will checked if it is intended for this session.
• identity_key (str, optional) – The identity key of the sender. To check if the message was also sent using this identity key.

pickle(passphrase='')

Store a olm session.

Stores a session as a base64 string. Encrypts the session using the supplied passphrase. Returns a byte object containing the base64 encoded string of the pickled session. Raises OlmSessionError on failure.

Parameters:passphrase (str, optional) – The passphrase to be used to encrypt the session.

olm.utility module

libolm Utility module.

This module contains utilities for olm. It only contains the ed25519_verify function for signature verification.

Examples

>>> alice = Account()

>>> message = "Test"
>>> signature = alice.sign(message)
>>> signing_key = alice.identity_keys["ed25519"]

>>> ed25519_verify(signing_key, message, signature)

exception olm.utility.OlmVerifyError

Bases: Exception

libolm signature verification exception.

olm.utility.ed25519_verify(key, message, signature)

Verify an ed25519 signature.

Raises an OlmVerifyError if verification fails.

Parameters:

• key (str) – The ed25519 public key used for signing.
• message (str) – The signed message.
• signature (bytes) – The message signature.