Struct vodozemac::megolm::InboundGroupSession

source ·

pub struct InboundGroupSession { /* private fields */ }

Expand description

A Megolm inbound group session represents a single receiving participant in an encrypted group communication involving multiple recipients.

The session includes a ratchet for decryption and an Ed25519 public key for ensuring authenticity.

Implementations§

source §

impl InboundGroupSession

source

pub fn new(key: &SessionKey, session_config: SessionConfig) -> Self

Creates a new InboundGroupSession from a SessionKey received over an authenticated channel.

A SessionKey can be obtained from the sender’s GroupSession using the GroupSession::session_key() method.

source

pub fn import( session_key: &ExportedSessionKey, session_config: SessionConfig, ) -> Self

Creates a new InboundGroupSession from an ExportedSessionKey received over an authenticated channel.

An ExportedSessionKey can be obtained from another recipient’s InboundGroupSession using the InboundGroupSession::export_at() method.

Warning: Extra care is required to ensure the authenticity of the InboundGroupSession because an ExportedSessionKey does not include the signature of the original GroupSession creator.

source

pub fn session_id(&self) -> String

Retrieves the unique ID of this session.

This ID is the Ed25519PublicKey encoded in Base64 format.

source

pub fn connected(&mut self, other: &mut InboundGroupSession) -> bool

Check if two InboundGroupSessions are the same.

An InboundGroupSession could be received multiple times with varying degrees of trust and first known message indices.

This method checks if the underlying ratchets of the two InboundGroupSessions are actually the same ratchet, potentially at a different ratcheting index. That is, if the sessions are connected, then ratcheting one of the ratchets to the index of the other should yield the same ratchet value, byte-for-byte. This will only be the case if the InboundGroupSessions were created from the same GroupSession.

If the sessions are connected, the session with the lower message index can safely replace the one with the higher message index.

source

pub fn compare(&mut self, other: &mut InboundGroupSession) -> SessionOrdering

Compare the InboundGroupSession with the given other InboundGroupSession.

Returns a SessionOrdering describing how the two sessions relate to each other.

source

pub fn merge( &mut self, other: &mut InboundGroupSession, ) -> Option<InboundGroupSession>

Merge the session with the given other session, picking the best parts from each of them.

This method is useful when you receive multiple sessions with the same session ID but potentially different ratchet indices and authenticity properties.

For example, imagine you receive a SessionKey S1 with ratchet index A from a fully-trusted source and an ExportedSessionKey S2 with ratchet state B from a less trusted source. If A > B, then S1 is better because it’s fully trusted, but worse because it’s ratcheted further than S2.

This method allows you to merge S1 and S2 safely into a fully-trusted S3 with ratchet state B, provided S1 and S2 connect with each other (meaning they are the same session, just at different ratchet indices).

Returns Some(session) if the sessions could be merged, i.e. they are considered to be connected and None otherwise.

§Example

use vodozemac::megolm::{GroupSession, InboundGroupSession, SessionOrdering};

let session = GroupSession::new(Default::default());
let session_key = session.session_key();

let mut first_session = InboundGroupSession::new(&session_key, Default::default());
let mut second_session = InboundGroupSession::import(&first_session.export_at(10).unwrap(), Default::default());

assert_eq!(first_session.compare(&mut second_session), SessionOrdering::Better);

let mut merged = second_session.merge(&mut first_session).unwrap();

assert_eq!(merged.compare(&mut second_session), SessionOrdering::Better);
assert_eq!(merged.compare(&mut first_session), SessionOrdering::Equal);

source

pub const fn first_known_index(&self) -> u32

Retrieves the first known message index for this InboundGroupSession.

The message index reflects how many times the ratchet has advanced, determining which messages the InboundGroupSession can decrypt. For example, if the first known index is zero, the session can decrypt all messages encrypted by the GroupSession. If the index is one, it can decrypt all messages except the first (zeroth) one.

source

pub fn advance_to(&mut self, index: u32) -> bool

Permanently advances the session to the specified message index.

Advancing the InboundGroupSession will remove the ability to decrypt messages encrypted with a lower index than the provided one.

Returns true if the ratchet was successfully advanced, or false if the ratchet was already advanced beyond the given index.

source

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

Decrypts the provided MegolmMessage using this InboundGroupSession.

Returns a DecryptedMessage containing the plaintext and the message index, which indicates the ratchet position at which the message was encrypted.

source

pub fn export_at(&mut self, index: u32) -> Option<ExportedSessionKey>

Export the InboundGroupSession at the specified message index.

The message index indicates how many times the ratchet has advanced, which determines the messages the InboundGroupSession can decrypt. For example, if the first known index is zero, the session can decrypt all messages encrypted by the GroupSession. If the index is one, it can decrypt all messages except the first (zeroth) one.

Returns None if the InboundGroupSession has been ratcheted beyond the given index, otherwise None.

This method can be used to forget a certain amount of message keys to remove the ability to decrypt those messages.

source

pub fn export_at_first_known_index(&self) -> ExportedSessionKey

Exports the InboundGroupSession at its first known message index.

This is equivalent to passing the message index from InboundGroupSession::first_known_index() to the InboundGroupSession::export_at() method. Since exporting at the first known index is always possible, this function cannot fail.

source