Skip to main content

KeychainBackend

Trait KeychainBackend 

Source
pub trait KeychainBackend:
    Send
    + Sync
    + 'static {
    // Required methods
    fn read(&self, key: &BackendKey) -> Result<Vec<u8>, KeystoreError>;
    fn write(&self, key: &BackendKey, data: &[u8]) -> Result<(), KeystoreError>;
    fn write_new(
        &self,
        key: &BackendKey,
        data: &[u8],
    ) -> Result<(), KeystoreError>;
    fn delete(&self, key: &BackendKey) -> Result<(), KeystoreError>;
    fn list(&self, prefix: &str) -> Result<Vec<BackendKey>, KeystoreError>;

    // Provided methods
    fn write_new_exclusivity(&self) -> Exclusivity { ... }
    fn exists(&self, key: &BackendKey) -> Result<bool, KeystoreError> { ... }
}
Expand description

Storage backend trait. Implementations must be Send + Sync + 'static so they can be held behind Arc<dyn KeychainBackend>.

Required Methods§

Source

fn read(&self, key: &BackendKey) -> Result<Vec<u8>, KeystoreError>

Read the full contents of the blob at key.

Returns a backend I/O error if the blob does not exist.

Source

fn write(&self, key: &BackendKey, data: &[u8]) -> Result<(), KeystoreError>

Write data to key. Implementations should be atomic — a reader seeing the key after this call must see either the old bytes or the new bytes in full, never a torn mix.

Source

fn write_new(&self, key: &BackendKey, data: &[u8]) -> Result<(), KeystoreError>

Write data to key only if nothing is stored there, returning KeystoreError::AlreadyExists otherwise.

This is the establish, not update, entry point. Use it whenever the write is meant to happen exactly once — see the crate-level coupled-records note for why that distinction is load-bearing and not a convenience.

Consult write_new_exclusivity before relying on it to make a coupled mismatch unreachable: not every store can offer create-if-absent as one indivisible step.

There is deliberately no default implementation. A default composed of exists then write would look like this contract while quietly providing none of it, and every backend that forgot to override it would inherit the race silently.

Source

fn delete(&self, key: &BackendKey) -> Result<(), KeystoreError>

Remove the blob at key. Implementations should best-effort overwrite the storage before removing so residual disk sectors do not retain the ciphertext.

Source

fn list(&self, prefix: &str) -> Result<Vec<BackendKey>, KeystoreError>

List keys that start with prefix. Order is unspecified.

Provided Methods§

Source

fn write_new_exclusivity(&self) -> Exclusivity

How strong write_new’s exclusivity is on this backend.

Defaults to Exclusivity::BestEffort so that a backend which has not considered the question understates rather than overstates what a consumer may rely on.

Source

fn exists(&self, key: &BackendKey) -> Result<bool, KeystoreError>

Whether a blob exists at key.

Three-valued, and it must stay that way. Ok(true) is present, Ok(false) is confidently absent, and Err is could not determine — an unreadable parent, a failing mount, an I/O fault. An implementation MUST NOT collapse the third answer into the second.

The reason is what callers do with it: this answer decides whether to mint. Since write replaces, a spurious false does not produce a harmless duplicate beside the original — it overwrites the original, and once that blob is hardware-wrapped (SPEC.md §17) the overwrite is unrecoverable. Refusing on an unanswerable read is therefore the fail-closed choice, and the only safe one.

The default impl delegates to read. Backends with a cheaper existence check may override, but the override inherits this contract — note that Path::exists() does not satisfy it, because it maps every error to false.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§