Struct SecretStorageKey

pub struct SecretStorageKey { /* private fields */ }

A secret storage key which can be used to store encrypted data in the user’s account data as defined in the spec.

The secret storage key can be initialized from a passphrase or from a base58-encoded string.

To bootstrap a new SecretStorageKey, use the SecretStorageKey::new() or SecretStorageKey::new_from_passphrase() method.

After a new SecretStorageKey has been created, the info about the key needs to be uploaded to the homeserver as a global account data event. The event and event type for this can be retrieved using the SecretStorageKey::event_content() and SecretStorageKey::event_type() methods, respectively.

Examples

use matrix_sdk_crypto::secret_storage::SecretStorageKey;

// Create a new secret storage key.
let key =
    SecretStorageKey::new_from_passphrase("It's a secret to everybody");
// Retrieve the content.
let content = key.event_content();
// Now upload the content to the server and mark the new key as the default one.

// If we want to restore the secret key, we'll need to retrieve the previously uploaded global
// account data event.
let restored_key = SecretStorageKey::from_account_data(
    "It's a secret to everybody",
    content.to_owned()
);

Implementations

impl SecretStorageKey

pub fn new() -> Self

Create a new random SecretStorageKey.

pub fn new_from_passphrase(passphrase: &str) -> Self

Create a new passphrase-based SecretStorageKey.

The passphrase will be expanded into a 32-byte key using the m.pbkdf2 algorithm described in the spec.

pub fn from_account_data( input: &str, content: SecretStorageKeyEventContent, ) -> Result<Self, DecodeError>

Restore a SecretStorageKey from the given input and the description of the key.

The [SecretStorageKeyEventContent] will contain the description of the SecretStorageKey. The constructor will check if the provided input string matches to the description.

The input can be a passphrase or a Base58 export of the SecretStorageKey.

pub fn to_base58(&self) -> String

Export the SecretStorageKey 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 fn encrypt( &self, plaintext: Vec<u8>, secret_name: &SecretName, ) -> AesHmacSha2EncryptedData

Encrypt a given secret string as a Secrets Storage secret with the given secret name.

Examples

use matrix_sdk_crypto::secret_storage::SecretStorageKey;
use ruma::events::secret::request::SecretName;

let key = SecretStorageKey::new();
let secret = "It's a secret to everybody";
let secret_name = SecretName::from("my-secret");

let encrypted_data = key.encrypt(secret.as_bytes().to_vec(), &secret_name);

let decrypted = key.decrypt(&encrypted_data, &secret_name)?;

assert_eq!(secret.as_bytes(), decrypted);

pub fn decrypt( &self, data: &AesHmacSha2EncryptedData, secret_name: &SecretName, ) -> Result<Vec<u8>, MacError>

Decrypt the given AesHmacSha2EncryptedData containing a secret with the given secret name.

pub fn event_content(&self) -> &SecretStorageKeyEventContent

The info about the SecretStorageKey formatted as a [SecretStorageKeyEventContent].

The [SecretStorageKeyEventContent] contains information about the secret storage key. This information can be used to determine whether the secret the user has entered is a valid secret for unlocking the Secrets Storage (i.e. a valid SecretStorageKey).

pub fn key_id(&self) -> &str

The unique ID of this SecretStorageKey.

pub fn event_type(&self) -> GlobalAccountDataEventType

The event type of this SecretStorageKey.

Can be used when uploading the key info as a [SecretStorageKeyEventContent] to the homeserver.

The type is equal to the concatenation of the string "m.secret_storage.key." and the key ID from the SecretStorageKey::key_id() method.

Trait Implementations

impl Debug for SecretStorageKey

Available on non-tarpaulin_include only.

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

Formats the value using the given formatter.

impl Drop for SecretStorageKey

fn drop(&mut self)

Executes the destructor for this type.

impl Zeroize for SecretStorageKey

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.