Crate matrix_sdk_crypto

A no-network-IO implementation of a state machine that handles E2EE for Matrix clients.

Usage

If you’re just trying to write a Matrix client or bot in Rust, you’re probably looking for matrix-sdk instead.

However, if you’re looking to add E2EE to an existing Matrix client or library, read on.

The state machine works in a push/pull manner:

• you push state changes and events retrieved from a Matrix homeserver /sync response into the state machine
• you pull requests that you’ll need to send back to the homeserver out of the state machine

use std::collections::BTreeMap;

use matrix_sdk_crypto::{OlmMachine, OlmError};
use ruma::{
    api::client::sync::sync_events::v3::{ToDevice, DeviceLists},
    device_id, user_id,
};

#[tokio::main]
async fn main() -> Result<(), OlmError> {
    let alice = user_id!("@alice:example.org");
    let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;

    let to_device_events = ToDevice::default();
    let changed_devices = DeviceLists::default();
    let one_time_key_counts = BTreeMap::default();
    let unused_fallback_keys = Some(Vec::new());

    // Push changes that the server sent to us in a sync response.
    let decrypted_to_device = machine.receive_sync_changes(
        to_device_events,
        &changed_devices,
        &one_time_key_counts,
        unused_fallback_keys.as_deref(),
    ).await?;

    // Pull requests that we need to send out.
    let outgoing_requests = machine.outgoing_requests().await?;

    // Send the requests here out and call machine.mark_request_as_sent().

    Ok(())
}

Room key sharing algorithm

The decision tree below visualizes the way this crate decides whether a room key will be shared with a requester upon a key request.

Crate Feature Flags

The following crate feature flags are available:

• qrcode: Enbles QRcode generation and reading code

• testing: provides facilities and functions for tests, in particular for integration testing store implementations. ATTENTION: do not ever use outside of tests, we do not provide any stability warantees on these, these are merely helpers. If you find you need any function provided here outside of tests, please open a Github Issue and inform us about your use case for us to consider.

Re-exports

pub use requests::IncomingResponse;

pub use requests::KeysBackupRequest;

pub use requests::KeysQueryRequest;

pub use requests::OutgoingRequest;

pub use requests::OutgoingRequests;

pub use requests::OutgoingVerificationRequest;

pub use requests::RoomMessageRequest;

pub use requests::ToDeviceRequest;

pub use requests::UploadSigningKeysRequest;

pub use store::CrossSigningKeyExport;

pub use store::CryptoStoreError;

pub use store::SecretImportError;

Modules

olm

The crypto specific Olm objects.

requests

Modules containing customized request types.

store

Types and traits to implement the storage layer for the OlmMachine

types

Module containing customized types modeling Matrix keys and events.

vodozemac

Re-exported Error types from the vodozemac crate.

Structs

AcceptSettings

Customize the accept-reply for a verification process

AttachmentDecryptor

A wrapper that transparently encrypts anything that implements Read as an Matrix attachment.

AttachmentEncryptor

A wrapper that transparently encrypts anything that implements Read.

CancelInfo

Information about the cancellation of a verification request or verification flow.

CrossSigningStatus

Struct representing the state of our private cross signing keys, it shows which private cross signing keys we have locally stored.

Device

A device represents a E2EE capable client of an user.

Emoji

An emoji that is used for interactive verification using a short auth string.

EncryptionSettings

Settings for an encrypted room.

GossipRequest

A struct describing an outgoing key request.

MasterPubkey

Wrapper for a cross signing key marking it as the master key.

MediaEncryptionInfo

Struct holding all the information that is needed to decrypt an encrypted file.

OlmMachine

State machine implementation of the Olm/Megolm encryption protocol used for Matrix end to end encryption.

OwnUserIdentity

Struct representing a cross signing identity of a user.

ReadOnlyAccount

Account holding identity keys for which sessions can be created.

ReadOnlyDevice

A read-only version of a Device.

ReadOnlyOwnUserIdentity

Struct representing a cross signing identity of our own user.

ReadOnlyUserIdentity

Struct representing a cross signing identity of a user.

RoomKeyImportResult

Return type for the room key importing.

Sas

Short authentication string object.

UserDevices

A read only view over all devices belonging to a user.

UserIdentity

Struct representing a cross signing identity of a user.

VerificationRequest

An object controlling key verification requests.

Enums

DecryptorError

Error type for attachment decryption.

EventError

Error that occurs when decrypting an event that is malformed.

KeyExportError

Error representing a failure during key export or import.

LocalTrust

The local trust state of a device.

MegolmError

Error representing a failure during a group encryption operation.

OlmError

Error representing a failure during a device to device cryptographic operation.

ReadOnlyUserIdentities

Enum over the different user identity types we can have.

SecretInfo

An enum over the various secret request types we can have.

SessionCreationError

Error that occurs when a room key can’t be converted into a valid Megolm session.

SignatureError

Error type describing different errors that happen when we check or create signatures for a Matrix JSON object.

UserIdentities

Enum over the different user identity types we can have.

Verification

An enum over the different verification types the SDK supports.

Functions

decrypt_room_key_export

Try to decrypt a reader into a list of exported room keys.

encrypt_room_key_export

Encrypt the list of exported room keys using the given passphrase.

format_emojis

Format the the list of emojis as a two line string.