Skip to content

v0.26.0

Choose a tag to compare

@caraka caraka released this 24 Oct 16:17
· 9 commits to main since this release
Immutable release. Only release title and notes can be modified.

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

  • oxicrypt crate 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 reading Passed, 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. The oxicrypt crate accepts any library that reports its ABI number and refuses another with Error::LibraryAbi; a library without oxi_abi_version, as every earlier release is, is accepted only at the crate's own release version. abi/v1.txt in oxicrypt-ffi records 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.h defines the status codes as OXI_RESULT_* constants of the OxiResult enum, with the values the C functions return.
  • Shared library named by ABI. The library's SONAME is liboxicrypt_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 library oxicrypt_ffi.dll.lib. Android keeps the plain liboxicrypt_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::NonceTooShort and a new DrbgError::EntropyInputTooShort variant, and reach the C ABI as OxiResult::EntropyInputTooShort (29) and OxiResult::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 as NoDwarf. The refusals are NoDwarf, DwarfForm, DuplicateStatic, StaticOutsideImage, StaticUnlocated and StaticUnsized.
  • Removed the oxicrypt-pointer placeholder crate. The oxicrypt crate 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.