Skip to main content

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;