Skip to main content

Crate db_keystore

Crate db_keystore 

Source
Expand description

File-backed credential store using Turso (sqlite) and optional encryption.

This module implements the keyring_core::api::CredentialStoreApi and keyring_core::api::CredentialApi traits, so it can be used wherever a keyring_core::api::CredentialStore is expected (for example via use_named_store_with_modifiers).

Features:

  • Local sqlite storage with optional encryption options.
  • Verified out-of-place rekey (DEK rotation) with safe destination creation and typed errors, plus standalone verification of two existing keystores (DbKeyStore::verify): see the rekey module.
  • WAL + busy timeout for better multi-process behavior.
  • Multi-process file sharing: the file-backed store opens the database per operation and closes it immediately afterward, so turso’s exclusive file lock is held only for the duration of each operation. Long-lived processes (daemons) and short-lived CLI invocations can share one keystore file; concurrent opens are handled by retry with backoff.
  • Optional uniqueness enforcement on (service, user) via allow_ambiguity=false.
  • UUID and optional comment attributes exposed via the credential API.
  • Search supports service, user, uuid, and comment regex filters.

Modifiers supported by new_with_modifiers:

  • path : path to the sqlite database file. Defaults to $XDG_STATE_HOME/keystore.db or $HOME/.local/state/keystore.db
  • encryption-cipher / cipher: encryption cipher name (optional, requires hexkey).
  • encryption-hexkey / hexkey: encryption key as hex (optional, requires cipher).
  • allow-ambiguity / allow_ambiguity: "true" or "false" (default "false").
  • vfs: optional VFS backing selection ("memory", "io_uring", or "syscall").
  • index-always / index_always: "true" or "false" (default "false").

Modifiers supported by build:

  • uuid: explicit credential UUID (allows creating ambiguous entries when allowed).
  • comment: initial comment value stored with the credential.

Uuid are generated in v7 format https://www.ietf.org/rfc/rfc9562.html#section-5.7. Uuids generated by this crate will be unique (on a per-process basis), and sortable by time, so ambiguous entries can be sorted by date created, if desired. Uuids generated externally, and passed to build() are validated against the string syntax (e.g., f81d4fae-7dec-11d0-a765-00a0c91e6bf6), but are not checked for uniqueness or order.

Example:

use std::collections::HashMap;
use db_keystore::{DbKeyStore, DbKeyStoreConfig};

// create from config
let config = DbKeyStoreConfig {
    path: "keystore.db".into(),
    ..Default::default()
};
let store = DbKeyStore::new(config).expect("store");

// or, create with modifiers
let modifiers = HashMap::from([
    ("path", "keystore.db"),
    ("allow-ambiguity", "true"),
]);
let store = DbKeyStore::new_with_modifiers(&modifiers).expect("store");

Re-exports§

pub use rekey::RekeyError;
pub use rekey::RekeyOutcome;
pub use rekey::SensitiveKey;
pub use rekey::rekey_at;
pub use rekey::verify_at;

Modules§

rekey
Out-of-place rekey (DEK rotation) with exact verification, safe destination creation, and typed errors.

Structs§

DbKeyStore
DbKeyStoreConfig
Configure turso database
EncryptionOpts
EncryptionOpts selects the cipher and key for on-disk encryption. See https://docs.turso.tech/tursodb/encryption Example ciphers: “aegis256”, “aes256gcm”. For 256-bit keys, hexkey is 64 chars.

Functions§

default_path
Default path for keystore: $XDG_STATE_HOME/keystore.db or $HOME/.local/state/keystore.db