RustCrypto Utils

The rustcrypto/utils repository is a collection of specialized utility crates designed for cryptographic applications. These crates provide low-level primitives, hardware feature detection, constant-time utilities, and data handling tools used across the broader RustCrypto ecosystem.

Key functional areas include:

• Hardware & CPU Features: aarch64-dit (AArch64 Data-Independent Timing), cpufeatures (efficient CPU feature detection), and cpubits (optimal word size detection).
• Cryptographic Primitives & Helpers: ctutils (constant-time selection and equality), cmov (conditional move intrinsics), dbl (Galois Field double operations), and block-padding (message padding/unpadding).
• Data Handling & Buffering: block-buffer (fixed-size block processing), blobby (binary blob storage decoder), sponge-cursor (sponge-based absorption/squeezing), and hex-literal (compile-time hex to byte array conversion).
• Security & Memory: zeroize (secure memory zeroing) and inout (generic in-place/buffer-to-buffer reference types).

The ctutils crate provides constant-time equivalents of Rust's bool and Option types, specifically Choice and CtOption. It is designed for cryptographic applications where execution time must not depend on secret data.

Key features include:

• Choice: A constant-time boolean replacement.
• CtOption: A constant-time Option replacement that uses eagerly evaluated combinators to maintain constant-time properties.
• const fn support: Extensive use of const fn allows for constant-time logic to be executed at compile time.
• Hardware Acceleration: Uses the cmov crate to leverage architecture-specific predication intrinsics (like conditional moves) on x86_64 and aarch64 for guaranteed constant-time equality and selection.
• No Copy bounds: Unlike many constant-time libraries, ctutils works with both stack-allocated and heap-allocated types.
• Expanded Traits: Includes CtFind and CtLookup for constant-time operations on arrays and slices.

⚠️ Security Warning: This implementation has never been independently audited. Use at your own risk.

The cpufeatures crate provides lightweight, efficient, and no_std-compatible runtime CPU feature detection for aarch64, loongarch64, and x86/x86_64 architectures. It serves as an alternative to the std-dependent is_x86_feature_detected! macro, making it suitable for mobile targets (iOS, Android) and embedded environments.

Key Characteristics

• no_std support: Works in environments without the Rust standard library.
• Caching: The first call to the detection logic caches the result, ensuring subsequent calls have minimal runtime overhead.
• Compiler Optimization: If target features are enabled via compiler flags (e.g., RUSTFLAGS), the get() method will always return true and init() will skip the CPUID instruction, allowing the compiler to eliminate fallback code paths.
• Architecture Support: Supports aarch64 (Linux, iOS, macOS/ARM), loongarch64 (Linux), and x86/x86_64 (OS independent).

// Add cpufeatures to your Cargo.toml
// [dependencies]
// cpufeatures = "..."

#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
pub mod x86_backend {
    // Use the `new!` macro to create a detection module for specific features.
    // Syntax: cpufeatures::new!(module_name, feature_1, feature_2, ...);
    cpufeatures::new!(cpuid_aes_sha, "aes", "sha");

    pub fn run() {
        // 1. Initialize the detection and get an `InitToken`.
        // The `InitToken` is a Zero Sized Type (ZST) that guarantees
        // the underlying static storage is initialized.
        let token: cpuid_aes_sha::InitToken = cpuid_aes_sha::init();

        // 2. Check if the features are supported.
        if token.get() {
            println!("CPU supports both SHA and AES extensions");
        } else {
            println!("SHA and AES extensions are not supported");
        }

        // 3. Alternative: Get the value directly without managing a token.
        // This is useful if the value is only needed once.
        let val = cpuid_aes_sha::get();
        assert_eq!(val, token.get());
    
        // 4. Alternative: Get both the token and the value at once.
        let (token, val) = cpuid_aes_sha::init_get();
        assert_eq!(val, token.get());
    }
}

The cmov crate provides low-level CPU intrinsics for conditional moves (predication). These allow selecting between values without using branch instructions, ensuring the operation is constant-time and resistant to timing side-channels caused by branch prediction or speculative execution.

Key Characteristics:

• Guaranteed Constant-Time: Uses inline asm! to prevent the compiler (e.g., LLVM) from rewriting instructions into branches (like the x86-cmov-conversion pass).
• Low-Level API: Designed as a building block for creating portable constant-time abstractions across different CPU architectures.
• Not for General Use: If you need a higher-level API, use the [ctutils] crate instead.

Supported Architectures with Native Instructions:

• x86/x86_64 (CMOVZ, CMOVNZ)
• aarch64 (CSEL)

Fallback Behavior: On other architectures (like arm, riscv32, or riscv64), the crate uses a "best effort" portable fallback based on bitwise arithmetic and core::hint::black_box. While designed to be branch-free, constant-time execution cannot be strictly guaranteed on these fallback paths due to potential future compiler optimizations.