Crate olm_sys[−][src]
This is an intermediate crate that exposes the C API of libolm to Rust. If you want to start building things with libolm from Rust, check out olm-rs.
Supported Platforms
- Android
- Linux
- macOS
- Windows
- FreeBSD
- WebAssembly
Building
This library can either be built by statically or dynamically linking against libolm:
Static
This is the default and requires no further action. libolm is built locally and then linked against statically.
Build dependencies
libstdc++/libc++- cmake
- GNU make or a compatible variant (WebAssembly only)
- Emscripten (WebAssembly only)
Dynamic
For linking against libolm dynamically, first make sure that you have the library in your link path.
Then build this library with the OLM_LINK_VARIANT environment variable set to dylib.
For example, building your project using olm-sys as a dependency would look like this:
$ OLM_LINK_VARIANT=dylib cargo build
Cross compiling for Android
To enable cross compilation for Android set the environment variable
ANDROID_NDK to the location of your NDK installation, for example:
$ ANRDOID_NDK=/home/user/Android/Sdk/ndk/22.0.7026061/
The linker needs to be set to an target specific one as well, for example for
aarch64-linux-android set this into your cargo config:
[target.aarch64-linux-android] ar = "/home/user/Android/Sdk/ndk/22.0.7026061/toolchains/llvm/prebuilt/linux-x86_64/bin/ar" linker = "/home/user/Android/Sdk/ndk/22.0.7026061/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android30-clang"
After both of these are set, compilation should work as usual using cargo:
$ ANDROID_NDK=~/Android/Sdk/ndk/22.0.7026061 cargo build --target aarch64-linux-android
Structs
| OlmAccount | |
| OlmInboundGroupSession | |
| OlmOutboundGroupSession | |
| OlmPkDecryption | |
| OlmPkEncryption | |
| OlmPkSigning | |
| OlmSAS | |
| OlmSession | |
| OlmUtility | |
| __fsid_t | |
| max_align_t |
Constants
Functions
| olm_account⚠ | Initialise an account object using the supplied memory The supplied memory must be at least olm_account_size() bytes |
| olm_account_fallback_key⚠ | |
| olm_account_fallback_key_length⚠ | The number of bytes needed to hold the fallback key as returned by olm_account_fallback_key. |
| olm_account_generate_fallback_key⚠ | Generates a new fallback key. Only one previous fallback key is stored. Returns olm_error() on error. If the number of random bytes is too small then olm_account_last_error() will be “NOT_ENOUGH_RANDOM”. |
| olm_account_generate_fallback_key_random_length⚠ | The number of random bytes needed to generate a fallback key. |
| olm_account_generate_one_time_keys⚠ | Generates a number of new one time keys. If the total number of keys stored by this account exceeds max_number_of_one_time_keys() then the old keys are discarded. Returns olm_error() on error. If the number of random bytes is too small then olm_account_last_error() will be “NOT_ENOUGH_RANDOM”. |
| olm_account_generate_one_time_keys_random_length⚠ | The number of random bytes needed to generate a given number of new one time keys. |
| olm_account_identity_keys⚠ | Writes the public parts of the identity keys for the account into the identity_keys output buffer. Returns olm_error() on failure. If the identity_keys buffer was too small then olm_account_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. |
| olm_account_identity_keys_length⚠ | The size of the output buffer needed to hold the identity keys |
| olm_account_last_error⚠ | A null terminated string describing the most recent error to happen to an account |
| olm_account_mark_keys_as_published⚠ | Marks the current set of one time keys as being published. |
| olm_account_max_number_of_one_time_keys⚠ | The largest number of one time keys this account can store. |
| olm_account_one_time_keys⚠ | Writes the public parts of the unpublished one time keys for the account into the one_time_keys output buffer. |
| olm_account_one_time_keys_length⚠ | The size of the output buffer needed to hold the one time keys |
| olm_account_sign⚠ | Signs a message with the ed25519 key for this account. Returns olm_error() on failure. If the signature buffer was too small then olm_account_last_error() will be “OUTPUT_BUFFER_TOO_SMALL” |
| olm_account_signature_length⚠ | The length of an ed25519 signature encoded as base64. |
| olm_account_size⚠ | The size of an account object in bytes |
| olm_clear_account⚠ | Clears the memory used to back this account |
| olm_clear_inbound_group_session⚠ | Clears the memory used to back this group session |
| olm_clear_outbound_group_session⚠ | Clears the memory used to back this group session |
| olm_clear_pk_decryption⚠ | Clears the memory used to back this decryption object |
| olm_clear_pk_encryption⚠ | Clears the memory used to back this encryption object |
| olm_clear_pk_signing⚠ | Clears the memory used to back this signing object |
| olm_clear_sas⚠ | Clears the memory used to back an SAS object. |
| olm_clear_session⚠ | Clears the memory used to back this session |
| olm_clear_utility⚠ | Clears the memory used to back this utility |
| olm_create_account⚠ | Creates a new account. Returns olm_error() on failure. If there weren’t enough random bytes then olm_account_last_error() will be “NOT_ENOUGH_RANDOM” |
| olm_create_account_random_length⚠ | The number of random bytes needed to create an account. |
| olm_create_inbound_session⚠ | Create a new in-bound session for sending/receiving messages from an incoming PRE_KEY message. Returns olm_error() on failure. If the base64 couldn’t be decoded then olm_session_last_error will be “INVALID_BASE64”. If the message was for an unsupported protocol version then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then then olm_session_last_error() will be “BAD_MESSAGE_FORMAT”. If the message refers to an unknown one time key then olm_session_last_error() will be “BAD_MESSAGE_KEY_ID”. |
| olm_create_inbound_session_from⚠ | Create a new in-bound session for sending/receiving messages from an incoming PRE_KEY message. Returns olm_error() on failure. If the base64 couldn’t be decoded then olm_session_last_error will be “INVALID_BASE64”. If the message was for an unsupported protocol version then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then then olm_session_last_error() will be “BAD_MESSAGE_FORMAT”. If the message refers to an unknown one time key then olm_session_last_error() will be “BAD_MESSAGE_KEY_ID”. |
| olm_create_outbound_session⚠ | Creates a new out-bound session for sending messages to a given identity_key and one_time_key. Returns olm_error() on failure. If the keys couldn’t be decoded as base64 then olm_session_last_error() will be “INVALID_BASE64” If there weren’t enough random bytes then olm_session_last_error() will be “NOT_ENOUGH_RANDOM”. |
| olm_create_outbound_session_random_length⚠ | The number of random bytes needed to create an outbound session |
| olm_create_sas⚠ | Creates a new SAS object. |
| olm_create_sas_random_length⚠ | The number of random bytes needed to create an SAS object. |
| olm_decrypt⚠ | Decrypts a message using the session. The input message buffer is destroyed. Returns the length of the plain-text on success. Returns olm_error() on failure. If the plain-text buffer is smaller than olm_decrypt_max_plaintext_length() then olm_session_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. If the base64 couldn’t be decoded then olm_session_last_error() will be “INVALID_BASE64”. If the message is for an unsupported version of the protocol then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then olm_session_last_error() will be BAD_MESSAGE_FORMAT“. If the MAC on the message was invalid then olm_session_last_error() will be “BAD_MESSAGE_MAC”. |
| olm_decrypt_max_plaintext_length⚠ | The maximum number of bytes of plain-text a given message could decode to. The actual size could be different due to padding. The input message buffer is destroyed. Returns olm_error() on failure. If the message base64 couldn’t be decoded then olm_session_last_error() will be “INVALID_BASE64”. If the message is for an unsupported version of the protocol then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then olm_session_last_error() will be “BAD_MESSAGE_FORMAT”. |
| olm_ed25519_verify⚠ | Verify an ed25519 signature. If the key was too small then olm_utility_last_error() will be “INVALID_BASE64”. If the signature was invalid then olm_utility_last_error() will be “BAD_MESSAGE_MAC”. |
| olm_encrypt⚠ | Encrypts a message using the session. Returns the length of the message in bytes on success. Writes the message as base64 into the message buffer. Returns olm_error() on failure. If the message buffer is too small then olm_session_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. If there weren’t enough random bytes then olm_session_last_error() will be “NOT_ENOUGH_RANDOM”. |
| olm_encrypt_message_length⚠ | The size of the next message in bytes for the given number of plain-text bytes. |
| olm_encrypt_message_type⚠ | The type of the next message that olm_encrypt() will return. Returns OLM_MESSAGE_TYPE_PRE_KEY if the message will be a PRE_KEY message. Returns OLM_MESSAGE_TYPE_MESSAGE if the message will be a normal message. Returns olm_error on failure. |
| olm_encrypt_random_length⚠ | The number of random bytes needed to encrypt the next message. |
| olm_error⚠ | The value that olm will return from a function if there was an error |
| olm_export_inbound_group_session⚠ | Export the base64-encoded ratchet key for this session, at the given index, in a format which can be used by olm_import_inbound_group_session |
| olm_export_inbound_group_session_length⚠ | Get the number of bytes returned by olm_export_inbound_group_session() |
| olm_get_library_version⚠ | Get the version number of the library. Arguments will be updated if non-null. |
| olm_group_decrypt⚠ | Decrypt a message. |
| olm_group_decrypt_max_plaintext_length⚠ | Get an upper bound on the number of bytes of plain-text the decrypt method will write for a given input message length. The actual size could be different due to padding. |
| olm_group_encrypt⚠ | Encrypt some plain-text. Returns the length of the encrypted message or olm_error() on failure. On failure last_error will be set with an error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if the output buffer is too small. |
| olm_group_encrypt_message_length⚠ | The number of bytes that will be created by encrypting a message |
| olm_import_inbound_group_session⚠ | Import an inbound group session, from a previous export. |
| olm_inbound_group_session⚠ | Initialise an inbound group session object using the supplied memory The supplied memory should be at least olm_inbound_group_session_size() bytes. |
| olm_inbound_group_session_first_known_index⚠ | Get the first message index we know how to decrypt. |
| olm_inbound_group_session_id⚠ | Get a base64-encoded identifier for this session. |
| olm_inbound_group_session_id_length⚠ | Get the number of bytes returned by olm_inbound_group_session_id() |
| olm_inbound_group_session_is_verified⚠ | Check if the session has been verified as a valid session. |
| olm_inbound_group_session_last_error⚠ | A null terminated string describing the most recent error to happen to a group session |
| olm_inbound_group_session_size⚠ | get the size of an inbound group session, in bytes. |
| olm_init_inbound_group_session⚠ | Start a new inbound group session, from a key exported from olm_outbound_group_session_key |
| olm_init_outbound_group_session⚠ | Start a new outbound group session. Returns olm_error() on failure. On failure last_error will be set with an error code. The last_error will be NOT_ENOUGH_RANDOM if the number of random bytes was too small. |
| olm_init_outbound_group_session_random_length⚠ | The number of random bytes needed to create an outbound group session |
| olm_matches_inbound_session⚠ | 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. The one_time_key_message buffer is destroyed. Returns 1 if the session matches. Returns 0 if the session does not match. Returns olm_error() on failure. If the base64 couldn’t be decoded then olm_session_last_error will be “INVALID_BASE64”. If the message was for an unsupported protocol version then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then then olm_session_last_error() will be “BAD_MESSAGE_FORMAT”. |
| olm_matches_inbound_session_from⚠ | 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. The one_time_key_message buffer is destroyed. Returns 1 if the session matches. Returns 0 if the session does not match. Returns olm_error() on failure. If the base64 couldn’t be decoded then olm_session_last_error will be “INVALID_BASE64”. If the message was for an unsupported protocol version then olm_session_last_error() will be “BAD_MESSAGE_VERSION”. If the message couldn’t be decoded then then olm_session_last_error() will be “BAD_MESSAGE_FORMAT”. |
| olm_outbound_group_session⚠ | Initialise an outbound group session object using the supplied memory The supplied memory should be at least olm_outbound_group_session_size() bytes. |
| olm_outbound_group_session_id⚠ | Get a base64-encoded identifier for this session. |
| olm_outbound_group_session_id_length⚠ | Get the number of bytes returned by olm_outbound_group_session_id() |
| olm_outbound_group_session_key⚠ | Get the base64-encoded current ratchet key for this session. |
| olm_outbound_group_session_key_length⚠ | Get the number of bytes returned by olm_outbound_group_session_key() |
| olm_outbound_group_session_last_error⚠ | A null terminated string describing the most recent error to happen to a group session |
| olm_outbound_group_session_message_index⚠ | Get the current message index for this session. |
| olm_outbound_group_session_size⚠ | get the size of an outbound group session, in bytes. |
| olm_pickle_account⚠ | Stores an account as a base64 string. Encrypts the account using the supplied key. Returns the length of the pickled account on success. Returns olm_error() on failure. If the pickle output buffer is smaller than olm_pickle_account_length() then olm_account_last_error() will be “OUTPUT_BUFFER_TOO_SMALL” |
| olm_pickle_account_length⚠ | Returns the number of bytes needed to store an account |
| olm_pickle_inbound_group_session⚠ | Stores a group session as a base64 string. Encrypts the session using the supplied key. Returns the length of the session on success. |
| olm_pickle_inbound_group_session_length⚠ | Returns the number of bytes needed to store an inbound group session |
| olm_pickle_outbound_group_session⚠ | Stores a group session as a base64 string. Encrypts the session using the supplied key. Returns the length of the session on success. |
| olm_pickle_outbound_group_session_length⚠ | Returns the number of bytes needed to store an outbound group session |
| olm_pickle_pk_decryption⚠ | Stores decryption object as a base64 string. Encrypts the object using the supplied key. Returns the length of the pickled object on success. Returns olm_error() on failure. If the pickle output buffer is smaller than olm_pickle_pk_decryption_length() then olm_pk_decryption_last_error() will be “OUTPUT_BUFFER_TOO_SMALL” |
| olm_pickle_pk_decryption_length⚠ | Returns the number of bytes needed to store a decryption object. |
| olm_pickle_session⚠ | Stores a session as a base64 string. Encrypts the session using the supplied key. Returns the length of the pickled session on success. Returns olm_error() on failure. If the pickle output buffer is smaller than olm_pickle_session_length() then olm_session_last_error() will be “OUTPUT_BUFFER_TOO_SMALL” |
| olm_pickle_session_length⚠ | Returns the number of bytes needed to store a session |
| olm_pk_ciphertext_length⚠ | Get the length of the ciphertext that will correspond to a plaintext of the given length. |
| olm_pk_decrypt⚠ | Decrypt a ciphertext. The input ciphertext buffer is destroyed. See the olm_pk_encrypt function for descriptions of the ephemeral_key and mac arguments. Returns the length of the plaintext on success. Returns olm_error() on failure. If the plaintext buffer is too small then olm_pk_encryption_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. |
| olm_pk_decryption⚠ | Initialise a decryption object using the supplied memory The supplied memory must be at least olm_pk_decryption_size() bytes |
| olm_pk_decryption_last_error⚠ | A null terminated string describing the most recent error to happen to a decription object |
| olm_pk_decryption_size⚠ | |
| olm_pk_encrypt⚠ | Encrypt a plaintext for the recipient set using olm_pk_encryption_set_recipient_key. Writes to the ciphertext, mac, and ephemeral_key buffers, whose values should be sent to the recipient. mac is a Message Authentication Code to ensure that the data is received and decrypted properly. ephemeral_key is the public part of the ephemeral key used (together with the recipient’s key) to generate a symmetric encryption key. Returns olm_error() on failure. If the ciphertext, mac, or ephemeral_key buffers were too small then olm_pk_encryption_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. If there weren’t enough random bytes then olm_pk_encryption_last_error() will be “OLM_INPUT_BUFFER_TOO_SMALL”. |
| olm_pk_encrypt_random_length⚠ | The number of random bytes needed to encrypt a message. |
| olm_pk_encryption⚠ | Initialise an encryption object using the supplied memory The supplied memory must be at least olm_pk_encryption_size() bytes |
| olm_pk_encryption_last_error⚠ | A null terminated string describing the most recent error to happen to an encryption object |
| olm_pk_encryption_set_recipient_key⚠ | Set the recipient’s public key for encrypting to |
| olm_pk_encryption_size⚠ | |
| olm_pk_generate_key⚠ | DEPRECATED: Use olm_pk_key_from_private |
| olm_pk_generate_key_random_length⚠ | DEPRECATED: Use olm_pk_private_key_length() |
| olm_pk_get_private_key⚠ | Get the private key for an OlmDecryption object as an unencoded byte array private_key must be a pointer to a buffer of at least olm_pk_private_key_length() bytes and this length must be passed in private_key_length. If the given buffer is too small, returns olm_error() and olm_pk_encryption_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. Returns the number of bytes written. |
| olm_pk_key_from_private⚠ | Initialise the key from the private part of a key as returned by olm_pk_get_private_key(). The associated public key will be written to the pubkey buffer. Returns olm_error() on failure. If the pubkey buffer is too small then olm_pk_decryption_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. If the private key was not long enough then olm_pk_decryption_last_error() will be “OLM_INPUT_BUFFER_TOO_SMALL”. |
| olm_pk_key_length⚠ | Get the length of a public or ephemeral key |
| olm_pk_mac_length⚠ | Get the length of the message authentication code. |
| olm_pk_max_plaintext_length⚠ | Get the length of the plaintext that will correspond to a ciphertext of the given length. |
| olm_pk_private_key_length⚠ | Get the number of bytes required to store an olm private key |
| olm_pk_sign⚠ | Sign a message. The signature will be written to the signature buffer. Returns olm_error() on failure. If the signature buffer is too small, olm_pk_signing_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. |
| olm_pk_signature_length⚠ | The size of a signature created by a signing object. |
| olm_pk_signing⚠ | Initialise a signing object using the supplied memory The supplied memory must be at least olm_pk_signing_size() bytes |
| olm_pk_signing_key_from_seed⚠ | Initialise the signing object with a public/private keypair from a seed. The associated public key will be written to the pubkey buffer. Returns olm_error() on failure. If the public key buffer is too small then olm_pk_signing_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. If the seed buffer is too small then olm_pk_signing_last_error() will be “INPUT_BUFFER_TOO_SMALL”. |
| olm_pk_signing_last_error⚠ | A null terminated string describing the most recent error to happen to a signing object |
| olm_pk_signing_public_key_length⚠ | The size of the public key of a signing object. |
| olm_pk_signing_seed_length⚠ | The size required for the seed for initialising a signing object. |
| olm_pk_signing_size⚠ | |
| olm_remove_one_time_keys⚠ | Removes the one time keys that the session used from the account. Returns olm_error() on failure. If the account doesn’t have any matching one time keys then olm_account_last_error() will be “BAD_MESSAGE_KEY_ID”. |
| olm_sas⚠ | Initialize an SAS object using the supplied memory.
The supplied memory must be at least |
| olm_sas_calculate_mac⚠ | Generate a message authentication code (MAC) based on the shared secret. |
| olm_sas_calculate_mac_long_kdf⚠ | |
| olm_sas_generate_bytes⚠ | Generate bytes to use for the short authentication string. |
| olm_sas_get_pubkey⚠ | Get the public key for the SAS object. |
| olm_sas_is_their_key_set⚠ | Checks if their key was set. |
| olm_sas_last_error⚠ | A null terminated string describing the most recent error to happen to an SAS object. |
| olm_sas_mac_length⚠ | The size of the message authentication code generated by olm_sas_calculate_mac()`. |
| olm_sas_pubkey_length⚠ | The size of a public key in bytes. |
| olm_sas_set_their_key⚠ | Sets the public key of other user. |
| olm_sas_size⚠ | The size of an SAS object in bytes. |
| olm_session⚠ | Initialise a session object using the supplied memory The supplied memory must be at least olm_session_size() bytes |
| olm_session_describe⚠ | Write a null-terminated string describing the internal state of an olm session to the buffer provided for debugging and logging purposes. |
| olm_session_has_received_message⚠ | |
| olm_session_id⚠ | An identifier for this session. Will be the same for both ends of the conversation. If the id buffer is too small then olm_session_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. |
| olm_session_id_length⚠ | The length of the buffer needed to return the id for this session. |
| olm_session_last_error⚠ | A null terminated string describing the most recent error to happen to a session |
| olm_session_size⚠ | The size of a session object in bytes |
| olm_sha256⚠ | Calculates the SHA-256 hash of the input and encodes it as base64. If the output buffer is smaller than olm_sha256_length() then olm_utility_last_error() will be “OUTPUT_BUFFER_TOO_SMALL”. |
| olm_sha256_length⚠ | The length of the buffer needed to hold the SHA-256 hash. |
| olm_unpickle_account⚠ | Loads an account from a pickled base64 string. Decrypts the account using the supplied key. Returns olm_error() on failure. If the key doesn’t match the one used to encrypt the account then olm_account_last_error() will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then olm_account_last_error() will be “INVALID_BASE64”. The input pickled buffer is destroyed |
| olm_unpickle_inbound_group_session⚠ | Loads a group session from a pickled base64 string. Decrypts the session using the supplied key. |
| olm_unpickle_outbound_group_session⚠ | Loads a group session from a pickled base64 string. Decrypts the session using the supplied key. |
| olm_unpickle_pk_decryption⚠ | Loads a decryption object from a pickled base64 string. The associated public key will be written to the pubkey buffer. Decrypts the object using the supplied key. Returns olm_error() on failure. If the key doesn’t match the one used to encrypt the account then olm_pk_decryption_last_error() will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then olm_pk_decryption_last_error() will be “INVALID_BASE64”. The input pickled buffer is destroyed |
| olm_unpickle_session⚠ | Loads a session from a pickled base64 string. Decrypts the session using the supplied key. Returns olm_error() on failure. If the key doesn’t match the one used to encrypt the account then olm_session_last_error() will be “BAD_ACCOUNT_KEY”. If the base64 couldn’t be decoded then olm_session_last_error() will be “INVALID_BASE64”. The input pickled buffer is destroyed |
| olm_utility⚠ | Initialise a utility object using the supplied memory The supplied memory must be at least olm_utility_size() bytes |
| olm_utility_last_error⚠ | A null terminated string describing the most recent error to happen to a utility |
| olm_utility_size⚠ | The size of a utility object in bytes |