Repository navigation
v0.26.0
oxicrypt 0.26.0
oxicrypt is a pure-Rust cryptographic module that targets FIPS 140-3 Level 1. This release adds the oxicrypt crate, which gives a Rust program the module through the module's separately built and signed shared library without compiling any module crate into the program. The C interface gains a numbered ABI that the Rust crate and the system loader both check. The deterministic random bit generators (DRBGs) refuse entropy and nonce inputs shorter than the minimum for their security strength. The integrity signer signs Windows DLLs built with the GNU toolchain.
What the release adds
oxicryptcrate for Rust programs. The crate links the module's shared library and never its static archive: on Linux, Android and Windows it links the library by its exact file name, and on Apple targets, whose linker takes no exact name, it refuses a library directory that also holds the archive. At build time it requires the library's verifying-key fingerprint or an explicit opt-out. At initialisation it checks the library's ABI number, that the library is operational with its integrity indicator readingPassed, its fingerprint and its active profile. It wraps SHA-384, HKDF-SHA384, AES-256-GCM, HMAC_DRBG-SHA-256, ML-DSA-87 and ML-KEM-1024 with fixed-size types, single-use seeds and secrets zeroed on drop. The crate is outside the cryptographic boundary.- Numbered C ABI.
oxi_abi_version()returns the C interface's ABI number, 1. The number is independent of the release version and changes only when the interface breaks compatibility; within a number, a newer library serves an older caller, not the reverse. Theoxicryptcrate accepts any library that reports its ABI number and refuses another withError::LibraryAbi; a library withoutoxi_abi_version, as every earlier release is, is accepted only at the crate's own release version.abi/v1.txtinoxicrypt-ffirecords every exported function's parameter and return types and every status code at that number, and a test fails when one is removed or changed while the number stays, or when a recorded line is edited. Output sizes are not in that record. - Status codes in the C header.
oxicrypt.hdefines the status codes asOXI_RESULT_*constants of theOxiResultenum, with the values the C functions return. - Shared library named by ABI. The library's
SONAMEisliboxicrypt_ffi.so.<ABI>on Linux and its macOS install name is@rpath/liboxicrypt_ffi.<ABI>.dylib, so a loader refuses a library of another ABI by name. Release tarballs ship that layout, and the Windows tarball also ships the MSVC import libraryoxicrypt_ffi.dll.lib. Android keeps the plainliboxicrypt_ffi.so, the only form an application packages, and the Windows DLL keeps its name. C programs linked against a cargo build on Linux or macOS must deploy the library under the new name; see Upgrading. - DRBG minimum input lengths. HMAC_DRBG, Hash_DRBG and CTR_DRBG with a derivation function refuse an entropy input shorter than the instantiated security strength on instantiate, reseed and prediction-resistance generate, and a nonce shorter than half of it on instantiate. The refusals are
Error::EntropyInputTooShort,Error::NonceTooShortand a newDrbgError::EntropyInputTooShortvariant, and reach the C ABI asOxiResult::EntropyInputTooShort(29) andOxiResult::NonceTooShort(30). An instantiate refused by a length check leaves the DRBG uninstantiated. See Upgrading for the lengths. - Integrity signer for GNU-toolchain Windows DLLs. The signer reads the module's statics from the DWARF debug information in the DLL when no program database of the name the DLL records is beside it. The four pinned statics are always located exactly or the DLL is refused. The other module statics are covered only on two assumptions the reader cannot check: that the compiler gives every static with storage a
DW_AT_location, and that every module crate is built with full debug information; a static that breaks either is not seen, where a program database would list it. An image with neither a program database record nor DWARF is refused asNoDwarf. The refusals areNoDwarf,DwarfForm,DuplicateStatic,StaticOutsideImage,StaticUnlocatedandStaticUnsized. - Removed the
oxicrypt-pointerplaceholder crate. Theoxicryptcrate name on crates.io passes to the Rust binding at its first publish, and the placeholder versions 1.40.3 and 0.0.1 are yanked then.
Upgrading
DRBG entropy and nonce lengths
Every Hash_DRBG and HMAC_DRBG variant requires at least 32 bytes of entropy input and a 16-byte nonce, so SHA-384 callers that supplied 24-byte entropy or a 12-byte nonce are refused. CTR_DRBG with a derivation function requires entropy input of at least the AES key length and a nonce of at least half of it. Supply inputs of those lengths or longer. Rust code that matches exhaustively on DrbgError must handle DrbgError::EntropyInputTooShort. C callers must handle OXI_RESULT_ENTROPY_INPUT_TOO_SHORT (29) and OXI_RESULT_NONCE_TOO_SHORT (30). An instantiate refused by a length check leaves the DRBG uninstantiated.
Shared library name for C programs linked against a cargo build
On Linux, cargo writes the plain liboxicrypt_ffi.so, while a program linked with -loxicrypt_ffi against target/release records liboxicrypt_ffi.so.1, so the loader refuses to start it (cannot open shared object file, exit status 127) until the library is deployed under that name. On macOS, cargo writes the plain liboxicrypt_ffi.dylib, while a program linked the same way records the install name @rpath/liboxicrypt_ffi.1.dylib, so the library must be deployed as liboxicrypt_ffi.1.dylib on the program's rpath. On both, copy the build output to the name scripts/library-file-name.sh prints and keep the plain name as a link to it. Release tarballs ship that layout already. Android and Windows keep their library names and need no change.
The full list of changes is in CHANGELOG.md under 0.26.0.