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.
  • WAL + busy timeout for better multi-process behavior.
  • 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");

Structs§

DbKeyStore
DbKeyStoreConfig
Configure turso database
EncryptionOpts
EncryptionOpts mirrors turso::EncryptionOpts 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