Skip to main content

Crate dig_session

Crate dig_session 

Source
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_seed then derive_identity_sk at the hardened path m/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§

BackendKey
An opaque key identifying a single encrypted blob within a backend.
BlsSigning
DIG validator BLS signing key (G1 pubkey / G2 signature on BLS12-381).
FileBackend
Filesystem-backed keychain.
L1WalletBls
DIG/Chia L1 wallet master BLS key (the root of wallet HD derivation).
Password
A password used to unlock a Keystore.
PublicKey
SecretKey
Session
Entry point for turning stored, encrypted key material into a live signer.
Signature
UnlockedIdentity
A live, in-memory identity whose secret key has been decrypted and is ready to sign.
UnlockedMasterSeed
A live, in-memory account root whose BIP-39 entropy has been decrypted and is ready to (a) reconstruct the wallet MasterKey app-side, (b) derive the dig-identity signing key + profile DEK in-crate, and (c) render the 24-word recovery phrase for the user.

Enums§

SessionError
Errors returned by crate::Session operations.

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.
KeychainBackend
Storage backend trait. Implementations must be Send + Sync + 'static so they can be held behind Arc<dyn KeychainBackend>.

Type Aliases§

IdentitySigningFn
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>.
SigningFn
A scheme-parameterized signing primitive: a plain callable that maps a message to a signature and carries no dig-session or dig-identity type.