dig_keystore_hardware/lib.rs
1//! Platform trusted-component providers for [`dig_keystore`].
2//!
3//! `dig-keystore` defines the [`HardwareProvider`] seam and the `DIGHW1`
4//! envelope, but ships no binding to real silicon: it sets
5//! `unsafe_code = "forbid"` as a spec-pinned security property (`SPEC.md`
6//! §12/§13.2, conformance C-15), and every platform trusted-component API is
7//! FFI. This crate is where that FFI lives, so the forbid stays intact in the
8//! crate that holds the key material.
9//!
10//! # What this buys
11//!
12//! A wrapping key created inside the host trusted component and **non-exportable
13//! from it**, so copying a sealed keystore to another machine does not let an
14//! attacker open it. That property, and only that property, is what a
15//! [`ProtectionTier::Hardware`](dig_keystore::hardware::ProtectionTier::Hardware)
16//! claim means.
17//!
18//! # The ladder, and why it is the part that matters
19//!
20//! | rung | protection | where |
21//! |---|---|---|
22//! | 1 | host trusted component, non-exportable wrapping key | this crate |
23//! | 2 | OS credential store | `dig_keystore::OsKeychainBackend` |
24//! | 3 | AES-256-GCM + Argon2id passphrase envelope — **the floor** | `dig_keystore` |
25//!
26//! Rung 3 is never skipped. Hardware wrapping is an outer envelope around an
27//! already-sealed blob, so a host with no trusted component writes exactly the
28//! bytes it always wrote — never a bare file.
29//!
30//! Most hosts, and every CI runner, land below rung 1. So [`ladder`] — the
31//! decision about *which* rung, and the reason recorded for landing below the top
32//! — is the code that actually runs everywhere, and it is tested on every host
33//! through the provider seam. See [`ladder`] for how those fixtures are built.
34//!
35//! # Platform status, stated plainly
36//!
37//! | platform | status |
38//! |---|---|
39//! | Windows | **implemented** — TPM 2.0 through the CNG *Microsoft Platform Crypto Provider* ([`platform::windows`]) |
40//! | macOS on Apple silicon | **implemented** — Secure Enclave P-256 + ECIES ([`platform::macos`]) |
41//! | macOS on Intel | **not implemented** — a T2 may or may not be present and this build cannot tell |
42//! | Linux | **implemented** — TPM 2.0 over the kernel resource manager ([`platform::linux`]) |
43//!
44//! An unimplemented platform degrades to rung 2/3 and **says so with a reason
45//! naming this build**, never as `NoHardwarePresent`: that would be a confident
46//! claim about the machine, and nothing here inspected it.
47//!
48//! **What the two new providers have and have not been proven against.** Both
49//! compile under their target, and their classification, custody and refusal
50//! logic is tested through the [`HardwareProvider`] seam on every CI leg. Neither
51//! has run against real silicon — no Mac and no TPM-bearing Linux host was
52//! available — so the wrap/unwrap path on those two platforms is the one part of
53//! this crate that rests on the specification rather than on an observation. The
54//! outstanding evidence is named in `SPEC.md` §17.5.
55//!
56//! # Example
57//!
58//! ```no_run
59//! use dig_keystore::backend::FileBackend;
60//! use dig_keystore::hardware::HardwarePolicy;
61//!
62//! // Strongest available tier for this host, honestly reported.
63//! let backend = dig_keystore_hardware::bind_strongest(
64//! FileBackend::new("/var/lib/dig/keys"),
65//! HardwarePolicy::Preferred,
66//! )?;
67//! println!("this host: {}", backend.tier());
68//! # Ok::<(), dig_keystore::KeystoreError>(())
69//! ```
70
71#![warn(missing_docs)]
72
73use std::sync::Arc;
74
75use dig_keystore::backend::KeychainBackend;
76use dig_keystore::hardware::{
77 degrade_under, HardwareBoundBackend, HardwarePolicy, HardwareProvider,
78};
79use dig_keystore::Result;
80
81pub mod ladder;
82pub mod platform;
83
84pub use ladder::{walk, Attempt, AttemptOutcome, Rung};
85
86/// The trusted-component candidates available on this host, in preference order.
87///
88/// Returns an empty slice on a platform this build has no provider for. That is
89/// distinct from "this machine has no trusted component" and is reported as such
90/// — see [`platform`].
91pub fn platform_candidates() -> Vec<Arc<dyn HardwareProvider>> {
92 platform::candidates()
93}
94
95/// Wrap `inner` in the strongest protection tier this host can actually prove,
96/// degrading honestly.
97///
98/// Walks [`platform_candidates`] through [`ladder::walk`], then hands the winner
99/// — or nothing — to [`HardwareBoundBackend`]. `inner` supplies rungs 2 and 3:
100/// pass `OsKeychainBackend` where a credential store is wanted underneath, or
101/// `FileBackend` for the passphrase-envelope floor.
102///
103/// # Errors
104///
105/// Per `policy`, and only from the ladder settling: `Required` refuses any
106/// software tier, and the default `Preferred` refuses to open when a candidate
107/// could not be inspected at all — rather than downgrading that into an absence.
108pub fn bind_strongest<B: KeychainBackend>(
109 inner: B,
110 policy: HardwarePolicy,
111) -> Result<HardwareBoundBackend> {
112 // A platform this build has no binding for is reported as such. Falling
113 // through to `bind_strongest_from` with an empty list would settle on
114 // `NotRequested` — "nobody asked" — when the truth is that nobody could
115 // answer. The distinction is what an operator acts on.
116 if let Some(reason) = platform::unsupported_reason() {
117 // Apply the policy to that reason first, so `Required` still refuses.
118 let _ = degrade_under(reason.clone(), policy)?;
119 return Ok(HardwareBoundBackend::degraded(inner, reason));
120 }
121 bind_strongest_from(inner, &platform_candidates(), policy)
122}
123
124/// As [`bind_strongest`], with the candidate list supplied by the caller.
125///
126/// The seam that makes the composition testable without hardware, and the way a
127/// consumer injects a provider this crate does not ship.
128///
129/// # Errors
130///
131/// As [`bind_strongest`].
132pub fn bind_strongest_from<B: KeychainBackend>(
133 inner: B,
134 candidates: &[Arc<dyn HardwareProvider>],
135 policy: HardwarePolicy,
136) -> Result<HardwareBoundBackend> {
137 let rung = ladder::walk(candidates, policy)?;
138 let settled = rung.tier().degrade_reason().cloned();
139 match rung.into_provider() {
140 // Re-resolved by the backend rather than asserted from here, so that ONE
141 // authority owns every `Hardware` claim in the system — a claim asserted
142 // from outside that authority is exactly the kind nobody re-checks.
143 //
144 // `policy` is passed through, and that is load-bearing rather than tidy.
145 // The second resolution re-probes and re-runs the wrap/unwrap self-test
146 // against LIVE hardware, so it is an independent chance to fail, not
147 // redundant work: a TPM contended by BitLocker, Credential Guard or
148 // Windows Hello can refuse the round-trip it had just passed. Handing
149 // that resolution a weaker policy than the caller's would let it fail
150 // OPEN — `Required` would return `Ok` over a refuted self-test, and
151 // `Preferred` would downgrade an uninspectable device into an absence,
152 // which is precisely the outcome `degrade_under` exists to refuse.
153 //
154 // Applying the policy twice is idempotent: `walk` has already errored
155 // under `Required` on every non-hardware settle, so this only closes the
156 // second resolution's hole.
157 Some(provider) => HardwareBoundBackend::new(inner, Some(provider), policy),
158 // The ladder already applied `policy` and established the reason; carry
159 // that reason through instead of letting the backend re-derive a
160 // caller-shaped `NotRequested` from the missing provider.
161 None => Ok(HardwareBoundBackend::degraded(
162 inner,
163 settled.unwrap_or(dig_keystore::hardware::DegradeReason::NotRequested),
164 )),
165 }
166}
167
168#[cfg(test)]
169mod tests;