dig_keystore/
lib.rs

1//! # dig-keystore
2//!
3//! Encrypted secret-key storage for DIG Network binaries.
4//!
5//! Provides a typed `Keystore<K: KeyScheme>` over an encrypted on-disk blob. The
6//! storage layer is abstracted behind a `KeychainBackend` trait; `FileBackend`
7//! ships for filesystem persistence, `MemoryBackend` ships under the `testing`
8//! feature for dependent crates' tests. Hardware-signer backends (Ledger /
9//! YubiHSM) plug into the same trait in future releases.
10//!
11//! ## File format
12//!
13//! `DIGVK1` (BLS signing) and `DIGLW1` (L1 wallet BLS). See
14//! [`docs/resources/SPEC.md`](../../docs/resources/SPEC.md) for the byte-level
15//! layout. Encryption is AES-256-GCM; key derivation is Argon2id (default 64
16//! MiB / 3 iterations / 4 lanes).
17//!
18//! ## Security properties
19//!
20//! - AES-256-GCM authenticated encryption (tag integrity)
21//! - Argon2id memory-hard KDF
22//! - `Zeroizing<...>` wrappers on passwords, seeds, and derived keys
23//! - Outer CRC32 for fast fail on bit-rot
24//! - Atomic file writes (tmp + rename)
25//!
26//! ## Minimal example
27//!
28//! ```no_run
29//! use std::sync::Arc;
30//! use dig_keystore::{
31//!     Keystore, Password, KdfParams,
32//!     scheme::BlsSigning,
33//!     backend::{FileBackend, BackendKey, KeychainBackend},
34//! };
35//!
36//! # fn main() -> dig_keystore::Result<()> {
37//! let backend: Arc<dyn KeychainBackend> = Arc::new(FileBackend::new("/var/dig/keys"));
38//! let key = BackendKey::new("validator_bls");
39//! let password = Password::from("correct horse battery staple");
40//!
41//! // Create
42//! let ks = Keystore::<BlsSigning>::create(
43//!     backend.clone(),
44//!     key.clone(),
45//!     password.clone(),
46//!     None,                          // generate a fresh seed
47//!     KdfParams::default(),
48//! )?;
49//!
50//! // Unlock + sign
51//! let signer = ks.unlock(password)?;
52//! let sig = signer.sign(b"message");
53//! let pk = signer.public_key();
54//! # Ok(())
55//! # }
56//! ```
57
58#![deny(unsafe_code)]
59#![warn(missing_docs)]
60
61pub mod backend;
62mod cipher;
63mod error;
64mod format;
65mod kdf;
66mod keystore;
67mod password;
68pub mod scheme;
69mod signer;
70
71// Re-exports — the public surface.
72
73#[cfg(feature = "file-backend")]
74pub use backend::FileBackend;
75pub use backend::MemoryBackend;
76pub use backend::{BackendKey, KeychainBackend};
77
78pub use error::{KeystoreError, Result};
79pub use format::{CipherId, KdfId, KdfParams, KeystoreHeader, FORMAT_VERSION_V1};
80pub use keystore::Keystore;
81pub use password::Password;
82pub use scheme::{BlsSigning, KeyScheme, L1WalletBls};
83pub use signer::SignerHandle;
84
85// chia-bls re-exports so consumers don't need a direct dependency for simple cases.
86pub mod bls {
87    //! Convenience re-exports of the `chia-bls` types used by the BLS schemes.
88    pub use chia_bls::{sign, verify};
89    pub use chia_bls::{PublicKey, SecretKey, Signature};
90}
91
92#[cfg(feature = "testing")]
93pub mod testing {
94    //! Testing helpers for dependent crates — only compiled under the `testing` feature.
95    //!
96    //! Exports [`MemoryBackend`] and a constant [`TEST_PASSWORD`] so that
97    //! dependent crates can stand up disposable keystores in their own tests
98    //! without re-deriving Argon2 + AES-GCM boilerplate.
99
100    pub use crate::backend::MemoryBackend;
101
102    /// A fixed, well-known password for test fixtures.
103    pub const TEST_PASSWORD: &str = "dig-keystore-test-password";
104}
dig_keystore/lib.rs

dig_keystore/
lib.rs
