Skip to content

v0.25.0

Choose a tag to compare

@caraka caraka released this 17 Oct 21:28
· 25 commits to main since this release

oxicrypt 0.25.0

oxicrypt is a pure-Rust cryptographic module targeting FIPS 140-3. This release changes how the module proves its own binary is intact, refuses output unless the module is operational, and brings the power-up self-tests to the form FIPS 140-3 IG 10.3.A requires. A 0.x minor bump is incompatible; read the upgrade section before moving.

What the module now does

  • Integrity test by signature. At start-up the module verifies an ML-DSA-87 (FIPS 204) signature over its own loaded image, covering every file-backed byte the loader maps: ELF on Linux and Android, Mach-O on macOS, PE on Windows. The signer refuses, by name, an image it cannot type.
  • No output outside SelfTest and Operational. Every output entry point checks the module state once per call, so an object built earlier produces nothing once the module enters its error state. During the power-up self-tests only the thread running them is admitted.
  • Self-tests compare against precomputed NIST values. The ML-KEM, ML-DSA, SLH-DSA and PBKDF2 power-up tests use vendored NIST ACVP vectors, and the C library's oxi_init runs the known-answer tests of every algorithm crate it links.
  • LMS verification for all 80 parameter pairs of SP 800-208, plus verify_any / oxi_lms_verify_any, which routes on the public key's typecodes. LMS key generation and signing are removed: SP 800-208 confines them to hardware modules.
  • Release artifacts cover Android (arm64 and x86_64) beside Linux, macOS and Windows.

Fixes

  • Integrity-signed binaries launch on macOS on Apple silicon; cargo xtask sign applies the code-sign, integrity-sign, code-sign order for every Apple target. (#280)
  • HKDF-Expand returns when asked for exactly 255 blocks in a release build. TLS 1.3 HkdfLabel inputs outside their RFC 8446 bounds are refused with InvalidInput rather than truncated. (#285)
  • initialize_with_profile leaves the active profile unchanged when called after initialisation. (#285)

Upgrading from 0.24.0

Re-sign every binary with a key pair you generate. The integrity slot is format version 4; slots of earlier versions are refused. Generate a pair with oxicrypt-integrity-sign --keygen <dir> (outside any git work tree), build with OXICRYPT_INTEGRITY_VERIFY_KEY=<dir>/integrity-verify.pub (or OXICRYPT_INTEGRITY_VERIFY_KEY_HEX), and sign with --sign --key <dir>/integrity-signing.key. A build without a verifying key compiles but reports NoVerifyKey and never becomes operational. A binary you received is replaced with a fresh copy from its publisher, not re-signed. sign_image and write_extent take an oxicrypt_integrity_sign::SigningKey. The signer exits 3 when --sign is refused for its key and 4 when --keygen fails.

Result from output points. These now return Result and refuse outside SelfTest and Operational:

  • every public *_internal function (ECDSA, RSA and DH helpers return the refusal as NotOperational);
  • finalize on the SHA-1, SHA-2 and SHA-3 hashers and on Hmac; squeeze and finalize_into on SHAKE, cSHAKE, KMAC, TupleHash and ParallelHash; finalize on the LMS hash adapters (update and absorb stay infallible);
  • encrypt_block / decrypt_block on Aes128Key, Aes192Key, Aes256Key; oxicrypt_aes::ctr_xor; oxicrypt_cmac::cmac_tag;
  • oxicrypt_rsa::pss and oaep encode, decode and verify (Result<Option<_>, Error> / Result<bool, Error>); Conditioner::startup_kat (Result<bool, Error>);
  • key accessors private_scalar, seed, prk, public_key, modulus_bytes, public_exponent;
  • the traits oxicrypt_drbg::HashAlg and HmacAlg changed signatures; BlockCipher's methods are encrypt_block_with / decrypt_block_with, taking a SelfTestStarted proof;
  • oxicrypt_rsa::keygen::generate_2048/3072/4096 are renamed generate_*_internal and hidden; use RsaPrivateKey2048::generate and its 3072- and 4096-bit counterparts. KeygenError gains Module.
  • The HKDF, SP 800-108, PBKDF2 and TLS KDF output functions zeroize the output buffer on error.

Renamed and added variants.

  • IntegrityStatus::Mismatch and IntegrityError::Mismatch → SignatureInvalid (status 2). Added Refused (7), NoVerifyKey (8), KeyMismatch (9), SlotDamaged (10). SlotInvalid (3) now means only the unsigned build template; Unreadable (4) means the test was not performed.
  • SlotDefect range variants are renamed for entries (NoEntries, TooManyEntries, EmptyEntry, EntryOverflow, EntryOutOfBounds); new variants name the other defects.
  • Unreadable::AllMechanismsFailed is removed; new variants name the read that failed. Unreadable::FileLength on Darwin and Windows for a file shorter than the signed length.
  • oxicrypt_imageread::ReadError gains InvalidName and NoImage.
  • oxicrypt_module::Error::AlreadyFailed (formerly NotOperational) for initialising a module whose initialisation failed; a failed initialisation is terminal until the process restarts.
  • New Module variants on ModeError, IntegrityError, DrbgError, EntropyError, TimerError, SourceError. EntropyError::Module replaces NotReady / ConditionerKat for a refusal; TimerError::Module replaces Unavailable for one.
  • VerifyAnyError::Unroutable for LMS input naming no parameter pair.

Removed.

  • oxicrypt_integrity::FIPS_INTEGRITY_KEY, mac_over_file_ranges, encode_hmac_hex, constant_time_eq; slot::OFF_MAC, RANGE_ENTRY_SIZE, MAX_RANGES. SlotImage loses flags, slot_rva, mac, ranges and gains fields and signature. slot::encode and slot::extent_len changed signatures.
  • LMS key generation and signing: keygen, keygen_internal, keygen_from_parts, sign, sign_internal, LmsPrivateKey, LmsSigningKey, PRIVATE_KEY_LEN (every per-pair module and the crate root); each per-pair module's KATS; the 80 Lms…Sign variants of oxicrypt_module::Service; the alloc and parallel features of oxicrypt-lms; the acvp-harness LMS keyGen and sigGen handlers.
  • Per-parameter-set self-test items: slh_dsa_*::KATS, ml_kem_*::{self_test, KAT_ENTRY, KATS}, ml_dsa_*::{self_test, KAT_ENTRY, KATS}; the crate-level KATS of each is the only self-test slice. pbkdf2_self_test_sha1 and pbkdf2_self_test_sha256; pbkdf2_self_test_sha224 replaces them.
  • Hidden from documentation: the arithmetic modules of oxicrypt_ecdsa, oxicrypt_eddsa, oxicrypt_rsa and oxicrypt_sha::keccak, the accelerator functions of oxicrypt_aes_accel and oxicrypt_sha_accel, and the BlockCipher trait.

#[non_exhaustive]: oxicrypt_integrity::SlotDefect, Unreadable, IntegrityError; oxicrypt_imageread::ReadError; oxicrypt_module::Error. Add a wildcard arm to every match.

On-demand integrity test. verify_loaded_image() runs only inside the power-up self-tests; at any other time it runs nothing and returns IntegrityError::Module (AlreadyInitialized once operational). oxi selftest reports the verdict from the process's start and re-runs the algorithm self-tests.

C ABI.

  • The AES functions and HMAC-DRBG reseed / generate return NotOperational = 1 once the module has left Operational, for handles created earlier. The functions returning a public key, modulus or exponent from a handle do the same.
  • oxi_integrity_status can return Refused = 7. oxi_init returns NotOperational for a module whose initialisation already failed.
  • Removed oxi_lms_keygen, oxi_lms_sign, the 80 oxi_lms_<pair>_keygen and 80 oxi_lms_<pair>_sign functions, and OXI_LMS_PRIVATE_KEY_LEN. oxi_lms_verify and the per-pair verify functions remain. Added oxi_lms_verify_any (InvalidInput = 5 for an unroutable key; TagMismatch = 22 for a failed verification).
  • Added oxi_integrity_status_detail() and oxi_integrity_key_fingerprint(), which returns BufferTooSmall for a buffer under 32 bytes.
  • oxicrypt-module does not compile for a target without 64-bit atomics.

Verifying a release asset

Each shared library and oxi is signed with the project's release key, whose public half is keys/release-integrity-verify.pub in this tag; the static archive ships unsigned. The release key's fingerprint is the SHA-256 of that 2,592-byte file:

sha256:ef4ff23cd2cdd5c9aa97576f928e874b149017485b3a0e74e45aee1155f248fe

Run oxi --integrity (or call oxi_integrity_key_fingerprint() against the library) and compare the fingerprint it reports with that value, and compare the asset's SHA-256 with the one published beside it. Each asset's provenance file records the key's fingerprint and the SHA-256 of the artifact's signature.

Full list of changes: https://github.com/oxiforge/oxicrypt/blob/v0.25.0/CHANGELOG.md