rivide 1.1.1

Official Rust idiomatic and zero-allocation bindings for the Rivide Post-Quantum Cryptography (NIST FIPS 203 ML-KEM & NIST FIPS 204 ML-DSA) C99 Library.
Documentation

Rivide: Post-Quantum Cryptography Rust Crate

Crates.io Documentation CI CodeQL Rust License: MIT C Engine Security Memory

Rivide for Rust (rivide) provides high-performance, zero-allocation, idiomatic Rust bindings for the Rivide Post-Quantum Cryptography (PQC) C99 library. It implements finalized NIST FIPS 203 (ML-KEM) and NIST FIPS 204 (ML-DSA) standards with automated RAII memory zeroization, constant-time arithmetic, and native AVX2 / ARM NEON hardware acceleration.

Key Features

  • Official NIST Post-Quantum Standards:
    • ML-KEM (FIPS 203): Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-768 and ML-KEM-1024).
    • ML-DSA (FIPS 204): Module-Lattice-Based Digital Signature Algorithm (ML-DSA-65 and ML-DSA-87).
  • Zero-Setup C99 Compilation: build.rs compiles the underlying C99 engine directly using the cc build dependency. No external pre-installed C libraries or system packages are required.
  • Zero Heap Allocations (0 Malloc): Pure stack-allocated byte arrays ([u8; N]) for core cryptographic keys, ciphertexts, and signatures.
  • Automated RAII Memory Safety: Secret keys (MlKem768SecretKey, MlDsa65SecretKey, etc.) implement the Drop trait and automatically invoke rivide_cleanse upon exiting scope.
  • Hardware SIMD Vector Acceleration: Executes native AVX2 (256-bit) and ARM NEON (128-bit) vectorized polynomial arithmetic directly in C.
  • Constant-Time Side-Channel Protection: Built-in constant-time byte comparisons (utils::ct_memcmp) and rejection sampling.
  • Integrated Symmetric Primitives: Native implementations of SHA3-256/512, SHAKE-128/256, and AES-128/256-GCM AEAD.

Table of Contents

  1. Installation & Quick Start
  2. Code Tutorials & Usage Examples
  3. Parameter & Specification Summary
  4. Cargo Automation & Testing
  5. API Reference & Namespaces
  6. Documentation Map
  7. License & Maintainers

Installation & Quick Start

1. Installation

Add rivide to your project using cargo add:

cargo add rivide

Or add it directly to your Cargo.toml:

[dependencies]
rivide = "1.1.1"

2. Building from Source

Clone the repository and compile using Cargo:

# Clone the repository
git clone https://github.com/mrvlous/rivide.git
cd rivide/bindings/rust

# Build optimized release artifact
cargo build --release

# Run automated integration test suite
cargo test

# Run executable demonstration examples
cargo run --example kem_exchange
cargo run --example dsa_sign
cargo run --example hybrid_channel

Code Tutorials & Usage Examples

Tutorial 1: ML-KEM-768 Quantum-Safe Key Exchange

Exchange a 256-bit symmetric session key between Alice and Bob using NIST FIPS 203 ML-KEM-768 (Security Category 3):

use rivide::kem::MlKem768;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Alice generates ML-KEM-768 keypair
    let alice = MlKem768::keypair()?;
    println!("Alice Public Key Length: {} bytes", alice.public_key.as_bytes().len());

    // 2. Bob encapsulates a 32-byte shared secret under Alice's public key
    let bob = MlKem768::encapsulate(&alice.public_key)?;
    println!("Bob Ciphertext Length   : {} bytes", bob.ciphertext.len());

    // 3. Alice decapsulates the shared secret using her secret key
    let alice_ss = MlKem768::decapsulate(&bob.ciphertext, &alice.secret_key)?;

    // 4. Verify shared secrets match in constant time
    assert_eq!(alice_ss, bob.shared_secret);
    println!("Quantum-safe shared secret established successfully!");

    // Secret keys automatically zeroized upon drop
    Ok(())
}

Tutorial 2: ML-DSA-65 Digital Signature & Verification

Sign and verify arbitrary documents and tokens using NIST FIPS 204 ML-DSA-65 (Security Category 3):

use rivide::dsa::MlDsa65;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Signer generates ML-DSA-65 keypair
    let signer = MlDsa65::keypair()?;

    // 2. Sign arbitrary message payload
    let document = b"Quantum-Safe Financial Authorization Payload: Transfer $50,000 to Alice.";
    let signature = MlDsa65::sign(document, &signer.secret_key)?;
    println!("Signature Length: {} bytes", signature.as_bytes().len());

    // 3. Verifier validates signature against public key
    let is_valid = MlDsa65::verify(&signature, document, &signer.public_key);
    assert!(is_valid);
    println!("Signature is 100% authentic and valid!");

    // 4. Test tamper detection
    let tampered_doc = b"Quantum-Safe Financial Authorization Payload: Transfer $500,000 to Alice.";
    let is_tampered_valid = MlDsa65::verify(&signature, tampered_doc, &signer.public_key);
    assert!(!is_tampered_valid);
    println!("Tampered payload successfully rejected!");

    Ok(())
}

Tutorial 3: Hybrid PQC + AES-256-GCM Secure Channel

Combine ML-KEM-768 with AES-256-GCM AEAD to build a post-quantum confidential authenticated transport channel:

use rivide::crypto::AesGcm;
use rivide::kem::MlKem768;
use rivide::utils::randombytes;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Server generates ephemeral ML-KEM-768 keypair
    let server = MlKem768::keypair()?;

    // 2. Client encapsulates session key under server public key
    let kem = MlKem768::encapsulate(&server.public_key)?;
    let session_key = kem.shared_secret; // 32-byte PQC key

    // 3. Client encrypts payload using AES-256-GCM
    let payload = b"CONFIDENTIAL: Sovereign post-quantum financial wire instructions.";
    let iv_bytes = randombytes(12)?;
    let mut iv = [0u8; 12];
    iv.copy_from_slice(&iv_bytes);
    let aad = b"Protocol:TLS1.3-PQC-Hybrid";

    let encrypted = AesGcm::encrypt_256(&session_key, &iv, payload, Some(aad))?;

    // 4. Server decapsulates session key and decrypts payload
    let server_key = MlKem768::decapsulate(&kem.ciphertext, &server.secret_key)?;
    let decrypted = AesGcm::decrypt_256(&server_key, &iv, &encrypted.ciphertext, &encrypted.tag, Some(aad))?;

    assert_eq!(&decrypted, payload);
    println!("Hybrid channel decrypted successfully: \"{}\"", std::str::from_utf8(&decrypted)?);
    Ok(())
}

Parameter & Specification Summary

Primitive Standard Public Key Secret Key Ciphertext / Signature Shared Key / Security
ML-KEM-768 NIST FIPS 203 1184 bytes 2400 bytes 1088 bytes 32 bytes (Category 3 / AES-192)
ML-KEM-1024 NIST FIPS 203 1568 bytes 3168 bytes 1568 bytes 32 bytes (Category 5 / AES-256)
ML-DSA-65 NIST FIPS 204 1952 bytes 4032 bytes 3309 bytes Category 3 / AES-192 equivalent
ML-DSA-87 NIST FIPS 204 2592 bytes 4896 bytes 4627 bytes Category 5 / AES-256 equivalent

Cargo Automation & Testing

Command Purpose
cargo build --release Compile optimized release static archive and binaries
cargo test Run entire integration test suite and doc-tests
cargo bench Execute high-precision performance benchmark harness
cargo run --example kem_exchange Execute ML-KEM-768 key encapsulation tutorial
cargo run --example dsa_sign Execute ML-DSA-65 digital signature tutorial
cargo run --example hybrid_channel Execute hybrid PQC + AES-256-GCM secure channel tutorial

API Reference & Namespaces

For complete documentation, see the Rivide Rust API Reference.

Documentation Map

License & Maintainers

This project is licensed under the MIT License - see the LICENSE file for details.