Expand description
Platform trusted-component providers for dig_keystore.
dig-keystore defines the HardwareProvider seam and the DIGHW1
envelope, but ships no binding to real silicon: it sets
unsafe_code = "forbid" as a spec-pinned security property (SPEC.md
§12/§13.2, conformance C-15), and every platform trusted-component API is
FFI. This crate is where that FFI lives, so the forbid stays intact in the
crate that holds the key material.
§What this buys
A wrapping key created inside the host trusted component and non-exportable
from it, so copying a sealed keystore to another machine does not let an
attacker open it. That property, and only that property, is what a
ProtectionTier::Hardware
claim means.
§The ladder, and why it is the part that matters
| rung | protection | where |
|---|---|---|
| 1 | host trusted component, non-exportable wrapping key | this crate |
| 2 | OS credential store | dig_keystore::OsKeychainBackend |
| 3 | AES-256-GCM + Argon2id passphrase envelope — the floor | dig_keystore |
Rung 3 is never skipped. Hardware wrapping is an outer envelope around an already-sealed blob, so a host with no trusted component writes exactly the bytes it always wrote — never a bare file.
Most hosts, and every CI runner, land below rung 1. So ladder — the
decision about which rung, and the reason recorded for landing below the top
— is the code that actually runs everywhere, and it is tested on every host
through the provider seam. See ladder for how those fixtures are built.
§Platform status, stated plainly
| platform | status |
|---|---|
| Windows | implemented — TPM 2.0 through the CNG Microsoft Platform Crypto Provider ([platform::windows]) |
| macOS on Apple silicon | implemented — Secure Enclave P-256 + ECIES ([platform::macos]) |
| macOS on Intel | not implemented — a T2 may or may not be present and this build cannot tell |
| Linux | implemented — TPM 2.0 over the kernel resource manager (platform::linux) |
An unimplemented platform degrades to rung 2/3 and says so with a reason
naming this build, never as NoHardwarePresent: that would be a confident
claim about the machine, and nothing here inspected it.
What the two new providers have and have not been proven against. Both
compile under their target, and their classification, custody and refusal
logic is tested through the HardwareProvider seam on every CI leg. Neither
has run against real silicon — no Mac and no TPM-bearing Linux host was
available — so the wrap/unwrap path on those two platforms is the one part of
this crate that rests on the specification rather than on an observation. The
outstanding evidence is named in SPEC.md §17.5.
§Example
use dig_keystore::backend::FileBackend;
use dig_keystore::hardware::HardwarePolicy;
// Strongest available tier for this host, honestly reported.
let backend = dig_keystore_hardware::bind_strongest(
FileBackend::new("/var/lib/dig/keys"),
HardwarePolicy::Preferred,
)?;
println!("this host: {}", backend.tier());Re-exports§
pub use ladder::walk;pub use ladder::Attempt;pub use ladder::AttemptOutcome;pub use ladder::Rung;
Modules§
- ladder
- The degrade ladder: walk candidate trusted components in preference order and settle on the strongest one that is proven, not merely claimed.
- platform
- Per-platform trusted-component bindings, and the honest answer where there is none.
Functions§
- bind_
strongest - Wrap
innerin the strongest protection tier this host can actually prove, degrading honestly. - bind_
strongest_ from - As
bind_strongest, with the candidate list supplied by the caller. - platform_
candidates - The trusted-component candidates available on this host, in preference order.