Struct vodozemac::olm::Account

pub struct Account { /* private fields */ }

An Olm Account manages all cryptographic keys used on a device.

Implementations

impl Account

pub fn new() -> Self

Create a new Account with new random identity keys.

pub const fn identity_keys(&self) -> IdentityKeys

Get the IdentityKeys of this Account

pub const fn ed25519_key(&self) -> Ed25519PublicKey

Get a copy of the account’s public Ed25519 key

pub const fn curve25519_key(&self) -> Curve25519PublicKey

Get a copy of the account’s public Curve25519 key

pub fn sign(&self, message: impl AsRef<[u8]>) -> Ed25519Signature

Sign the given message using our Ed25519 fingerprint key.

pub const fn max_number_of_one_time_keys(&self) -> usize

Get the maximum number of one-time keys the client should keep on the server.

Note: this differs from the libolm method of the same name, the libolm method returned the maximum amount of one-time keys the Account could hold and only half of those should be uploaded.

pub fn create_outbound_session( &self, session_config: SessionConfig, identity_key: Curve25519PublicKey, one_time_key: Curve25519PublicKey, ) -> Session

Create a Session with the given identity key and one-time key.

pub fn create_inbound_session( &mut self, their_identity_key: Curve25519PublicKey, pre_key_message: &PreKeyMessage, ) -> Result<InboundCreationResult, SessionCreationError>

Create a Session from the given PreKeyMessage message and identity key

pub fn generate_one_time_keys( &mut self, count: usize, ) -> OneTimeKeyGenerationResult

Generates the supplied number of one time keys. Returns the public parts of the one-time keys that were created and discarded.

Our one-time key store inside the Account has a limited amount of places for one-time keys, If we try to generate new ones while the store is completely populated, the oldest one-time keys will get discarded to make place for new ones.

pub fn stored_one_time_key_count(&self) -> usize

Get the number of one-time keys we have stored locally.

This will be equal or greater to the number of one-time keys we have published. Each time a new Session is created using the Account::create_inbound_session() a one-time key will be used up and removed.

pub fn one_time_keys(&self) -> HashMap<KeyId, Curve25519PublicKey>

Get the currently unpublished one-time keys.

The one-time keys should be published to a server and marked as published using the mark_keys_as_published() method.

pub fn generate_fallback_key(&mut self) -> Option<Curve25519PublicKey>

Generate a single new fallback key.

The fallback key will be used by other users to establish a Session if all the one-time keys on the server have been used up.

Returns the public Curve25519 key of the previous fallback key, that is, the one that will get removed from the Account when this method is called. This return value is mostly useful for logging purposes.

pub fn fallback_key(&self) -> HashMap<KeyId, Curve25519PublicKey>

Get the currently unpublished fallback key.

The fallback key should be published just like the one-time keys, after it has been successfully published it needs to be marked as published using the mark_keys_as_published() method as well.

pub fn forget_fallback_key(&mut self) -> bool

The Account stores at most two private parts of the fallback key. This method lets us forget the previously used fallback key.

pub fn mark_keys_as_published(&mut self)

Mark all currently unpublished one-time and fallback keys as published.

pub fn pickle(&self) -> AccountPickle

Convert the account into a struct which implements serde::Serialize and serde::Deserialize.

pub fn from_pickle(pickle: AccountPickle) -> Self

Restore an Account from a previously saved AccountPickle.

pub fn from_libolm_pickle( pickle: &str, pickle_key: &[u8], ) -> Result<Self, LibolmPickleError>

Create an Account object by unpickling an account pickle in libolm legacy pickle format.

Such pickles are encrypted and need to first be decrypted using pickle_key.

pub fn to_libolm_pickle( &self, pickle_key: &[u8], ) -> Result<String, LibolmPickleError>

Pickle an Account into a libolm pickle format.

This pickle can be restored using the Account::from_libolm_pickle() method, or can be used in the libolm C library.

The pickle will be encrypted using the pickle key.

Note: This method might be lossy, the vodozemac Account has the ability to hold more one-time keys compared to the libolm variant.

⚠️ Security Warning: The pickle key will get expanded into both an AES key and an IV in a deterministic manner. If the same pickle key is reused, this will lead to IV reuse. To prevent this, users have to ensure that they always use a globally (probabilistically) unique pickle key.

Examples

use vodozemac::olm::Account;
use olm_rs::{account::OlmAccount, PicklingMode};
let account = Account::new();

let export = account
    .to_libolm_pickle(&[0u8; 32])
    .expect("We should be able to pickle a freshly created Account");

let unpickled = OlmAccount::unpickle(
    export,
    PicklingMode::Encrypted { key: [0u8; 32].to_vec() },
).expect("We should be able to unpickle our exported Account");

Trait Implementations

impl Default for Account

fn default() -> Self

Returns the “default value” for a type.

impl From<AccountPickle> for Account

fn from(pickle: AccountPickle) -> Self

Converts to this type from the input type.