Crate dig_keystore 

dig-keystore

Encrypted secret-key storage for DIG Network binaries.

Feature tiers

The crate splits into a machine-key core and a user-key custody tier. The core seals arbitrary bytes under a password and stores them; it has no notion of whose key it is. Custody models a user’s identity key: the typed Keystore<K: KeyScheme>, its schemes, and the SignerHandle<K> you get by unlocking one.

Feature	Default	Adds
file-backend	yes	FileBackend (filesystem storage)
os-keychain	no	OsKeychainBackend (Windows / macOS credential store)
custody	no	Keystore, SignerHandle, scheme::*
hd-derivation	no	SignerHandle::expose_secret (implies custody)
password-strength	no	Password::strength
testing	no	MemoryBackend + TEST_PASSWORD for dependents’ tests

custody is off by default so that a consumer needing only machine-key sealing — the DIG node engine, whose identity-agnostic boundary is dig_ecosystem #908 — cannot name the custody API. See SPEC.md §18, including the honest limits of that under Cargo feature unification.

The core surface is opaque (seal/open arbitrary-length secrets), backend, and the format/KDF/cipher types. Storage is abstracted behind the KeychainBackend trait; hardware-signer backends (Ledger / YubiHSM) plug into the same trait in future releases.

File format

DIGVK1 (BLS signing) and DIGLW1 (L1 wallet BLS) for typed custody keystores, DIGOP1 for opaque secrets. See SPEC.md §3 for the byte-level layout. Encryption is AES-256-GCM; key derivation is Argon2id (default 64 MiB / 3 iterations / 4 lanes).

Security properties

• AES-256-GCM authenticated encryption (tag integrity)
• Argon2id memory-hard KDF
• Zeroizing<...> wrappers on passwords, seeds, and derived keys
• Outer CRC32 for fast fail on bit-rot
• Atomic file writes (tmp + rename)

Minimal example

Requires the custody feature:

dig-keystore = { version = "0.8", features = ["custody"] }

use std::sync::Arc;
use dig_keystore::{
    Keystore, Password, KdfParams,
    scheme::BlsSigning,
    backend::{FileBackend, BackendKey, KeychainBackend},
};

let backend: Arc<dyn KeychainBackend> = Arc::new(FileBackend::new("/var/dig/keys"));
let key = BackendKey::new("validator_bls");
let password = Password::from("correct horse battery staple");

// Create
let ks = Keystore::<BlsSigning>::create(
    backend.clone(),
    key.clone(),
    password.clone(),
    None,                          // generate a fresh seed
    KdfParams::default(),
)?;

// Unlock + sign
let signer = ks.unlock(password)?;
let sig = signer.sign(b"message");
let pk = signer.public_key();

Re-exports

pub use backend::FileBackend;

pub use backend::MemoryBackend;

pub use backend::OsKeychainBackend;

pub use backend::BackendKey;

pub use backend::KeychainBackend;

pub use hardware::DegradeReason;

pub use hardware::HardwareBoundBackend;

pub use hardware::HardwareKind;

pub use hardware::HardwarePolicy;

pub use hardware::HardwareProbe;

pub use hardware::HardwareProvider;

pub use hardware::KeyCustody;

pub use hardware::ProtectionTier;

Modules

backend

Storage backend abstraction.

bls

Convenience re-exports of the chia-bls types used by the BLS schemes.

hardware

Hardware binding for at-rest key material.

opaque

Opaque secret sealing — password-encrypts arbitrary-length secret bytes.

scheme

Key schemes: the typed layer that defines how raw secret bytes become usable keys, public keys, and signatures.

testing

Testing helpers for dependent crates — only compiled under the testing feature.

Structs

BlsSigning

DIG validator BLS signing key (G1 pubkey / G2 signature on BLS12-381).

KdfParams

Parameters for the key derivation function.

Keystore

A typed, encrypted keystore.

KeystoreHeader

Parsed file header.

L1WalletBls

DIG/Chia L1 wallet master BLS key (the root of wallet HD derivation).

Password

A password used to unlock a Keystore.

SignerHandle

The unlocked handle. Drop wipes the secret.

Enums

CipherId

Identifies the symmetric cipher used.

KdfId

Identifies the key derivation function used.

KeystoreError

Errors produced by keystore operations.

Constants

FORMAT_VERSION_V1

File format version supported by this library.

Traits

KeyScheme

Trait implemented by every supported key scheme.

Type Aliases

Result

Result alias used throughout the crate.