Expand description
§dig-session
The DIG session / keystore layer: a small, custody-safe facade that turns stored, encrypted key material into a live signer and injects a bare signing primitive into downstream consumers.
It composes two lower-level crates and adds no cryptography of its own:
dig_keystore— encrypted, per-scheme secret-key storage (Keystore::<K>::load -> unlock -> SignerHandle<K>, AES-256-GCM + Argon2id).dig_identity— the canonical DIG BLS identity derivation (master_secret_key_from_seedthenderive_identity_skat the hardened pathm/12381'/8444'/9'/0').
§What this crate deliberately does NOT do
There is no seal / decap (recipient message encryption) here. That
composition belongs to dig-message (the same 10-primitives level); adding
it here would duplicate a cross-repo contract and invite byte-drift. This
crate’s first cut is strictly unlock / sign / inject.
§Enrollment stores the derived key with L1WalletBls, not BlsSigning
The identity signing key is a key that dig-identity has already derived
(via EIP-2333 hardened steps). To reconstruct it on unlock byte-identically,
storage must use a scheme that round-trips raw secret-key bytes through
chia_bls::SecretKey::from_bytes — that is L1WalletBls.
BlsSigning instead treats its stored 32 bytes as a seed and runs them
through chia_bls::SecretKey::from_seed on every unlock. Storing an
already-derived key under BlsSigning would therefore re-derive a
different key (the documented dig_ecosystem #64 / #57 pitfall), and the
resulting public key would not match the DID-anchored identity key. So the
identity path uses L1WalletBls; a regression test asserts the unlocked
public key equals dig_identity::public_key_bytes(derive_identity_sk(master)).
Session::unlock stays generic over the scheme, so BlsSigning is still
available for seed-derived validator keys.
§Example
use std::sync::Arc;
use dig_session::{Session, FileBackend, BackendKey, Password};
let backend = Arc::new(FileBackend::new("/var/lib/dig/keys"));
let identity = Session::enroll_identity(
backend,
BackendKey::new("identity"),
Password::from("correct horse battery staple"),
b"BIP-39 seed bytes go here",
)?;
// Hand a downstream a bare signing primitive — it never sees a session type.
let sign = identity.signing_fn();
let _sig = sign(b"message");Structs§
- Backend
Key - An opaque key identifying a single encrypted blob within a backend.
- BlsSigning
- DIG validator BLS signing key (G1 pubkey / G2 signature on BLS12-381).
- File
Backend - Filesystem-backed keychain.
- L1Wallet
Bls - DIG/Chia L1 wallet master BLS key (the root of wallet HD derivation).
- Password
- A password used to unlock a
Keystore. - Public
Key - Secret
Key - Session
- Entry point for turning stored, encrypted key material into a live signer.
- Signature
- Unlocked
Identity - A live, in-memory identity whose secret key has been decrypted and is ready to sign.
- Unlocked
Master Seed - A live, in-memory account root whose BIP-39 entropy has been decrypted and is
ready to (a) reconstruct the wallet
MasterKeyapp-side, (b) derive the dig-identity signing key + profile DEK in-crate, and (c) render the 24-word recovery phrase for the user.
Enums§
- Session
Error - Errors returned by
crate::Sessionoperations.
Constants§
- ENTROPY_
LEN - The number of bytes of BIP-39 entropy behind a DIG account — the value actually stored at rest.
- IDENTITY_
PUBLIC_ KEY_ LEN - The number of bytes in a compressed BLS12-381 G1 identity public key.
- IDENTITY_
SIGNATURE_ LEN - The number of bytes in a BLS12-381 G2 AugScheme signature.
- MASTER_
SEED_ LEN - The number of bytes in an expanded BIP-39 master HD seed — the value fed to
chia_bls::SecretKey::from_seed. - RECOVERY_
PHRASE_ WORDS - The number of words in a DIG recovery phrase.
Traits§
- KeyScheme
- Trait implemented by every supported key scheme.
- Keychain
Backend - Storage backend trait. Implementations must be
Send + Sync + 'staticso they can be held behindArc<dyn KeychainBackend>.
Type Aliases§
- Identity
Signing Fn - A standalone identity-signing primitive: a plain callable mapping a message to a 96-byte G2 signature, carrying no dig-session or dig-identity type.
- Result
- Convenience alias for
Result<T, SessionError>. - Signing
Fn - A scheme-parameterized signing primitive: a plain callable that maps a message to a signature and carries no dig-session or dig-identity type.