Struct matrix_sdk_crypto::OlmMachine [−][src]
pub struct OlmMachine { /* fields omitted */ }
Expand description
State machine implementation of the Olm/Megolm encryption protocol used for Matrix end to end encryption.
Implementations
Create a new memory based OlmMachine.
The created machine will keep the encryption keys only in memory and once the object is dropped the keys will be lost.
Arguments
-
user_id
- The unique id of the user that owns this machine. -
device_id
- The unique id of the device that owns this machine.
pub async fn new_with_store(
user_id: UserId,
device_id: DeviceIdBox,
store: Box<dyn CryptoStore>
) -> StoreResult<Self>
pub async fn new_with_store(
user_id: UserId,
device_id: DeviceIdBox,
store: Box<dyn CryptoStore>
) -> StoreResult<Self>
Create a new OlmMachine with the given CryptoStore
.
The created machine will keep the encryption keys only in memory and once the object is dropped the keys will be lost.
If the store already contains encryption keys for the given user/device pair those will be re-used. Otherwise new ones will be created and stored.
Arguments
-
user_id
- The unique id of the user that owns this machine. -
device_id
- The unique id of the device that owns this machine. -
store
- ACryptostore
implementation that will be used to store the encryption keys.
pub async fn new_with_default_store(
user_id: &UserId,
device_id: &DeviceId,
path: impl AsRef<Path>,
passphrase: Option<&str>
) -> StoreResult<Self>
This is supported on sled_cryptostore
only.
pub async fn new_with_default_store(
user_id: &UserId,
device_id: &DeviceId,
path: impl AsRef<Path>,
passphrase: Option<&str>
) -> StoreResult<Self>
sled_cryptostore
only.Create a new machine with the default crypto store.
The default store uses a Sled database to store the encryption keys.
Arguments
-
user_id
- The unique id of the user that owns this machine. -
device_id
- The unique id of the device that owns this machine.
Get the public parts of our Olm identity keys.
Get the display name of our own device
Get all the tracked users we know about
Get the outgoing requests that need to be sent out.
This returns a list of OutGoingRequest
, those requests need to be sent
out to the server and the responses need to be passed back to the state
machine using mark_request_as_sent
.
pub async fn mark_request_as_sent<'a>(
&self,
request_id: &Uuid,
response: impl Into<IncomingResponse<'a>>
) -> Result<(), OlmError>
pub async fn mark_request_as_sent<'a>(
&self,
request_id: &Uuid,
response: impl Into<IncomingResponse<'a>>
) -> Result<(), OlmError>
Mark the request with the given request id as sent.
Arguments
-
request_id
- The unique id of the request that was sent out. This is needed to couple the response with the now sent out request. -
response
- The response that was received from the server after the outgoing request was sent out.
pub async fn bootstrap_cross_signing(
&self,
reset: bool
) -> StoreResult<(UploadSigningKeysRequest, UploadSignaturesRequest)>
pub async fn bootstrap_cross_signing(
&self,
reset: bool
) -> StoreResult<(UploadSigningKeysRequest, UploadSignaturesRequest)>
Create a new cross signing identity and get the upload request to push the new public keys to the server.
Warning: This will delete any existing cross signing keys that might exist on the server and thus will reset the trust between all the devices.
Uploading these keys will require user interactive auth.
pub async fn get_missing_sessions(
&self,
users: impl Iterator<Item = &UserId>
) -> StoreResult<Option<(Uuid, KeysClaimRequest)>>
pub async fn get_missing_sessions(
&self,
users: impl Iterator<Item = &UserId>
) -> StoreResult<Option<(Uuid, KeysClaimRequest)>>
Get the a key claiming request for the user/device pairs that we are missing Olm sessions for.
Returns None if no key claiming request needs to be sent out.
Sessions need to be established between devices so group sessions for a room can be shared with them.
This should be called every time a group session needs to be shared as well as between sync calls. After a sync some devices may request room keys without us having a valid Olm session with them, making it impossible to server the room key request, thus it’s necessary to check for missing sessions between sync as well.
Note: Care should be taken that only one such request at a time is in flight, e.g. using a lock.
The response of a successful key claiming requests needs to be passed to
the OlmMachine
with the mark_request_as_sent
.
Arguments
users
- The list of users that we should check if we lack a session
with one of their devices. This can be an empty iterator when calling
this method between sync requests.
pub async fn encrypt(
&self,
room_id: &RoomId,
content: AnyMessageEventContent
) -> Result<EncryptedEventContent, MegolmError>
pub async fn encrypt(
&self,
room_id: &RoomId,
content: AnyMessageEventContent
) -> Result<EncryptedEventContent, MegolmError>
Encrypt a room message for the given room.
Beware that a group session needs to be shared before this method can be
called using the share_group_session
method.
Since group sessions can expire or become invalid if the room membership
changes client authors should check with the
should_share_group_session
method if a new group session needs to
be shared.
Arguments
-
room_id
- The id of the room for which the message should be encrypted. -
content
- The plaintext content of the message that should be encrypted.
Panics
Panics if a group session for the given room wasn’t shared beforehand.
Invalidate the currently active outbound group session for the given room.
Returns true if a session was invalidated, false if there was no session to invalidate.
Get to-device requests to share a group session with users in a room.
Arguments
room_id
- The room id of the room where the group session will be
used.
users
- The list of users that should receive the group session.
Get a verification object for the given user id with the given flow id.
pub fn get_verification_request(
&self,
user_id: &UserId,
flow_id: impl AsRef<str>
) -> Option<VerificationRequest>
pub fn get_verification_request(
&self,
user_id: &UserId,
flow_id: impl AsRef<str>
) -> Option<VerificationRequest>
Get a verification request object with the given flow id.
Get all the verification requests of a given user.
pub async fn receive_sync_changes(
&self,
to_device_events: ToDevice,
changed_devices: &DeviceLists,
one_time_keys_counts: &BTreeMap<DeviceKeyAlgorithm, UInt>
) -> Result<ToDevice, OlmError>
pub async fn receive_sync_changes(
&self,
to_device_events: ToDevice,
changed_devices: &DeviceLists,
one_time_keys_counts: &BTreeMap<DeviceKeyAlgorithm, UInt>
) -> Result<ToDevice, OlmError>
Handle a to-device and one-time key counts from a sync response.
This will decrypt and handle to-device events returning the decrypted versions of them.
To decrypt an event from the room timeline call decrypt_room_event
.
Arguments
-
to_device_events
- The to-device events of the current sync response. -
changed_devices
- The list of devices that changed in this sync response. -
one_time_keys_count
- The current one-time keys counts that the sync response returned.
pub async fn request_room_key(
&self,
event: &SyncMessageEvent<EncryptedEventContent>,
room_id: &RoomId
) -> Result<(Option<OutgoingRequest>, OutgoingRequest), MegolmError>
pub async fn request_room_key(
&self,
event: &SyncMessageEvent<EncryptedEventContent>,
room_id: &RoomId
) -> Result<(Option<OutgoingRequest>, OutgoingRequest), MegolmError>
Request a room key from our devices.
This method will return a request cancellation and a new key request if the key was already requested, otherwise it will return just the key request.
The request cancellation must be sent out before the request is sent out, otherwise devices will ignore the key request.
Arguments
-
room_id
- The id of the room where the key is used in. -
sender_key
- The curve25519 key of the sender that owns the key. -
session_id
- The id that uniquely identifies the session.
pub async fn decrypt_room_event(
&self,
event: &SyncMessageEvent<EncryptedEventContent>,
room_id: &RoomId
) -> Result<SyncRoomEvent, MegolmError>
pub async fn decrypt_room_event(
&self,
event: &SyncMessageEvent<EncryptedEventContent>,
room_id: &RoomId
) -> Result<SyncRoomEvent, MegolmError>
Decrypt an event from a room timeline.
Arguments
-
event
- The event that should be decrypted. -
room_id
- The ID of the room where the event was sent to.
Update the tracked users.
Arguments
users
- An iterator over user ids that should be marked for tracking.
This will mark users that weren’t seen before for a key query and tracking.
If the user is already known to the Olm machine it will not be considered for a key query.
pub async fn get_device(
&self,
user_id: &UserId,
device_id: &DeviceId
) -> StoreResult<Option<Device>>
pub async fn get_device(
&self,
user_id: &UserId,
device_id: &DeviceId
) -> StoreResult<Option<Device>>
Get a specific device of a user.
Arguments
-
user_id
- The unique id of the user that the device belongs to. -
device_id
- The unique id of the device.
Returns a Device
if one is found and the crypto store didn’t throw an
error.
Example
let device = machine.get_device(&alice, "DEVICEID".into()).await;
println!("{:?}", device);
Get the cross signing user identity of a user.
Arguments
user_id
- The unique id of the user that the identity belongs to
Returns a UserIdentities
enum if one is found and the crypto store
didn’t throw an error.
pub async fn import_keys(
&self,
exported_keys: Vec<ExportedRoomKey>,
progress_listener: impl Fn(usize, usize)
) -> StoreResult<(usize, usize)>
pub async fn import_keys(
&self,
exported_keys: Vec<ExportedRoomKey>,
progress_listener: impl Fn(usize, usize)
) -> StoreResult<(usize, usize)>
Import the given room keys into our store.
Arguments
exported_keys
- A list of previously exported keys that should be imported into our store. If we already have a better version of a key the key will not be imported.
Returns a tuple of numbers that represent the number of sessions that were imported and the total number of sessions that were found in the key export.
Examples
let exported_keys = decrypt_key_export(export, "1234").unwrap();
machine.import_keys(exported_keys, |_, _| {}).await.unwrap();
pub async fn export_keys(
&self,
predicate: impl FnMut(&InboundGroupSession) -> bool
) -> StoreResult<Vec<ExportedRoomKey>>
pub async fn export_keys(
&self,
predicate: impl FnMut(&InboundGroupSession) -> bool
) -> StoreResult<Vec<ExportedRoomKey>>
Export the keys that match the given predicate.
Arguments
predicate
- A closure that will be called for every knownInboundGroupSession
, which represents a room key. If the closure returnstrue
theInboundGroupSession
will be included in the export, if the closure returnsfalse
it will not be included.
Panics
This method will panic if it can’t get enough randomness from the OS to encrypt the exported keys securely.
Examples
let room_id = room_id!("!test:localhost");
let exported_keys = machine.export_keys(|s| s.room_id() == &room_id).await.unwrap();
let encrypted_export = encrypt_key_export(&exported_keys, "1234", 1);
Get the status of the private cross signing keys.
This can be used to check which private cross signing keys we have stored locally.
Export all the private cross signing keys we have.
The export will contain the seed for the ed25519 keys as a unpadded base64 encoded string.
This method returns None
if we don’t have any private cross signing
keys.
pub async fn import_cross_signing_keys(
&self,
export: CrossSigningKeyExport
) -> Result<CrossSigningStatus, SecretImportError>
pub async fn import_cross_signing_keys(
&self,
export: CrossSigningKeyExport
) -> Result<CrossSigningStatus, SecretImportError>
Import our private cross signing keys.
The export needs to contain the seed for the ed25519 keys as an unpadded base64 encoded string.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for OlmMachine
impl Send for OlmMachine
impl Sync for OlmMachine
impl Unpin for OlmMachine
impl !UnwindSafe for OlmMachine
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more