1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
//! The Rust interface to `liboxicrypt_ffi`, the oxicrypt cryptographic module
//! delivered as a separately built and signed shared library.
//!
//! This crate is outside the module's cryptographic boundary and is not the
//! module itself: the module is the `oxicrypt-*` crates, built into that
//! library and signed. This crate contains no cryptographic code and links no
//! module crate: it declares the C functions of `liboxicrypt_ffi`, links the
//! program to that library, and gives typed Rust over the C calling
//! convention. The module is the library the
//! operating system's loader binds to the program; the library runs its own
//! integrity test and self-tests when it is initialised, whatever program
//! loaded it, so a program using this crate is never signed.
//!
//! # Getting a library
//!
//! Either download a signed release library and pin the project's
//! verifying-key fingerprint, or build the library from source and sign it
//! with a key of your own (`docs/integrity-signing.md` in the repository
//! gives the procedure per platform):
//!
//! ```text
//! oxicrypt-integrity-sign --keygen <dir> # once, outside any source tree
//! OXICRYPT_INTEGRITY_VERIFY_KEY=<dir>/integrity-verify.pub cargo build --release -p oxicrypt-ffi
//! oxicrypt-integrity-sign --sign --key <dir>/integrity-signing.key <library>
//! oxicrypt-integrity-sign --verify <library>
//! oxicrypt-integrity-sign --show <library> # prints the fingerprint
//! ```
//!
//! Project release libraries are signed with the release key
//! `keys/release-integrity-verify.pub` of the repository, whose fingerprint
//! is `sha256:ef4ff23cd2cdd5c9aa97576f928e874b149017485b3a0e74e45aee1155f248fe`.
//!
//! # Building a program
//!
//! The build script reads, at build time only:
//!
//! - `OXICRYPT_LIB_DIR`: the directory holding the signed shared library
//! (`liboxicrypt_ffi.so`, `liboxicrypt_ffi.dylib`, or on Windows the import
//! library `oxicrypt_ffi.dll.lib` (MSVC) or `liboxicrypt_ffi.dll.a` (GNU)).
//! The static archive `liboxicrypt_ffi.a` / `oxicrypt_ffi.lib` is never
//! linked, because it would compile the module into the program. On
//! Linux, Android and Windows the shared library is linked by its exact
//! file name, so an archive beside it cannot be chosen, and the variable
//! may be left unset to link a library from the linker's default paths by
//! that name. Apple's linker takes no exact file name, so on macOS and iOS
//! the library is linked as `-loxicrypt_ffi`, the variable is required,
//! and a directory that also holds the static archive is refused.
//! - `OXICRYPT_LIB_FINGERPRINT=sha256:<64 hex digits>`: the fingerprint of the
//! verifying key the library embeds. [`Module::init`] refuses a library
//! that reports another, with [`Error::KeyFingerprint`].
//! - `OXICRYPT_LIB_UNPINNED=1`: the explicit opt-out from the pin. The crate
//! then has [`Module::init_unpinned`] and no [`Module::init`].
//!
//! A build that links the library requires exactly one of the fingerprint
//! and the opt-out. `OXICRYPT_LIB_OPTIONAL=1` with no `OXICRYPT_LIB_DIR`
//! builds the crate without linking the library, for running this crate's
//! own unit tests only.
//!
//! The pin catches an honestly built library signed with another key. It does
//! not resist a library that lies about its fingerprint, which no code outside
//! the boundary can.
//!
//! # Running a program
//!
//! The loader resolves `liboxicrypt_ffi` before `main` runs. The crate cannot
//! set a run-time search path for a dependent program; set it in the
//! program's own build (its `build.rs` or `.cargo/config.toml`):
//!
//! ```text
//! # ELF (Linux): RUNPATH, which the loader's environment can still override
//! -C link-arg=-Wl,--enable-new-dtags -C link-arg=-Wl,-rpath,<dir>
//! # macOS
//! -C link-arg=-Wl,-rpath,<dir>
//! ```
//!
//! or deploy the library where the loader looks: on Windows, the
//! application's directory. When the library is missing, the loader refuses
//! to start the program with its own message, before any Rust code runs: on
//! Linux `error while loading shared libraries: liboxicrypt_ffi.so.1: cannot
//! open shared object file`, naming the library's delivered name, exit status
//! 127; on macOS `dyld: Library not
//! loaded`; on Windows a dialog or exit status `0xC0000135`
//! (`STATUS_DLL_NOT_FOUND`).
//!
//! # Checking a program
//!
//! The program must hold no module code of its own:
//!
//! - `oxicrypt-integrity-sign --show <program>` reports no integrity slot in
//! it, and finds the slot in the library;
//! - `cargo tree -i oxicrypt-module`, run on the program's own dependency
//! graph, prints nothing. A dependency that pulls module crates in would
//! put an unsigned copy of module code beside the signed library.
//!
//! # Using the module
//!
//! [`Module::init`] initialises the loaded library once and returns a
//! [`Module`] token; every service is a method on it.
//!
//! ```no_run
//! # #[cfg(any(oxicrypt_pinned, doc))]
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! use oxicrypt::{Module, Profile};
//!
//! let module = Module::init(Profile::Cnsa2)?;
//! let digest = module.sha384(b"abc")?;
//! assert_eq!(digest.len(), 48);
//! # Ok(())
//! # }
//! # #[cfg(not(any(oxicrypt_pinned, doc)))]
//! # fn main() {}
//! ```
//!
//! Key generation and encapsulation take caller-supplied seeds, as the C ABI
//! does; the crate generates no randomness. The approved status of a key
//! generated through this crate depends on where its seed came from: a seed
//! drawn from the module's DRBG with [`HmacDrbgSha256::seed`] comes from
//! inside the module, a seed passed to `from_bytes` from outside it. Each seed
//! role has its own type ([`MlDsa87KeySeed`], [`MlKem1024KeySeedD`],
//! [`MlKem1024KeySeedZ`], [`MlKem1024EncapsSeed`]), and each is consumed by
//! the call that uses it.
//! The DRBG itself is seeded by the caller through
//! [`HmacDrbgSha256::instantiate`] and [`HmacDrbgSha256::reseed`], so the
//! caller supplies entropy meeting SP 800-90A and SP 800-90B and documents
//! its source in their own security policy.
//!
//! Secrets the crate returns zero themselves when dropped (see [`HkdfPrk`],
//! [`Okm`], [`MlDsa87SecretKey`], [`MlKem1024DecapsulationKey`],
//! [`SharedSecret`] and the seed types); an output is exposed only when the library
//! returned status 0.
//!
//! # Compile-time guarantees
//!
//! Each seed is consumed by the call that uses it, so one encapsulation
//! seed cannot serve two encapsulations:
//!
//! ```compile_fail,E0382
//! fn twice(
//! m: oxicrypt::Module,
//! ek: &oxicrypt::MlKem1024EncapsulationKey,
//! seed: oxicrypt::MlKem1024EncapsSeed,
//! ) {
//! let _ = m.ml_kem_1024_encapsulate(ek, seed);
//! let _ = m.ml_kem_1024_encapsulate(ek, seed);
//! }
//! ```
//!
//! and each role has its own type, so seeds cannot be swapped between roles:
//!
//! ```compile_fail,E0308
//! fn swapped(m: oxicrypt::Module, d: oxicrypt::MlKem1024KeySeedD, z: oxicrypt::MlKem1024KeySeedZ) {
//! let _ = m.ml_kem_1024_keygen(z, d);
//! }
//! ```
//!
//! ```compile_fail,E0308
//! fn crossed(m: oxicrypt::Module, seed: oxicrypt::MlDsa87KeySeed, z: oxicrypt::MlKem1024KeySeedZ) {
//! let _ = m.ml_kem_1024_keygen(seed, z);
//! }
//! ```
//!
//! The same calls, used as intended, compile:
//!
//! ```
//! fn once(
//! m: oxicrypt::Module,
//! d: oxicrypt::MlKem1024KeySeedD,
//! z: oxicrypt::MlKem1024KeySeedZ,
//! seed: oxicrypt::MlKem1024EncapsSeed,
//! dsa: oxicrypt::MlDsa87KeySeed,
//! ) -> Result<(), oxicrypt::Error> {
//! let (ek, _dk) = m.ml_kem_1024_keygen(d, z)?;
//! let _ = m.ml_kem_1024_encapsulate(&ek, seed)?;
//! let _ = m.ml_dsa_87_keygen(dsa)?;
//! Ok(())
//! }
//! ```
//!
//! [`Error`], [`Profile`] and [`IntegrityStatus`] are `#[non_exhaustive]`, so
//! a later release can add a variant without breaking a caller; a `match`
//! outside this crate needs a wildcard arm:
//!
//! ```compile_fail,E0004
//! fn name(p: oxicrypt::Profile) -> i32 {
//! match p {
//! oxicrypt::Profile::Unrestricted => 0,
//! oxicrypt::Profile::Cnsa2 => 1,
//! oxicrypt::Profile::Cnsa1 => 2,
//! oxicrypt::Profile::Migration => 3,
//! oxicrypt::Profile::Unknown(n) => n,
//! }
//! }
//! ```
//!
//! ```compile_fail,E0004
//! fn ok(s: oxicrypt::IntegrityStatus) -> bool {
//! use oxicrypt::IntegrityStatus as S;
//! match s {
//! S::Passed => true,
//! S::NotRun | S::SignatureInvalid | S::SlotInvalid | S::Unreadable | S::CastNotRun
//! | S::UnknownRecord | S::Refused | S::NoVerifyKey | S::KeyMismatch | S::SlotDamaged
//! | S::Unknown(_) => false,
//! }
//! }
//! ```
//!
//! ```compile_fail,E0004
//! fn retry(e: &oxicrypt::Error) -> bool {
//! use oxicrypt::Error as E;
//! match e {
//! E::ReseedRequired => true,
//! E::NotOperational | E::SelfTestFailed | E::ConditionalTestFailed
//! | E::AlreadyInitialized | E::InvalidInput | E::AlgorithmRestricted
//! | E::NotImplemented | E::Uninstantiated | E::NullPointer | E::BufferTooSmall
//! | E::OutputTooLong | E::NotBlockAligned | E::InvalidIvLength | E::TagMismatch
//! | E::LengthMismatch | E::InvalidNonceLength | E::InvalidTagLength
//! | E::InvalidPayloadLength | E::InvalidAadLength | E::IntegrityUnverified
//! | E::EntropyInputTooShort | E::NonceTooShort | E::Internal | E::SignatureInvalid
//! | E::Unknown(_) | E::LibraryAbi { .. } | E::LibraryVersion { .. }
//! | E::ProfileMismatch { .. } | E::KeyFingerprint { .. } => false,
//! }
//! }
//! ```
//!
//! ```
//! fn name(p: oxicrypt::Profile) -> i32 {
//! match p {
//! oxicrypt::Profile::Cnsa2 => 1,
//! other => other.code(),
//! }
//! }
//! ```
//!
//! # Wrapped C functions
//!
//! The safe layer of this release calls exactly these functions of the C ABI;
//! the others are declared and reached by nothing.
//!
//! <!-- wrapped:begin -->
//! - `lama_manifest`
//! - `oxi_init`
//! - `oxi_active_profile`
//! - `oxi_is_operational`
//! - `oxi_integrity_status`
//! - `oxi_integrity_status_detail`
//! - `oxi_integrity_key_fingerprint`
//! - `oxi_sha384`
//! - `oxi_hkdf_sha384_extract`
//! - `oxi_hkdf_sha384_expand`
//! - `oxi_aes256_new`
//! - `oxi_aes256_free`
//! - `oxi_aes256_gcm_encrypt`
//! - `oxi_aes256_gcm_decrypt`
//! - `oxi_hmac_drbg_sha256_new`
//! - `oxi_hmac_drbg_sha256_free`
//! - `oxi_hmac_drbg_sha256_instantiate`
//! - `oxi_hmac_drbg_sha256_reseed`
//! - `oxi_hmac_drbg_sha256_generate`
//! - `oxi_ml_dsa_87_keygen`
//! - `oxi_ml_dsa_87_sign`
//! - `oxi_ml_dsa_87_verify`
//! - `oxi_ml_kem_1024_keygen`
//! - `oxi_ml_kem_1024_encapsulate`
//! - `oxi_ml_kem_1024_decapsulate`
//! <!-- wrapped:end -->
//!
//! # Versions
//!
//! The C interface has an ABI number, independent of the release version,
//! that changes only when the interface breaks compatibility. This crate was
//! built against [`OXI_ABI_VERSION`]; [`Module::init`] calls the library's
//! `oxi_abi_version` before initialising it and refuses any other number with
//! [`Error::LibraryAbi`]. Within one ABI number, compatibility runs one way:
//! a library of a later release serves this crate, while an older release
//! of the same number may lack a function this crate calls, and the program
//! then fails at load (immediate binding) rather than through the number.
//! The function is looked up at run time, not linked, and only in the image
//! the library was loaded from: a library that predates it still loads, and
//! is then held to the exact-version rule, its API manifest's version equal
//! to this crate's, else [`Error::LibraryVersion`].
//!
//! | crate built against | accepts |
//! |---|---|
//! | ABI 1 | a library reporting ABI 1 that exports every function the crate calls; a library without `oxi_abi_version` only at the crate's own release version |
//!
//! On Linux the library's `SONAME` is `liboxicrypt_ffi.so.<ABI>` and on macOS
//! its install name is `@rpath/liboxicrypt_ffi.<ABI>.dylib`: the loader asks
//! for that file, so deploy the library under that name, with the plain name
//! (`liboxicrypt_ffi.so`, `liboxicrypt_ffi.dylib`) as a link to it for the
//! linker, which `OXICRYPT_LIB_DIR` must hold. On Android the `SONAME` is the
//! plain `liboxicrypt_ffi.so`, the only form an application packages.
pub use ;
pub use ;
pub use ;
pub use ;
/// The ABI number of the C interface this crate was built against.
pub const OXI_ABI_VERSION: i32 = 1;
/// SHA-384 digest length.
pub const SHA384_LEN: usize = 48;
/// HKDF-SHA384 pseudorandom key length.
pub const HKDF_SHA384_PRK_LEN: usize = 48;
/// The longest HKDF-SHA384 output, 255 × 48 bytes (RFC 5869 §2.3).
pub const HKDF_SHA384_MAX_OKM_LEN: usize = 12_240;
/// AES-256 key length.
pub const AES256_KEY_LEN: usize = 32;
/// AES-256-GCM nonce length.
pub const AES256_GCM_NONCE_LEN: usize = 12;
/// AES-256-GCM tag length.
pub const AES256_GCM_TAG_LEN: usize = 16;
/// The most entropy, nonce and personalization bytes HMAC_DRBG-SHA-256
/// accepts in one call, combined.
pub const HMAC_DRBG_MAX_PROVIDED_LEN: usize = 768;
/// The most bytes one HMAC_DRBG-SHA-256 generate call returns
/// (SP 800-90A Table 3).
pub const HMAC_DRBG_MAX_REQUEST_LEN: usize = 65_536;
/// ML-DSA-87 key-generation seed length.
pub const ML_DSA_87_SEED_LEN: usize = 32;
/// ML-DSA-87 public key length.
pub const ML_DSA_87_PUBLIC_KEY_LEN: usize = 2_592;
/// ML-DSA-87 secret key length.
pub const ML_DSA_87_SECRET_KEY_LEN: usize = 4_896;
/// ML-DSA-87 signature length.
pub const ML_DSA_87_SIGNATURE_LEN: usize = 4_627;
/// The longest ML-DSA-87 context string (FIPS 204 §5.2).
pub const ML_DSA_87_MAX_CONTEXT_LEN: usize = 255;
/// ML-KEM-1024 seed length, for each of `d`, `z` and `m`.
pub const ML_KEM_1024_SEED_LEN: usize = 32;
/// ML-KEM-1024 encapsulation key length.
pub const ML_KEM_1024_ENCAPSULATION_KEY_LEN: usize = 1_568;
/// ML-KEM-1024 decapsulation key length.
pub const ML_KEM_1024_DECAPSULATION_KEY_LEN: usize = 3_168;
/// ML-KEM-1024 ciphertext length.
pub const ML_KEM_1024_CIPHERTEXT_LEN: usize = 1_568;
/// ML-KEM-1024 shared secret length.
pub const ML_KEM_1024_SHARED_SECRET_LEN: usize = 32;
/// An ML-DSA-87 public key.
pub type MlDsa87PublicKey = ;
/// An ML-DSA-87 signature.
pub type MlDsa87Signature = ;
/// An ML-KEM-1024 encapsulation key.
pub type MlKem1024EncapsulationKey = ;
/// An ML-KEM-1024 ciphertext.
pub type MlKem1024Ciphertext = ;