pqcrypto

The pqcrypto super-crate provides Rust wrappers around C implementations from the PQClean project. It includes several NIST PQC standardization effort algorithms categorized into Key-Encapsulation Mechanisms (KEM) and Signature Schemes.

Key-Encapsulation Mechanisms (KEM)

• pqcrypto-mlkem
• pqcrypto-classicmceliece
• pqcrypto-hqc

Signature Schemes

• pqcrypto-mldsa
• pqcrypto-falcon
• pqcrypto-sphincsplus

The pqcrypto-mlkem crate provides Rust-friendly wrappers around C implementations from PQClean.

For each scheme (ml-kem-512, ml-kem-768, and ml-kem-1024), the crate provides:

1. Default implementation: Used by the standard, high-level Rust API.
2. Alternative implementations: Optimized versions (like avx2 or aarch64) are available but are only exposed via ffi methods. Use the high-level API unless you specifically require direct FFI access to a particular implementation.

The pqcrypto-falcon crate provides bindings to several Falcon schemes sourced from PQClean.

For each scheme, there is a "default" implementation used by the high-level, Rust-friendly API. Alternative implementations (such as hardware-optimized versions like avx2 or aarch64) are available but are only exposed via ffi methods. Use the high-level API for standard usage and the ffi methods only when you specifically require a particular implementation variant.

Supported schemes include:

• falcon-512 (variants: clean, avx2, aarch64)
• falcon-padded-512 (variants: clean, avx2, aarch64)
• falcon-1024 (variants: clean, avx2, aarch64)
• falcon-padded-1024 (variants: clean, avx2, aarch64)

The pqcrypto-mldsa crate provides bindings to ML-DSA schemes sourced from PQClean.

For each scheme, the crate provides a high-level, Rust-friendly interface using the clean implementation by default. If you require optimized implementations (like avx2 or aarch64), these are exposed exclusively via ffi methods and do not use the standard Rust-friendly API.

Supported schemes:

• ml-dsa-44 (supports clean, avx2, aarch64)
• ml-dsa-65 (supports clean, avx2, aarch64)
• ml-dsa-87 (supports clean, avx2, aarch64)

Note: avx2 and aarch64 implementations are only available if the target hardware supports them.

The pqcrypto-sphincsplus crate provides bindings to various SPHINCS+ schemes sourced from PQClean. It distinguishes between two types of interfaces:

1. Rust-friendly interface: Uses the default implementation for each scheme. This is the primary way to interact with the algorithms in idiomatic Rust.
2. FFI interface: Alternative implementations (such as avx2 if supported by your hardware) are exposed exclusively via ffi methods.

Because the quantum routines require a standard library, they cannot be compiled as pure no-std WASM. Instead, you must use wasi and its standard library.

To enable this, download the wasm32-wasi sysroot build from the wasi-sdk releases and set the WASI_SDK_DIR environment variable to point to it.

Below is an example of installing the sysroot globally to /opt/wasi and configuring the environment variable system-wide via /etc/profile.d/wasi.sh.

sudo mkdir -p /opt/wasi
cd /opt/wasi
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sysroot-12.0.tar.gz -O /tmp/wasi-sysroot-12.0.tar.gz
sudo tar -xvzf /tmp/wasi-sysroot-12.0.tar.gz
rm /tmp/wasi-sysroot-12.0.tar.gz

sudo tee /etc/profile.d/wasi.sh <<EOF
export WASI_SDK_DIR="/opt/wasi/wasi-sysroot"
EOF
source /etc/profile.d/wasi.sh

By default, the sphincsplus crate does not include serde support. If you need to serialize or deserialize SPHINCS+ keys or signatures using the serde framework, you must enable the serialization feature in your Cargo.toml.

# Example Cargo.toml configuration
pqcrypto-sphincsplus = { version = "...", features = ["serialization"] }

By default, the pqcrypto-mlkem crate does not include serde support. To enable serialization and deserialization of ML-KEM types, you must enable the serialization feature in your Cargo.toml.

[dependencies]
pqcrypto-mlkem = { version = "...", features = ["serialization"] }

By default, the pqcrypto-falcon crate does not include serde support. To enable serialization and deserialization of Falcon keys and signatures, you must enable the serialization feature in your Cargo.toml.

# Example Cargo.toml configuration
pqcrypto-falcon = { version = "...", features = ["serialization"] }

Once the WASI_SDK_DIR is configured, you can compile the pqcrypto library for linking with WebAssembly using the wasm32-wasi target. You must disable default features to ensure compatibility with the WASI environment.

Use the following command to build the library with avx2 and serialization features enabled:

cd pqcrypto
cargo build --no-default-features --target wasm32-wasi --features avx2,serialization