Skip to main content

FileBackend

Struct FileBackend 

Source
pub struct FileBackend { /* private fields */ }
Expand description

Filesystem-backed keychain.

Thread-safe — KeychainBackend is Send + Sync, and all operations use OS-level atomic primitives (rename, unlink). Multiple FileBackend instances pointing at the same root directory coexist without mutual serialization; the tmp-file names include a random suffix so concurrent writes to the same BackendKey do not step on each other’s tmp files.

§Example

use std::sync::Arc;
use dig_keystore::{
    backend::{FileBackend, BackendKey, KeychainBackend},
};

let backend: Arc<dyn KeychainBackend> = Arc::new(
    FileBackend::new("/var/lib/dig/keys")
);
backend.write(&BackendKey::new("v1"), b"...").unwrap();

Implementations§

Source§

impl FileBackend

Source

pub fn new(root: impl Into<PathBuf>) -> FileBackend

Create a new file backend rooted at root.

The directory is not created immediately — it is lazily created on the first write call (with mode 0700 on Unix). This lets callers construct a FileBackend in tests without side effects; no files are written until the first write.

§Example
use dig_keystore::backend::FileBackend;
let be = FileBackend::new("/var/lib/dig/keys");
let _ = be;  // directory not created yet
Source

pub fn root(&self) -> &Path

The root directory this backend writes to.

Trait Implementations§

Source§

impl KeychainBackend for FileBackend

Source§

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

Read the entire file at <root>/<key>.dks.

Returns KeystoreError::Backend wrapping an io::Error with ErrorKind::NotFound if the file does not exist.

Source§

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

Atomically write data to <root>/<key>.dks.

Steps:

  1. Ensure root exists, is a directory rather than a symlink, and is verified owner-only.
  2. Create sibling <key>.dks.tmp.<random> file with mode 0600 requested in the open(2) call on Unix, then verify the mode that actually took effect before any bytes are written — so a root that cannot hold key material safely yields KeystoreError::InsecurePermissions and an empty, removed tmp file rather than an exposed blob.
  3. Write data, fsync the file handle.
  4. rename the tmp file onto the final name.
  5. On Unix, fsync the containing directory so the rename is durable.
  6. On error in step 4, best-effort unlink the tmp file.

The random suffix in step 2 is not cryptographic — it exists only to disambiguate two concurrent writes to the same key from the same process. Uses a hash of (nanoseconds_since_epoch, pid).

Source§

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

Best-effort secure delete, then unlink.

Steps:

  1. No-op if the file is confidently absent (idempotent); refuses if its presence could not be determined, rather than reporting a completed erase over a blob that may still be there.
  2. Open the file for writing; overwrite with zeros in 4 KiB chunks.
  3. fsync the overwritten file so zeros hit storage.
  4. unlink the file.

Step 2 is best-effort. On SSDs with flash translation layer or on copy-on-write filesystems (btrfs, ZFS), the zero pass may not reach the sectors that held the ciphertext. Use full-disk encryption for stronger guarantees.

Source§

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

Enumerate keys whose names start with prefix.

Scans the root directory; skips any file that:

  • does not end in .dks
  • has a non-UTF-8 name
  • does not start with prefix

Returns an empty vec if the root directory is confidently absent, and an error if it could not be inspected at all — the same three-valued contract exists keeps, for the same reason.

Source§

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

Stat the path without opening it, preserving the trait’s three-valued contract: present, confidently absent, or could not determine.

Uses symlink_metadata rather than Path::exists() or try_exists(). Path::exists() maps every error to false, which turns an inspection failure into a confident negative — and the caller uses that answer to decide whether to mint over a write that replaces.

symlink_metadata is also the stricter of the two honest options: it does not follow links, so a dangling symlink at the key path counts as present. Something occupies that name; refusing to write over it is the fail-closed reading, whereas try_exists() would report false and invite exactly the overwrite this method exists to prevent.

Source§

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

Establish <root>/<key>.dks only if it does not already exist.

Exclusivity comes from the OS: the file is opened with create_new, so exactly one racer creates it and every other gets KeystoreError::AlreadyExists — a distinguishable error the loser can adopt on, rather than a generic I/O failure it can only give up on.

§Why this does not use tmp + rename

rename always replaces, so it cannot express “only if absent”; the two guarantees are not simultaneously available without a hard link, which not every filesystem supports. Exclusivity is the one that matters here, and the cost is bounded: a crash mid-write leaves a short file, which the format’s magic, length and CRC all detect on the next read (SPEC.md §3.2), and which is repaired by deleting it and retrying. The state this method exists to prevent — a coupled pair that settled mismatched — is neither detectable nor repairable. A best-effort unlink removes the partial file on the way out of any failure.

Source§

fn write_new_exclusivity(&self) -> Exclusivity

create_new(true) is an atomic create-if-absent at the OS level, so two concurrent calls cannot both succeed.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> Conv for T

Source§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
Source§

impl<T> FmtForward for T

Source§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
Source§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
Source§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
Source§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
Source§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
Source§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
Source§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
Source§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
Source§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Pipe for T
where T: ?Sized,

Source§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
Source§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
Source§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
Source§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
Source§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
Source§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
Source§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
Source§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
Source§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> Tap for T

Source§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
Source§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
Source§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
Source§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
Source§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
Source§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
Source§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
Source§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
Source§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
Source§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
Source§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
Source§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
Source§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
Source§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
Source§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
Source§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
Source§

impl<T> TryConv for T

Source§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V