bookclerk_library::master_key
Data-encryption key (DEK) for encrypted_secrets.
Secrets in the DB are sealed with a random 32-byte DEK + per-row
XChaCha20-Poly1305 nonce (format sealed-v1). The DEK is not derived
per secret (no Argon2 on every load/save).
| Source | Behavior |
|---|---|
BOOKCLERK_AUTH_PASSWORD or [auth].password |
Wraps/unwraps the DEK in {files_dir}/master.key |
| Auto-mint | If neither password nor file exists, generates a DEK and writes master.key (mode 0600) |
| OS keychain | master.key is a BCK3 pointer naming a keychain item that holds the BCK1/BCK2 envelope |
The envelope (BCK1 or BCK2) lives either in master.key itself or in
one OS keychain item (bookclerk_keystore). On a keychain install
master.key holds a BCK3 pointer: the item's id and the DEK's SHA-256
fingerprint, never key bytes. Loading follows whatever master.key says
and fails closed: a missing item, a locked keychain or a key that doesn't
match the pointer's fingerprint is an error, never a fresh mint.
set_key_store_preference picks where a new key goes (a first mint,
a shared branch's installed key, an import); move_master_key moves an
existing one.
A later password can wrap an existing BCK1 file in place (CLI
config master-key wrap, config set auth.password, or daemon config
reload). The operator API token is independent and short-lived for
HTTP auth only. Rotating it does not re-encrypt library secrets.
Prefer a single opaque ciphertext blob per secret (not per-field columns): Audible envelopes are already opaque, updates stay atomic, and one unseal recovers the whole credential.
| Item | Kind | Summary |
|---|---|---|
KeyStorePreference |
struct | Where a new key goes, and whether that place is required. |
MasterKey |
struct | 32-byte data-encryption key (zeroized on drop). |
MasterKeyResolution |
struct | DEK loaded from master.key, plus whether this call created the file. |
StoredMasterKey |
struct | A key store_master_key placed, waiting for its master.key to be published. |
MasterKeyFormat |
enum | On-disk master.key envelope kind. |
set_key_store_preference |
function | Sets where this process writes new keys (first mint, a shared branch's installed key, an import). Existing keys stay where master.key says. |
key_store_preference |
function | The current store preference. |
set_keychain_vault |
function | Replaces the keychain this process uses, for tests (a bookclerk_keystore::MemoryVault) and for hosts that substitute their own store. |
set_systemd_creds_vault |
function | Replaces how this process builds its systemd-creds store, for tests (a fake tool, or a bookclerk_keystore::MemoryVault). |
master_key_path |
function | Path to {files_dir}/master.key. |
inspect_master_key |
function | Inspect the on-disk envelope without unlocking (missing → None). |
master_key_is_wrapped |
function | Whether the key is password-wrapped (BCK2), reading the keychain item when master.key is a pointer. None when there is no master.key. |
configure_master_key |
function | Load or mint the DEK and cache it for this process. |
configure_master_key_with |
function | Load or mint the DEK using an explicit password (env / config), then cache it. |
require_master_key |
function | Return the process-cached DEK, or resolve from files_dir if not configured. |
resolve_master_key |
function | Resolve the DEK from env + master.key (minting when needed). |
resolve_master_key_with |
function | Resolve the DEK with an explicit password override. |
resolve_master_key_detailed |
function | Resolve the DEK and report whether master.key was created by this call. |
master_key_fingerprint |
function | SHA-256 hex fingerprint of the unwrapped DEK. |
uncache_master_key |
function | Drops key from the process cache when it is the cached DEK. |
discard_minted_master_key |
function | Delete a master.key this process just created and drop it from the cache. |
wrap_master_key |
function | Wrap an existing BCK1 key with password (BCK2), in master.key or in the OS keychain item it points at. |
install_master_key |
function | Installs dek as {files_dir}/master.key: a shared branch joining a library receives the library's DEK (sealed to its node key, never the passphrase-wrapped file) and keeps it under its own password. |
prepare_master_key_dir |
function | Creates the directory that holds master.key and sets it to mode 0700 on Unix, as a first mint does. |
warn_unwrapped_master_key |
function | Warns that the master.key at path was written as BCK1 (the DEK unwrapped at rest), and how to wrap it. |
encode_master_key_file |
function | The key envelope for dek: BCK2 (Argon2id + XChaCha20-Poly1305) when password is set and non-empty after trimming, BCK1 otherwise. It touches no store; store_master_key places an envelope where the store preference says. |
store_master_key |
function | The bytes master.key must hold for dek, after putting the envelope where the key_store_preference says: the envelope itself for the file store, or a BCK3 pointer to the keychain item this call just wrote. A caller that stages the file itself (a shared branch applying its bootstrap as one recoverable step) writes these bytes with mode 0600. |
move_master_key |
function | Moves the existing key to to, keeping its bytes (and its password wrap) unchanged, so every sealed secret stays readable. |
master_key_envelope |
function | The key's envelope exactly as it is stored (BCK1, or BCK2 under the auth password), for an administrator who seals it into a unit credential themselves (systemd-creds encrypt --name=bookclerk-master-key on systemd older than 256, or a system-wide credential store). A systemd-creds move then adopts that credential instead of sealing its own copy, because the bytes match. |
export_master_key |
function | A recovery copy of the key: a BCK2 envelope wrapped with recovery_password, readable by import_master_key on any machine. |
import_master_key |
function | Restores a key from a recovery copy (export_master_key, or a copied master.key in BCK1/BCK2) on an install that has no master.key, placing it where the key_store_preference says. |
seal_with_dek |
function | Seal plaintext with the DEK (random nonce). Fast — no Argon2. |
unseal_with_dek |
function | Unseal ciphertext with the DEK. |
SystemdCredsFactory |
type alias | Builds the systemd-creds store for a files directory. |
AUTH_PASSWORD_ENV |
constant | Env var that wraps the DEK in master.key (optional). |
MASTER_KEY_FILE_NAME |
constant | Bootstrap key file under BOOKCLERK_FILES_DIR (auto-minted when missing). |
pub struct KeyStorePreference {
pub kind: KeyStoreKind,
pub required: bool,
}
Where a new key goes, and whether that place is required.
Fields
kind: The store new keys are written to.required: True when the operator set[auth].key_store: a keychain that can't be reached is then an error. False for a host's default, which falls back to the file with a warning.
pub fn from_config(configured: Option<KeyStoreKind>, default: KeyStoreKind) -> Self
The preference for configured ([auth].key_store), or the host's
default when unset.
configured- the operator's setting, if any.default- the host's default store.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct MasterKey {
/* private fields */
}
32-byte data-encryption key (zeroized on drop).
pub fn as_bytes(&self) -> &[u8; 32]
Returns the 32-byte DEK without copying.
Implements: Clone, Debug, Drop, Zeroize
pub struct MasterKeyResolution {
pub key: MasterKey,
pub minted: bool,
}
DEK loaded from master.key, plus whether this call created the file.
Fields
key: Unwrapped data-encryption key.minted: True when this call createdmaster.key(lost create races are false).
Implements: Clone
pub struct StoredMasterKey {
/* private fields */
}
A key store_master_key placed, waiting for its master.key to be
published.
pub fn bytes(&self) -> &[u8]
The bytes master.key must hold (write them with mode 0600).
pub fn store(&self) -> KeyStoreKind
The store the key went to: the file, or the store master.key
points at.
pub fn discard(self)
Deletes the store item again, for a caller whose master.key was
never published. Does nothing for a key kept in the file.
pub enum MasterKeyFormat {
Raw,
Wrapped,
Keychain,
SystemdCreds,
}
On-disk master.key envelope kind.
Variants
Raw: Raw 32-byte DEK (BCK1).Wrapped: Password-wrapped DEK (BCK2).Keychain: A pointer to an OS keychain item (BCK3); the item holdsBCK1orBCK2.SystemdCreds: A pointer to asystemd-credscredential (BCK4); the credential holdsBCK1orBCK2.
pub fn header(self) -> &'static str
The four-character header: BCK1, BCK2, BCK3 or BCK4.
pub fn store(self) -> KeyStoreKind
The store this format means.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn set_key_store_preference(preference: KeyStorePreference)
Sets where this process writes new keys (first mint, a shared branch's
installed key, an import). Existing keys stay where master.key says.
preference- the store and whether it is required.
pub fn key_store_preference() -> KeyStorePreference
The current store preference.
pub fn set_keychain_vault(vault: Arc<dyn Vault>)
Replaces the keychain this process uses, for tests (a
bookclerk_keystore::MemoryVault) and for hosts that substitute
their own store.
vault- the keychain to read and write items in.
pub fn set_systemd_creds_vault(factory: Arc<SystemdCredsFactory>)
Replaces how this process builds its systemd-creds store, for tests
(a fake tool, or a bookclerk_keystore::MemoryVault).
factory- builds the store for a files directory.
pub fn master_key_path(files_dir: &Path) -> PathBuf
Path to {files_dir}/master.key.
pub fn inspect_master_key(files_dir: &Path) -> Result<Option<MasterKeyFormat>>
Inspect the on-disk envelope without unlocking (missing → None).
Returns an error when the operation fails.
pub fn master_key_is_wrapped(files_dir: &Path) -> Result<Option<bool>>
Whether the key is password-wrapped (BCK2), reading the keychain item
when master.key is a pointer. None when there is no master.key.
Returns an error when master.key or the item it names can't be read.
pub fn configure_master_key(files_dir: &Path) -> Result<MasterKey>
Load or mint the DEK and cache it for this process.
Password comes from BOOKCLERK_AUTH_PASSWORD only. Prefer
configure_master_key_with when [auth].password may apply.
Call once at CLI/daemon startup after paths.ensure_dirs().
Returns an error when the operation fails.
pub fn configure_master_key_with(
files_dir: &Path,
password: Option<&str>,
) -> Result<MasterKey>
Load or mint the DEK using an explicit password (env / config), then cache it.
When password is set and master.key is still BCK1, re-wraps to BCK2
in place (same DEK bytes — sealed ciphertext stays valid). Empty password
is treated as absent.
If the resolved DEK identity differs from the previously cached one (e.g. a
replaced master.key), the plaintext unseal cache is flushed so callers
cannot observe stale plaintext under the new key.
Returns an error when the operation fails.
pub fn require_master_key(files_dir: Option<&Path>) -> Result<MasterKey>
Return the process-cached DEK, or resolve from files_dir if not configured.
Returns an error when the operation fails.
pub fn resolve_master_key(files_dir: &Path) -> Result<MasterKey>
Resolve the DEK from env + master.key (minting when needed).
Returns an error when the operation fails.
pub fn resolve_master_key_with(
files_dir: &Path,
password: Option<&str>,
) -> Result<MasterKey>
Resolve the DEK with an explicit password override.
Returns an error when the operation fails.
pub fn resolve_master_key_detailed(
files_dir: &Path,
password: Option<&str>,
) -> Result<MasterKeyResolution>
Resolve the DEK and report whether master.key was created by this call.
Returns an error when the file cannot be read, unwrapped, or created.
pub fn master_key_fingerprint(key: &MasterKey) -> String
SHA-256 hex fingerprint of the unwrapped DEK.
This identifies the library secret root. It is not a password hash: the passphrase, when set, is stretched with Argon2id before it unwraps this key. Wrapping changes the file bytes and leaves this fingerprint stable.
pub fn uncache_master_key(key: &MasterKey)
Drops key from the process cache when it is the cached DEK.
pub fn discard_minted_master_key(files_dir: &Path, key: &MasterKey) -> Result<()>
Delete a master.key this process just created and drop it from the cache.
Returns an error when the file exists and cannot be removed.
pub fn wrap_master_key(files_dir: &Path, password: &str) -> Result<MasterKey>
Wrap an existing BCK1 key with password (BCK2), in master.key
or in the OS keychain item it points at.
No-op (still unlocks) when already BCK2 and password is correct.
Fails if the file is missing — mint via configure_master_key_with first.
Returns an error when the operation fails.
pub fn install_master_key(
files_dir: &Path,
dek: &[u8],
password: Option<&str>,
) -> Result<()>
Installs dek as {files_dir}/master.key: a shared branch joining a library
receives the library's DEK (sealed to its node key, never the
passphrase-wrapped file) and keeps it under its own password.
Writes store_master_key's bytes (the envelope, or a pointer to the
keychain item it just wrote), mode 0600, replacing any
existing file atomically. The process cache is not changed: the daemon
restarts on the new bootstrap.
Returns an error when dek is not 32 bytes or the file cannot be
written.
pub fn prepare_master_key_dir(files_dir: &Path) -> Result<()>
Creates the directory that holds master.key and sets it to mode
0700 on Unix, as a first mint does.
Returns an error when the directory cannot be created or hardened.
pub fn warn_unwrapped_master_key(path: &Path)
Warns that the master.key at path was written as BCK1 (the DEK
unwrapped at rest), and how to wrap it.
pub fn encode_master_key_file(
dek: &[u8],
password: Option<&str>,
) -> Result<Zeroizing<Vec<u8>>>
The key envelope for dek: BCK2 (Argon2id + XChaCha20-Poly1305) when
password is set and non-empty after trimming, BCK1 otherwise. It
touches no store; store_master_key places an envelope where the store
preference says.
Returns LibraryError::Invalid when dek is not 32 bytes, and the
wrapping error.
pub fn store_master_key(
files_dir: &Path,
dek: &[u8],
password: Option<&str>,
) -> Result<StoredMasterKey>
The bytes master.key must hold for dek, after putting the envelope
where the key_store_preference says: the envelope itself for the
file store, or a BCK3 pointer to the keychain item this call just
wrote. A caller that stages the file itself (a shared branch applying
its bootstrap as one recoverable step) writes these bytes with mode
0600.
files_dir- the files directorymaster.keywill be written in (where asystemd-credscredential lives beside it).dek- the 32-byte data-encryption key.password- wraps the envelope asBCK2when set and non-empty.
Returns LibraryError::Invalid when dek is not 32 bytes, the
wrapping error, and a keychain failure when the keychain is required.
pub fn move_master_key(
files_dir: &Path,
to: KeyStoreKind,
password: Option<&str>,
) -> Result<MasterKeyFormat>
Moves the existing key to to, keeping its bytes (and its password
wrap) unchanged, so every sealed secret stays readable.
To the keychain or systemd-creds: writes a new item, reads it back,
replaces master.key with a pointer atomically, then deletes any item
the key was in before. To the file: writes the envelope over the pointer
atomically, reloads it, then deletes the old item. Moving to the store
the key is already in does nothing. Unlike starting a library, an
explicit move never falls back: a store that can't take the key is an
error.
files_dir- the files directory holdingmaster.key.to- the store to move to.password- the auth password, needed when the key is wrapped.
The format master.key has afterwards.
Returns an error when there is no key, it can't be unwrapped, or the target store can't take it. On error the key stays where it was.
pub fn master_key_envelope(
files_dir: &Path,
password: Option<&str>,
) -> Result<Zeroizing<Vec<u8>>>
The key's envelope exactly as it is stored (BCK1, or BCK2 under the
auth password), for an administrator who seals it into a unit
credential themselves (systemd-creds encrypt --name=bookclerk-master-key
on systemd older than 256, or a system-wide credential store). A
systemd-creds move then adopts that credential instead of sealing its
own copy, because the bytes match.
files_dir- the files directory holdingmaster.key.password- the auth password, needed when the key is wrapped (the envelope stays wrapped; the password only proves it opens).
Returns an error when there is no key or it can't be unwrapped.
pub fn export_master_key(
files_dir: &Path,
password: Option<&str>,
recovery_password: &str,
) -> Result<Zeroizing<Vec<u8>>>
A recovery copy of the key: a BCK2 envelope wrapped with
recovery_password, readable by import_master_key on any machine.
files_dir- the files directory holdingmaster.key.password- the auth password, needed when the key is wrapped.recovery_password- the password the recovery copy is wrapped with.
Returns an error when recovery_password is empty, or there is no key or
it can't be unwrapped.
pub fn import_master_key(
files_dir: &Path,
recovery: &[u8],
recovery_password: Option<&str>,
password: Option<&str>,
) -> Result<String>
Restores a key from a recovery copy (export_master_key, or a copied
master.key in BCK1/BCK2) on an install that has no master.key,
placing it where the key_store_preference says.
files_dir- the files directory to writemaster.keyin.recovery- the recovery copy's bytes.recovery_password- the password the copy is wrapped with, if it is.password- this install's auth password, which wraps the key at rest when set.
The SHA-256 hex fingerprint of the restored key.
Returns an error when master.key already exists, the copy can't be
unwrapped, or the key can't be stored.
pub fn seal_with_dek(plaintext: &[u8], dek: &MasterKey) -> Result<(Vec<u8>, Vec<u8>)>
Seal plaintext with the DEK (random nonce). Fast — no Argon2.
Returns an error when the operation fails.
pub fn unseal_with_dek(
ciphertext: &[u8],
nonce: &[u8],
dek: &MasterKey,
) -> Result<Vec<u8>>
Unseal ciphertext with the DEK.
Returns an error when the operation fails.
pub type SystemdCredsFactory = dyn Fn(&Path) -> Arc<dyn Vault> + Send + Sync;
Builds the systemd-creds store for a files directory.
pub const AUTH_PASSWORD_ENV: &str = "BOOKCLERK_AUTH_PASSWORD";
Env var that wraps the DEK in master.key (optional).
pub const MASTER_KEY_FILE_NAME: &str = "master.key";
Bootstrap key file under BOOKCLERK_FILES_DIR (auto-minted when missing).
Generated from crates/bookclerk-library at main · View as Markdown