Struct SealedFileMlsStorage 

pub struct SealedFileMlsStorage { /* private fields */ }

MLS storage in files, every record sealed under a key derived from the operator’s store key.

This is the headless host’s stand-in for the platform keystore the mobile bindings use. What it protects against is someone who can read the directory but does not have the store key: a copied disk, a backup, another local user. Against that reader:

• Values are sealed. ChaCha20-Poly1305 under a key derived with HKDF from the store key and the account namespace, so a record copied into another account’s directory does not open.
• Keys are sealed too. The record’s (key_type, key_id) travels inside the ciphertext, and file names are an HMAC under a second derived key. A listing reveals how many records of each kind exist, never which peers or groups they belong to. (The protocol-state store’s names are an unsalted digest, a format shared with the bindings.)
• A record is bound to its slot. The associated data is the file name, and the decrypted header must name the key asked for, so a record moved onto another’s name does not open.

What it cannot protect against is the store key itself. It arrives from a StoreKeyProvider, and on a host without a keystore that means in the clear from the operator’s configuration (residual risk R18).

A record that does not authenticate is reported as StorageError::CorruptedData, naming its file, and left in place. The store never deletes on a read, because the common cause is a wrong key and deleting on that would destroy the identity. Self::open checks the key against a sealed check file first and refuses a wrong one before any record is read, so a record that fails afterwards is damaged: the error names the file, and what deleting it costs depends on what it held (the engine regenerates a damaged protocol-state record key by itself).

Implementations

impl SealedFileMlsStorage

pub fn open( root: impl AsRef<Path>, namespace: &str, provider: &dyn StoreKeyProvider, ) -> Result<Self, FileStoreError>

Opens (creating if needed) the store at <root>/<namespace>/, sealed under the key provider supplies.

The provider is asked once. The first open writes a sealed check file; every later open must open it, and a key that does not is refused with FileStoreError::WrongStoreKey before any record is read or changed. A check file that is missing or damaged is rebuilt only when an existing record opens under the key, which proves it. A check that does not open over a store with no records is refused with FileStoreError::KeyCheckUnverifiable, which names the check file.

A second store over the same directory is refused with FileStoreError::InUse until this one is closed or dropped.

root should be a directory that survives an upgrade: this store holds the device’s identity, and losing it gives the device a new address.

Examples found in repository

examples/replicated_notes.rs (line 52)

fn open_stores(
    root: &std::path::Path,
    key: &dyn StoreKeyProvider,
) -> Result<(Arc<SealedFileMlsStorage>, Arc<FileProtocolStateStorage>), Box<dyn std::error::Error>>
{
    let namespace = account_storage_namespace(APP_ID, PROFILE);
    // Two roots: MLS material may outlive an installation, protocol state
    // must not.
    let secure = SealedFileMlsStorage::open(root.join("keys"), &namespace, key)?;
    let records = FileProtocolStateStorage::open(root.join("state"), &namespace)?;
    Ok((Arc::new(secure), Arc::new(records)))
}

pub fn directory(&self) -> &Path

The directory this store owns.

pub fn close(&self)

Releases the directory and refuses every later operation.

The lock goes at once, whoever still holds the store: an engine that was handed it, a host object its runtime has not freed yet. An operation in flight finishes first. Afterwards every operation is an error naming the directory, and a new store may open over it. Closing twice is closing once.

pub fn holds_records( root: impl AsRef<Path>, namespace: &str, ) -> Result<bool, FileStoreError>

Whether <root>/<namespace>/ holds MLS records, without opening, creating or locking anything.

A record file, not the directory and not a type directory. An open refused after the account directory was made (a wrong key, a protocol-state root that could not be created) leaves the directory, its lock file and its key check, and no identity. A first write that failed (a full disk, a crash) leaves a type directory with nothing in it but a temporary. A directory that cannot be read, at either level, is an FileStoreError::Io, never “no records”.

Trait Implementations

impl Debug for SealedFileMlsStorage

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

Formats the value using the given formatter.

impl MlsStorage for SealedFileMlsStorage

fn store(&self, key_type: &str, key_id: &str, data: &[u8]) -> StorageResult<()>

Stores data with the given key type and ID.

fn load(&self, key_type: &str, key_id: &str) -> StorageResult<Option<Vec<u8>>>

Loads data for the given key type and ID.

fn delete(&self, key_type: &str, key_id: &str) -> StorageResult<()>

Deletes data for the given key type and ID.

fn list_keys(&self, key_type: &str) -> StorageResult<Vec<String>>

Lists all key IDs for a given key type.

fn exists(&self, key_type: &str, key_id: &str) -> Result<bool, StorageError>

Checks if a key exists.

fn clear_type(&self, key_type: &str) -> Result<(), StorageError>

Clears all data of a given key type.