Struct SecretStore

pub struct SecretStore { /* private fields */ }

Available on crate feature e2e-encryption only.

Secure key/value storage for Matrix users.

The SecretStore struct encapsulates the secret storage mechanism for Matrix users, as it is specified in the Matrix specification.

This specialized storage is tied to the user’s Matrix account and serves as an encrypted key/value store, backed by account data residing on the homeserver. Any secrets uploaded to the homeserver using the SecretStore::put_secret() method are automatically encrypted by the SecretStore.

SecretStore enables you to safely manage and access sensitive information while ensuring that it remains protected from unauthorized access. It plays a crucial role in maintaining the privacy and security of a Matrix user’s data.

Data Flow Overview:

flowchart LR subgraph Client SecretStore end subgraph Homeserver data[Account Data] end SecretStore <== Encrypted ==> data

Note: It’s important to emphasize that the SecretStore should not be used for storing large volumes of data due to its nature as a key/value store for sensitive information.

Examples

use ruma::events::secret::request::SecretName;

let secret_store = client
   .encryption()
   .secret_storage()
   .open_secret_store("It's a secret to everybody")
   .await?;

let my_secret = "Top secret secret";
let my_secret_name = SecretName::from("m.treasure");

secret_store.put_secret(my_secret_name, my_secret);

Implementations

impl SecretStore

pub fn secret_storage_key(&self) -> String

Export the SecretStorageKey of this SecretStore as a base58-encoded string as defined in the spec.

Note: This returns a copy of the private key material of the SecretStorageKey as a string. The caller needs to ensure that this string is zeroized.

pub async fn get_secret( &self, secret_name: impl Into<SecretName>, ) -> Result<Option<String>>

Retrieve a secret from the homeserver’s account data

This method allows you to retrieve a secret from the account data stored on the Matrix homeserver.

Arguments

• secret_name: The name of the secret. The provided secret_name serves as the event type for the associated account data event.

The retrieve_secret method enables you to access and decrypt secrets previously stored in the user’s account data on the homeserver. You can use the secret_name parameter to specify the desired secret to retrieve.

Examples

use ruma::events::secret::request::SecretName;

let secret_store = client
    .encryption()
    .secret_storage()
    .open_secret_store("It's a secret to everybody")
    .await?;

let my_secret_name = SecretName::from("m.treasure");

let secret = secret_store.get_secret(my_secret_name).await?;

pub async fn put_secret( &self, secret_name: impl Into<SecretName>, secret: &str, ) -> Result<()>

Store a secret in the homeserver’s account data

This method allows you to securely store a secret on the Matrix homeserver as an encrypted account data event.

Arguments

• secret_name: The name of the secret. The provided secret_name serves as the event type for the account data event on the homeserver.

• secret: The secret to be stored on the homeserver. The secret is encrypted before being stored, ensuring its confidentiality and integrity.

Examples

use ruma::events::secret::request::SecretName;

let secret_store = client
    .encryption()
    .secret_storage()
    .open_secret_store("It's a secret to everybody")
    .await?;

let my_secret = "Top secret secret";
let my_secret_name = SecretName::from("m.treasure");

secret_store.put_secret(my_secret_name, my_secret);

pub async fn import_secrets(&self) -> Result<()>

Retrieve and store well-known secrets locally

This method retrieves and stores all well-known secrets from the account data on the Matrix homeserver to enhance local security and identity verification.

The following secrets are retrieved by this method:

• m.cross_signing.master: The master cross-signing key.
• m.cross_signing.self_signing: The self-signing cross-signing key.
• m.cross_signing.user_signing: The user-signing cross-signing key.
• m.megolm_backup.v1: The backup recovery key.

If the m.cross_signing.self_signing key is successfully imported, it is used to sign our own Device, marking it as verified. This step is establishes trust in your own device’s identity.

By invoking this method, you ensure that your device has access to the necessary secrets for device and identity verification.

Examples

use ruma::events::secret::request::SecretName;

let secret_store = client
    .encryption()
    .secret_storage()
    .open_secret_store("It's a secret to everybody")
    .await?;

secret_store.import_secrets().await?;

let status = client
    .encryption()
    .cross_signing_status()
    .await
    .expect("We should be able to check out cross-signing status");

println!("Cross-signing status {status:?}");

Trait Implementations

impl Debug for SecretStore

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

Formats the value using the given formatter.