Expand description
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):
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 fingerprintProject 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 libraryoxicrypt_ffi.dll.lib(MSVC) orliboxicrypt_ffi.dll.a(GNU)). The static archiveliboxicrypt_ffi.a/oxicrypt_ffi.libis 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::initrefuses a library that reports another, withError::KeyFingerprint.OXICRYPT_LIB_UNPINNED=1: the explicit opt-out from the pin. The crate then hasModule::init_unpinnedand noModule::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):
# 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.
use oxicrypt::{Module, Profile};
let module = Module::init(Profile::Cnsa2)?;
let digest = module.sha384(b"abc")?;
assert_eq!(digest.len(), 48);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:
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:
fn swapped(m: oxicrypt::Module, d: oxicrypt::MlKem1024KeySeedD, z: oxicrypt::MlKem1024KeySeedZ) {
let _ = m.ml_kem_1024_keygen(z, d);
}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:
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,
}
}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,
}
}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.
lama_manifestoxi_initoxi_active_profileoxi_is_operationaloxi_integrity_statusoxi_integrity_status_detailoxi_integrity_key_fingerprintoxi_sha384oxi_hkdf_sha384_extractoxi_hkdf_sha384_expandoxi_aes256_newoxi_aes256_freeoxi_aes256_gcm_encryptoxi_aes256_gcm_decryptoxi_hmac_drbg_sha256_newoxi_hmac_drbg_sha256_freeoxi_hmac_drbg_sha256_instantiateoxi_hmac_drbg_sha256_reseedoxi_hmac_drbg_sha256_generateoxi_ml_dsa_87_keygenoxi_ml_dsa_87_signoxi_ml_dsa_87_verifyoxi_ml_kem_1024_keygenoxi_ml_kem_1024_encapsulateoxi_ml_kem_1024_decapsulate
§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.
Structs§
- Aes256
Key - An AES-256 key schedule held by the library.
- Fingerprint
- The SHA-256 fingerprint of the verifying key a library embeds. Public data: it names a signer.
- HkdfPrk
- A 48-byte HKDF-SHA384 pseudorandom key, from
Module::hkdf_sha384_extract. - Hmac
Drbg Sha256 - An HMAC_DRBG-SHA-256 instance held by the library (SP 800-90A §10.1.2).
- Init
Error - Why
Module::initdid not return a token. - MlDsa87
KeySeed - The 32-byte seed
ξof ML-DSA-87 key generation (FIPS 204 §6.1). Consumed byModule::ml_dsa_87_keygen. - MlDsa87
Secret Key - An ML-DSA-87 secret key, 4,896 bytes on the heap.
- MlKem1024
Decapsulation Key - An ML-KEM-1024 decapsulation key, 3,168 bytes on the heap. Borrowed, never cloned, to decapsulate many ciphertexts.
- MlKem1024
Encaps Seed - The 32-byte randomness
mof one ML-KEM-1024 encapsulation (FIPS 203 §6.2), which must be fresh for each. Consumed byModule::ml_kem_1024_encapsulate. - MlKem1024
KeySeedD - The 32-byte seed
dof ML-KEM-1024 key generation (FIPS 203 §6.1). Consumed byModule::ml_kem_1024_keygen. - MlKem1024
KeySeedZ - The 32-byte implicit-rejection seed
zof ML-KEM-1024 key generation (FIPS 203 §6.1). Consumed byModule::ml_kem_1024_keygen. - Module
- Proof that the library this program loaded is initialised.
- Okm
- HKDF-SHA384 output key material of a length chosen at the call, on the
heap. From
Module::hkdf_sha384_expand. - Shared
Secret - A 32-byte ML-KEM-1024 shared secret.
Enums§
- Detail
Error - Why the library’s integrity-test detail text could not be read.
- Error
- An error from the library, or from a check the crate makes before calling it.
- Integrity
Status - The pre-operational integrity test’s indicator, as
oxi_integrity_statusreports it. The library latches it on the first run. - Profile
- An algorithm profile of the module.
- Site
- Which kind of C function returned a status code.
Constants§
- AES256_
GCM_ NONCE_ LEN - AES-256-GCM nonce length.
- AES256_
GCM_ TAG_ LEN - AES-256-GCM tag length.
- AES256_
KEY_ LEN - AES-256 key length.
- HKDF_
SHA384_ MAX_ OKM_ LEN - The longest HKDF-SHA384 output, 255 × 48 bytes (RFC 5869 §2.3).
- HKDF_
SHA384_ PRK_ LEN - HKDF-SHA384 pseudorandom key length.
- HMAC_
DRBG_ MAX_ PROVIDED_ LEN - The most entropy, nonce and personalization bytes HMAC_DRBG-SHA-256 accepts in one call, combined.
- HMAC_
DRBG_ MAX_ REQUEST_ LEN - The most bytes one HMAC_DRBG-SHA-256 generate call returns (SP 800-90A Table 3).
- ML_
DSA_ 87_ MAX_ CONTEXT_ LEN - The longest ML-DSA-87 context string (FIPS 204 §5.2).
- ML_
DSA_ 87_ PUBLIC_ KEY_ LEN - ML-DSA-87 public key length.
- ML_
DSA_ 87_ SECRET_ KEY_ LEN - ML-DSA-87 secret key length.
- ML_
DSA_ 87_ SEED_ LEN - ML-DSA-87 key-generation seed length.
- ML_
DSA_ 87_ SIGNATURE_ LEN - ML-DSA-87 signature length.
- ML_
KEM_ 1024_ CIPHERTEXT_ LEN - ML-KEM-1024 ciphertext length.
- ML_
KEM_ 1024_ DECAPSULATION_ KEY_ LEN - ML-KEM-1024 decapsulation key length.
- ML_
KEM_ 1024_ ENCAPSULATION_ KEY_ LEN - ML-KEM-1024 encapsulation key length.
- ML_
KEM_ 1024_ SEED_ LEN - ML-KEM-1024 seed length, for each of
d,zandm. - ML_
KEM_ 1024_ SHARED_ SECRET_ LEN - ML-KEM-1024 shared secret length.
- OXI_
ABI_ VERSION - The ABI number of the C interface this crate was built against.
- SHA384_
LEN - SHA-384 digest length.
Traits§
- Drbg
Seed - A seed type the module’s DRBG can fill with
HmacDrbgSha256::seed: the four seed types of this crate, and no others.
Type Aliases§
- MlDsa87
Public Key - An ML-DSA-87 public key.
- MlDsa87
Signature - An ML-DSA-87 signature.
- MlKem1024
Ciphertext - An ML-KEM-1024 ciphertext.
- MlKem1024
Encapsulation Key - An ML-KEM-1024 encapsulation key.