Skip to main content

Crate oxicrypt

Crate oxicrypt 

Source
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 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):

# 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_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

§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 againstaccepts
ABI 1a 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§

Aes256Key
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.
HmacDrbgSha256
An HMAC_DRBG-SHA-256 instance held by the library (SP 800-90A §10.1.2).
InitError
Why Module::init did not return a token.
MlDsa87KeySeed
The 32-byte seed ξ of ML-DSA-87 key generation (FIPS 204 §6.1). Consumed by Module::ml_dsa_87_keygen.
MlDsa87SecretKey
An ML-DSA-87 secret key, 4,896 bytes on the heap.
MlKem1024DecapsulationKey
An ML-KEM-1024 decapsulation key, 3,168 bytes on the heap. Borrowed, never cloned, to decapsulate many ciphertexts.
MlKem1024EncapsSeed
The 32-byte randomness m of one ML-KEM-1024 encapsulation (FIPS 203 §6.2), which must be fresh for each. Consumed by Module::ml_kem_1024_encapsulate.
MlKem1024KeySeedD
The 32-byte seed d of ML-KEM-1024 key generation (FIPS 203 §6.1). Consumed by Module::ml_kem_1024_keygen.
MlKem1024KeySeedZ
The 32-byte implicit-rejection seed z of ML-KEM-1024 key generation (FIPS 203 §6.1). Consumed by Module::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.
SharedSecret
A 32-byte ML-KEM-1024 shared secret.

Enums§

DetailError
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.
IntegrityStatus
The pre-operational integrity test’s indicator, as oxi_integrity_status reports 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, z and m.
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§

DrbgSeed
A seed type the module’s DRBG can fill with HmacDrbgSha256::seed: the four seed types of this crate, and no others.

Type Aliases§

MlDsa87PublicKey
An ML-DSA-87 public key.
MlDsa87Signature
An ML-DSA-87 signature.
MlKem1024Ciphertext
An ML-KEM-1024 ciphertext.
MlKem1024EncapsulationKey
An ML-KEM-1024 encapsulation key.