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.