Struct StoreCipher

pub struct StoreCipher { /* private fields */ }

An encryption key that can be used to encrypt data for key/value stores.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

// Export the store cipher and persist it in your key/value store
let export = store_cipher.export("secret-passphrase")?;

let value = json!({
    "some": "data",
});

let encrypted = store_cipher.encrypt_value(&value)?;
let decrypted: Value = store_cipher.decrypt_value(&encrypted)?;

assert_eq!(value, decrypted);

Implementations

impl StoreCipher

pub fn new() -> Result<Self, Error>

Generate a new random store cipher.

pub fn export(&self, passphrase: &str) -> Result<Vec<u8>, Error>

Encrypt the store cipher using the given passphrase and export it.

This method can be used to persist the StoreCipher in an unencrypted key/value store in a safe manner.

The StoreCipher can later on be restored using StoreCipher::import.

Arguments

• passphrase - The passphrase that should be used to encrypt the store cipher.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::json;

let store_cipher = StoreCipher::new()?;

// Export the store cipher and persist it in your key/value store
let export = store_cipher.export("secret-passphrase");

// Save the export in your key/value store.

pub fn export_with_key(&self, key: &[u8; 32]) -> Result<Vec<u8>, Error>

Encrypt the store cipher using the given key and export it.

This method can be used to persist the StoreCipher in an unencrypted key/value store in a safe manner.

The StoreCipher can later on be restored using StoreCipher::import_with_key.

Arguments

• key - The 32-byte key to be used to encrypt the store cipher. It’s recommended to use a freshly and securely generated random key.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::json;

let store_cipher = StoreCipher::new()?;

// Export the store cipher and persist it in your key/value store
let export = store_cipher.export_with_key(&[0u8; 32]);

// Save the export in your key/value store.

pub fn import(passphrase: &str, encrypted: &[u8]) -> Result<Self, Error>

Restore a store cipher from an export encrypted with a passphrase.

Arguments

• passphrase - The passphrase that was used to encrypt the store cipher.

• encrypted - The exported and encrypted version of the store cipher.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::json;

let store_cipher = StoreCipher::new()?;

// Export the store cipher and persist it in your key/value store
let export = store_cipher.export("secret-passphrase")?;

// This is now the same as `store_cipher`.
let imported = StoreCipher::import("secret-passphrase", &export)?;

// Save the export in your key/value store.

pub fn import_with_key(key: &[u8; 32], encrypted: &[u8]) -> Result<Self, Error>

Restore a store cipher from an export encrypted with a random key.

Arguments

• key - The 32-byte decryption key that was previously used to encrypt the store cipher.

• encrypted - The exported and encrypted version of the store cipher.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::json;

let store_cipher = StoreCipher::new()?;

// Export the store cipher and persist it in your key/value store
let export = store_cipher.export_with_key(&[0u8; 32])?;

// This is now the same as `store_cipher`.
let imported = StoreCipher::import_with_key(&[0u8; 32], &export)?;

// Save the export in your key/value store.

pub fn hash_key(&self, table_name: &str, key: &[u8]) -> [u8; 32]

Hash a key before it is inserted into the key/value store.

This prevents the key names from leaking to parties which do not have the ability to decrypt the key/value store.

Arguments

• table_name - The name of the key/value table this key will be inserted into. This can also contain additional unique data. It will be used to derive a table-specific cryptographic key which will be used in a keyed hash function. This ensures data independence between the different tables of the key/value store.

• key - The key to be hashed, prior to insertion into the key/value store.

Note: This is a one-way transformation; you cannot obtain the original key from its hash.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::json;

let store_cipher = StoreCipher::new()?;

let key = "bulbasaur";

// Hash the key so people don't know which pokemon we have collected.
let hashed_key = store_cipher.hash_key("list-of-pokemon", key.as_ref());

// It's now safe to insert the key into our key/value store.

pub fn encrypt_value(&self, value: &impl Serialize) -> Result<Vec<u8>, Error>

Encrypt a value before it is inserted into the key/value store.

A value can be decrypted using the StoreCipher::decrypt_value() method.

Arguments

• value - A value that should be encrypted, any value that implements Serialize can be given to this method. The value will be serialized as json before it is encrypted.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = json!({
    "some": "data",
});

let encrypted = store_cipher.encrypt_value(&value)?;
let decrypted: Value = store_cipher.decrypt_value(&encrypted)?;

assert_eq!(value, decrypted);

pub fn encrypt_value_data(&self, data: Vec<u8>) -> Result<EncryptedValue, Error>

Encrypt some data before it is inserted into the key/value store.

A value can be decrypted using the StoreCipher::decrypt_value_data() method. This is the lower level function to encrypt_value

Arguments

• data - A value that should be encrypted, encoded as a Vec<u8>

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = serde_json::to_vec(&json!({
    "some": "data",
}))?;

let encrypted = store_cipher.encrypt_value_data(value.clone())?;
let decrypted = store_cipher.decrypt_value_data(encrypted)?;

assert_eq!(value, decrypted);

pub fn encrypt_value_base64_data( &self, data: Vec<u8>, ) -> Result<EncryptedValueBase64, Error>

Encrypt some data before it is inserted into the key/value store, using base64 for arrays of integers.

A value can be decrypted using the StoreCipher::decrypt_value_base64_data() method.

Arguments

• data - A value that should be encrypted, encoded as a Vec<u8>

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = serde_json::to_vec(&json!({
    "some": "data",
}))?;

let encrypted = store_cipher.encrypt_value_base64_data(value.clone())?;
let decrypted = store_cipher.decrypt_value_base64_data(encrypted)?;

assert_eq!(value, decrypted);

pub fn decrypt_value<T: DeserializeOwned>( &self, value: &[u8], ) -> Result<T, Error>

Decrypt a value after it was fetched from the key/value store.

A value can be encrypted using the StoreCipher::encrypt_value() method.

Arguments

• value - The ciphertext of a value that should be decrypted.

The method will deserialize the decrypted value into the expected type.

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = json!({
    "some": "data",
});

let encrypted = store_cipher.encrypt_value(&value)?;
let decrypted: Value = store_cipher.decrypt_value(&encrypted)?;

assert_eq!(value, decrypted);

pub fn decrypt_value_base64_data( &self, value: EncryptedValueBase64, ) -> Result<Vec<u8>, Error>

Decrypt a base64-encoded value after it was fetched from the key/value store.

A value can be encrypted using the StoreCipher::encrypt_value_base64_data() method.

Arguments

• value - The EncryptedValueBase64 of a value that should be decrypted.

The method will return the raw decrypted value

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = serde_json::to_vec(&json!({
    "some": "data",
}))?;

let encrypted = store_cipher.encrypt_value_base64_data(value.clone())?;
let decrypted = store_cipher.decrypt_value_base64_data(encrypted)?;

assert_eq!(value, decrypted);

pub fn decrypt_value_data( &self, value: EncryptedValue, ) -> Result<Vec<u8>, Error>

Decrypt a value after it was fetched from the key/value store.

A value can be encrypted using the StoreCipher::encrypt_value_data() method. Lower level method to StoreCipher::decrypt_value().

Arguments

• value - The EncryptedValue of a value that should be decrypted.

The method will return the raw decrypted value

Examples

use matrix_sdk_store_encryption::StoreCipher;
use serde_json::{json, value::Value};

let store_cipher = StoreCipher::new()?;

let value = serde_json::to_vec(&json!({
    "some": "data",
}))?;

let encrypted = store_cipher.encrypt_value_data(value.clone())?;
let decrypted = store_cipher.decrypt_value_data(encrypted)?;

assert_eq!(value, decrypted);