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§
Sourcefn read(&self, key: &BackendKey) -> Result<Vec<u8>, KeystoreError>
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.
Sourcefn write(&self, key: &BackendKey, data: &[u8]) -> Result<(), KeystoreError>
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.
Sourcefn write_new(&self, key: &BackendKey, data: &[u8]) -> Result<(), KeystoreError>
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.
Sourcefn delete(&self, key: &BackendKey) -> Result<(), KeystoreError>
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.
Sourcefn list(&self, prefix: &str) -> Result<Vec<BackendKey>, KeystoreError>
fn list(&self, prefix: &str) -> Result<Vec<BackendKey>, KeystoreError>
List keys that start with prefix. Order is unspecified.
Provided Methods§
Sourcefn write_new_exclusivity(&self) -> Exclusivity
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.
Sourcefn exists(&self, key: &BackendKey) -> Result<bool, KeystoreError>
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".