Struct OutboundGroupSession

pub struct OutboundGroupSession { /* private fields */ }

Outbound group session.

Outbound group sessions are used to exchange room messages between a group of participants. Outbound group sessions are used to encrypt the room messages.

Implementations

impl OutboundGroupSession

pub fn new( device_id: OwnedDeviceId, identity_keys: Arc<IdentityKeys>, room_id: &RoomId, settings: EncryptionSettings, ) -> Result<Self, SessionCreationError>

Create a new outbound group session for the given room.

Outbound group sessions are used to encrypt room messages.

Arguments

• device_id - The id of the device that created this session.

• identity_keys - The identity keys of the account that created this session.

• room_id - The id of the room that the session is used in.

• settings - Settings determining the algorithm and rotation period of the outbound group session.

pub fn add_request( &self, request_id: OwnedTransactionId, request: Arc<ToDeviceRequest>, share_infos: BTreeMap<OwnedUserId, BTreeMap<OwnedDeviceId, ShareInfo>>, )

Add a to-device request that is sending the session key (or room key) belonging to this OutboundGroupSession to other members of the group.

The request will get persisted with the session which allows seamless session reuse across application restarts.

Warning this method is only exposed to be used in integration tests of crypto-store implementations. Do not use this outside of tests.

pub fn withheld_code(&self, code: WithheldCode) -> RoomKeyWithheldContent

Create a new m.room_key.withheld event content with the given code for this outbound group session.

pub fn invalidate_session(&self)

This should be called if an the user wishes to rotate this session.

pub fn settings(&self) -> &EncryptionSettings

Get the encryption settings of this outbound session.

pub fn mark_request_as_sent( &self, request_id: &TransactionId, ) -> BTreeMap<OwnedUserId, BTreeSet<OwnedDeviceId>>

Mark the request with the given request id as sent.

This removes the request from the queue and marks the set of users/devices that received the session.

pub async fn encrypt( &self, event_type: &str, content: &Raw<AnyMessageLikeEventContent>, ) -> Raw<RoomEncryptedEventContent>

Encrypt a room message for the given room.

Beware that a room key needs to be shared before this method can be called using the share_room_key() method.

Arguments

• event_type - The plaintext type of the event, the outer type of the event will become m.room.encrypted.

• content - The plaintext content of the message that should be encrypted in raw JSON form.

Panics

Panics if the content can’t be serialized.

pub fn expired(&self) -> bool

Check if the session has expired and if it should be rotated.

A session will expire after some time or if enough messages have been encrypted using it.

pub fn invalidated(&self) -> bool

Has the session been invalidated.

pub fn mark_as_shared(&self)

Mark the session as shared.

Messages shouldn’t be encrypted with the session before it has been shared.

pub fn shared(&self) -> bool

Check if the session has been marked as shared.

pub async fn session_key(&self) -> SessionKey

Get the session key of this session.

A session key can be used to to create an InboundGroupSession.

pub fn sender_key(&self) -> Curve25519PublicKey

Gets the Sender Key

pub fn room_id(&self) -> &RoomId

Get the room id of the room this session belongs to.

pub fn session_id(&self) -> &str

Returns the unique identifier for this session.

pub async fn message_index(&self) -> u32

Get the current message index for this session.

Each message is sent with an increasing index. This returns the message index that will be used for the next encrypted message.

pub fn from_pickle( device_id: OwnedDeviceId, identity_keys: Arc<IdentityKeys>, pickle: PickledOutboundGroupSession, ) -> Result<Self, PickleError>

Restore a Session from a previously pickled string.

Returns the restored group session or a OlmGroupSessionError if there was an error.

Arguments

• device_id - The device ID of the device that created this session. Put differently, our own device ID.

• identity_keys - The identity keys of the device that created this session, our own identity keys.

• pickle - The pickled version of the OutboundGroupSession.

• pickle_mode - The mode that was used to pickle the session, either an unencrypted mode or an encrypted using passphrase.

pub async fn pickle(&self) -> PickledOutboundGroupSession

Store the group session as a base64 encoded string and associated data belonging to the session.

Arguments

• pickle_mode - The mode that should be used to pickle the group session, either an unencrypted mode or an encrypted using passphrase.

Trait Implementations

impl Clone for OutboundGroupSession

fn clone(&self) -> OutboundGroupSession

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OutboundGroupSession

Available on non-tarpaulin_include only.

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

Formats the value using the given formatter.