Struct vodozemac::olm::Session

pub struct Session { /* private fields */ }

An Olm session represents one end of an encrypted communication channel between two participants.

A session enables enables the session owner to encrypt messages intended for, and decrypt messages sent by, the other participant of the channel.

Olm sessions have two important properties:

1. They are based on a double ratchet algorithm which continuously introduces new entropy into the channel as messages are sent and received. This imbues the channel with self-healing properties, allowing it to recover from a momentary loss of confidentiality in the event of a key compromise.
2. They are asynchronous, allowing the participant to start sending messages to the other side even if the other participant is not online at the moment.

An Olm Session is acquired from an Account, by calling either

• Account::create_outbound_session, if you are the first participant to send a message in this channel, or
• Account::create_inbound_session, if the other participant initiated the channel by sending you a message.

Implementations

impl Session

pub fn session_id(&self) -> String

Returns the globally unique session ID, in base64-encoded form.

A session ID is the SHA256 of the concatenation of the account’s identity key, an ephemeral base key and the one-time key which was used to establish the session. Due to the construction, every session ID is (probabilistically) globally unique.

pub fn has_received_message(&self) -> bool

Have we ever received and decrypted a message from the other side?

Used to decide if outgoing messages should be sent as normal or pre-key messages.

pub fn encrypt(&mut self, plaintext: &str) -> OlmMessage

Encrypt the plaintext and construct an OlmMessage.

The message will either be a pre-key message or a normal message, depending on whether the session is fully established. A session is fully established once you receive (and decrypt) at least one message from the other side.

pub fn session_keys(&self) -> SessionKeys

Get the keys associated with this session.

pub fn next_message_key(&mut self) -> MessageKey

Available on crate feature low-level-api only.

Get the MessageKey to encrypt the next message.

Note: Each key obtained in this way should be used to encrypt a message and the message must then be sent to the recipient.

Failing to do so will increase the number of out-of-order messages on the recipient side. Given that a Session can only support a limited number of out-of-order messages, this will eventually lead to undecryptable messages.

pub fn decrypt(
    &mut self,
    message: &OlmMessage
) -> Result<String, DecryptionError>

Try to decrypt an Olm message, which will either return the plaintext or result in a DecryptionError.

pub fn pickle(&self) -> SessionPickle

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

pub fn from_pickle(pickle: SessionPickle) -> Self

Restore a Session from a previously saved SessionPickle.

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

Available on crate feature libolm-compat only.

Create a Session object by unpickling a session pickle in libolm legacy pickle format.

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

Trait Implementations

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<SessionPickle> for Session

fn from(pickle: SessionPickle) -> Self

Converts to this type from the input type.