hardware_enclave/
lib.rs

1// Copyright 2026 Jay Gowdy
2// SPDX-License-Identifier: MIT
3
4//! Hardware-backed key management and in-process memory protection.
5//!
6//! This crate provides two independently usable capability sets:
7//!
8//! ## Memory protection (`features = ["memory"]`)
9//!
10//! Available with `default-features = false, features = ["memory"]` — no platform
11//! HSM, no TPM, no Secure Enclave, no key storage. Only depends on `aes-gcm`,
12//! `rand`, `zeroize`, `sha2`, `libc`, and `subtle`.
13//!
14//! - [`SecureBuffer`] — guard-paged, mlock'd buffer; memory never swaps to disk
15//! - [`LockedBuffer`] — Arc-wrapped secret with global zeroize-on-shutdown registry
16//! - [`MemoryEnclave`] — AES-256-GCM sealed in-memory secret with hot-cache tier
17//! - [`TieredPool`] / [`pool_acquire`] — pool of locked memory slots for key material
18//! - [`harden_process`] — disable core dumps, restrict ptrace, set no-new-privs
19//!
20//! ```no_run
21//! use hardware_enclave::{harden_process, SecureBuffer, MemoryEnclave, init_pool};
22//!
23//! harden_process();
24//! init_pool(hardware_enclave::TieredPoolConfig::default())?;
25//! let buf = SecureBuffer::new(32)?; // 32 bytes, guard-paged
26//! let enc = MemoryEnclave::seal(b"secret key material")?;
27//! # Ok::<(), Box<dyn std::error::Error>>(())
28//! ```
29//!
30//! ## Hardware key management (`features = ["signing", "encryption"]`)
31//!
32//! ECDSA P-256 signing and ECIES P-256 encryption backed by the platform HSM
33//! (macOS Secure Enclave, Windows TPM 2.0, Linux TPM 2.0 / keyring). Keys never
34//! leave the hardware. User-presence enforcement (Touch ID, Windows Hello) built in.
35//!
36//! ```ignore
37//! // Requires `features = ["signing"]` (included in the default feature set).
38//! use hardware_enclave::{EnclaveConfig, create_signer, AccessPolicy};
39//!
40//! let config = EnclaveConfig::new("myapp", "default");
41//! let signer = create_signer(&config)?;
42//! let pubkey = signer.generate_key("default", AccessPolicy::Any)?;
43//! let sig = signer.sign("default", b"hello world")?;
44//! # Ok::<(), hardware_enclave::Error>(())
45//! ```
46//!
47//! # Memory pool initialization
48//! The global memory pool is lazily initialized on first use. For reliable startup-time
49//! error reporting, call [`init_pool()`] explicitly before using any [`MemoryEnclave`] or
50//! [`pool_acquire()`] operations.
51
52// ── Internal platform backends — only compiled with key management features ──
53#[cfg(any(feature = "signing", feature = "encryption"))]
54pub(crate) mod internal;
55
56// ── Always available: memory protection, error types, and process hardening ──
57pub mod error;
58pub mod hardening;
59pub mod memory;
60
61pub use error::{Error, Result};
62pub use hardening::harden_process;
63pub use memory::{
64    coffer_view, init_pool, pool_acquire, pool_release, zeroize_all_registered_at_shutdown,
65    LockedBuffer, MemoryEnclave, PoolSlot, SecureBuffer, TieredPool, TieredPoolConfig,
66};
67pub use zeroize::Zeroizing;
68
69// ── Key management + platform utilities (signing or encryption) ──────────────
70#[cfg(any(feature = "signing", feature = "encryption"))]
71pub mod auth;
72#[cfg(any(feature = "signing", feature = "encryption"))]
73pub mod bridge_server;
74#[cfg(any(feature = "signing", feature = "encryption"))]
75pub mod capabilities;
76#[cfg(any(feature = "signing", feature = "encryption"))]
77pub mod config;
78#[cfg(any(feature = "signing", feature = "encryption"))]
79pub mod credential;
80#[cfg(any(feature = "signing", feature = "encryption"))]
81pub mod diagnostics;
82#[cfg(any(feature = "signing", feature = "encryption"))]
83pub mod encryption;
84#[cfg(any(feature = "signing", feature = "encryption"))]
85pub mod exec;
86#[cfg(any(feature = "signing", feature = "encryption"))]
87pub mod factory;
88#[cfg(any(feature = "signing", feature = "encryption"))]
89pub mod fs;
90#[cfg(any(feature = "signing", feature = "encryption"))]
91pub mod integrity;
92#[cfg(any(feature = "signing", feature = "encryption"))]
93pub mod process;
94#[cfg(any(feature = "signing", feature = "encryption"))]
95pub mod security_key;
96#[cfg(any(feature = "signing", feature = "encryption"))]
97pub mod shell;
98#[cfg(any(feature = "signing", feature = "encryption"))]
99pub mod signing;
100#[cfg(any(feature = "signing", feature = "encryption"))]
101pub mod types;
102#[cfg(any(feature = "signing", feature = "encryption"))]
103pub mod wsl;
104
105#[cfg(any(feature = "signing", feature = "encryption"))]
106pub use auth::{platform_auth_capabilities, AuthCapabilities, AuthHandle};
107#[cfg(any(feature = "signing", feature = "encryption"))]
108pub use capabilities::{
109    has_keychain_entitlement, is_binary_signed, security_capabilities, SecurityCapabilities,
110};
111#[cfg(any(feature = "signing", feature = "encryption"))]
112pub use config::{
113    EnclaveConfig, LinuxConfig, MacOsConfig, PlatformConfig, WindowsConfig, WindowsSoftwareFallback,
114};
115#[cfg(any(feature = "signing", feature = "encryption"))]
116pub use credential::{classify_credential, CredentialState, LifecyclePolicy};
117#[cfg(feature = "encryption")]
118pub use encryption::EncryptorHandle;
119// Error and Result already re-exported unconditionally above.
120#[cfg(any(feature = "signing", feature = "encryption"))]
121pub use exec::{IntegrationType, SecureProcess, TempSecretFile};
122#[cfg(any(feature = "signing", feature = "encryption"))]
123pub use factory::{
124    create_auth, create_encryptor, create_security_key, create_signer, create_tamper_evident,
125    create_tamper_evident_ephemeral,
126};
127#[cfg(any(feature = "signing", feature = "encryption"))]
128pub use integrity::{IntegrityMode, TamperEvidentHandle, VerifyOutcome};
129#[cfg(any(feature = "signing", feature = "encryption"))]
130pub use security_key::{SecurityKeyHandle, SecurityKeyInfo, SecurityKeySignature};
131#[cfg(feature = "signing")]
132pub use signing::SignerHandle;
133#[cfg(any(feature = "signing", feature = "encryption"))]
134pub use types::{AccessPolicy, BackendKind, KeyInfo, KeyType, PresenceMode, PresenceOptions};
hardware_enclave/lib.rs

hardware_enclave/
lib.rs
