oxicrypto — The COOLJAPAN Pure-Rust cryptography facade

oxicrypto is the top-level façade crate for the OxiCrypto stack. It aggregates the individual Pure-Rust primitive crates (hashes, AEADs, ciphers, MACs, signatures, key exchange, KDFs, CSPRNG, and an optional post-quantum preview) behind one coherent API: trait re-exports from oxicrypto-core, *Algo selector enums with *_impl() factory functions returning trait objects, convenience one-shot helpers, runtime feature/algorithm introspection, and named algorithm suites. Everything in the default build is #![forbid(unsafe_code)] and 100% Pure Rust — no C, C++, or Fortran.

Two optional, non-Pure-Rust adapters can be enabled behind feature flags: oxicrypto-adapter-aws-lc (FIPS-validated aws-lc-rs, surfaced at oxicrypto::aws_lc) and oxicrypto-adapter-pkcs11 (PKCS#11 HSM via cryptoki, surfaced at oxicrypto::pkcs11). These involve C/FFI and are off by default; the Pure-Rust pure feature is the default.

Sub-crates aggregated by oxicrypto

Installation

[dependencies]
# Default: all Pure-Rust primitives (hash, aead, cipher, mac, sig, kex, kdf, rand).
oxicrypto = "0.1.0"

# Trait surface only — no algorithm implementations.
oxicrypto = { version = "0.1.0", default-features = false }

# Add explicit runtime CPU-feature detection (oxicrypto::simd::cpu_info()).
oxicrypto = { version = "0.1.0", features = ["simd"] }

# Add the post-quantum preview (ML-KEM, ML-DSA, SLH-DSA, X-Wing).
oxicrypto = { version = "0.1.0", features = ["pq-preview"] }

# Opt-in, NON-Pure-Rust adapters (require a C toolchain / HSM).
oxicrypto = { version = "0.1.0", features = ["aws-lc"] }   # aws-lc-rs (FIPS)
oxicrypto = { version = "0.1.0", features = ["pkcs11"] }   # PKCS#11 HSM

Quick Start

Derive a session key with HKDF-SHA-256, then encrypt and decrypt with AES-256-GCM:

use oxicrypto::{aead_impl, kdf_impl, AeadAlgo, KdfAlgo};
use oxicrypto::prelude::*;

# fn main() -> Result<(), oxicrypto::CryptoError> {
// 1. Derive a 32-byte AES-256-GCM key from input key material.
let kdf = kdf_impl(KdfAlgo::HkdfSha256);
let mut session_key = [0u8; 32];
kdf.derive(b"input-key-material", b"salt", b"context v1", &mut session_key)?;

// 2. Encrypt (seal_to_vec returns ciphertext || 16-byte tag).
let aead = aead_impl(AeadAlgo::Aes256Gcm);
let nonce = [0x42u8; 12];
let ct = aead.seal_to_vec(&session_key, &nonce, b"header", b"secret payload")?;

// 3. Decrypt (verifies the tag, then decrypts).
let pt = aead.open_to_vec(&session_key, &nonce, b"header", &ct)?;
assert_eq!(pt, b"secret payload");
# Ok(())
# }

One-shot hashing and runtime introspection:

# #[cfg(feature = "pure")]
# {
let digest = oxicrypto::sha256(b"hello");        // [u8; 32]
assert_eq!(digest.len(), 32);

let features = oxicrypto::enabled_features();      // e.g. ["pure"]
let algos = oxicrypto::available_algorithms();     // Vec<AlgorithmId>
assert!(features.contains(&"pure"));
assert!(!algos.is_empty());
# }

Top-level API

Convenience functions (pure feature)

Factory functions (pure feature)

Each returns a boxed Send + Sync trait object for the selected algorithm.

Introspection & version (version module)

Algorithm suites (version module)

simd module (simd feature)

Post-quantum helpers (pq-preview feature)

Re-exported from oxicrypto::pq::* plus selector enums and free functions:

Selector enums

All *Algo enums are #[non_exhaustive], Copy, and implement Display, FromStr, and TryFrom<&str> (case-insensitive aliases supported).

HashAlgo

Sha256, Sha384, Sha512, Sha3_256, Sha3_384, Sha3_512, Blake3.

AeadAlgo

Aes128Gcm, Aes256Gcm, ChaCha20Poly1305, Aes128GcmSiv, Aes256GcmSiv, XChaCha20Poly1305, Aes128Ccm, Aes256Ccm, Aes128Ocb3, Aes256Ocb3, DeoxysII128.

Note: aead_impl covers every variant except Aes128Ocb3 / Aes256Ocb3, which are available directly in oxicrypto-aead and via the AEAD benchmark.

MacAlgo

HmacSha256, HmacSha384, HmacSha512, HmacSha3_256, HmacSha3_512, Poly1305, CmacAes128, CmacAes256, Kmac128 { output_len }, Kmac256 { output_len }.

SigAlgo

Ed25519, Ed448, EcdsaP256, EcdsaP384, EcdsaP521, RsaPkcs1v15Sha256, RsaPkcs1v15Sha384, RsaPkcs1v15Sha512, RsaPssSha256, SchnorrBip340.

KexAlgo

X25519, EcdhP256, EcdhP384, EcdhP521.

KdfAlgo

HkdfSha256, HkdfSha384, HkdfSha512, Pbkdf2Sha256, Pbkdf2Sha512, Argon2id, Scrypt, Balloon.

PqKemAlgo / PqSigAlgo (pq-preview)

• PqKemAlgo: MlKem512, MlKem768, MlKem1024.
• PqSigAlgo: MlDsa44, MlDsa65, MlDsa87, plus the ten SLH-DSA parameter sets (SlhDsaSha2_{128,192,256}{s,f}, SlhDsaShake{128,256}{s,f}).

Re-exports at the crate root

From oxicrypto-core (always)

• Traits: Aead, Hash, Mac, Signer, Verifier, Kdf, KeyAgreement, KeyPair, Rng, StreamingHash, StreamingMac, ConstantTimeEq.
• Identifiers: AlgorithmId, AlgorithmCategory.
• Secure wrappers: SecretKey, SecretVec; zeroize: Zeroize, ZeroizeOnDrop.
• Constant-time utilities: ct_eq, ct_is_zero, ct_select.
• Errors: CryptoError.

From the primitive crates (pure)

• Hash: ParallelHash128, ParallelHash256, parallel_hash128, parallel_hash128_xof, parallel_hash256, parallel_hash256_xof, HashBuilder.
• AEAD: AesGcmSiv128, AesGcmSiv256, XChaCha20Poly1305, Deoxys2_128, seal_box, open_box, seal_with_random_nonce, aes128_key_wrap/aes128_key_unwrap, aes256_key_wrap/aes256_key_unwrap.
• KDF: argon2id_derive, scrypt_derive, pbkdf2_sha256, pbkdf2_sha512, balloon_sha256, balloon_sha512, the hkdf_sha{256,384,512}_{extract,expand} family, hkdf_expand_label_sha{256,384}, plus Argon2Params, BalloonHasher/BalloonParams/BalloonVariant, HkdfSha384, the KeyStretcher/Stretcher/StretchParams abstraction, and per-algorithm *StretchParams.
• Cipher (oxicrypto::cipher): aes128_encrypt_block, aes256_encrypt_block, chacha20_keystream_block, and the *_KEY_LEN / *_BLOCK_LEN / *_NONCE_LEN constants (QUIC header-protection building blocks).
• Signatures: ECDSA P-256/384/521 signer + verifier types, Ed448SigningKey/Ed448VerifyingKey, the RSA PKCS#1v15 (SHA-256/384/512) and RSA-PSS-SHA-256 signer/verifier types, SchnorrBip340, schnorr_bip340_sign_with_aux.
• MAC: HmacSha384.
• KEX: EcdhP256, EcdhP384; HPKE (oxicrypto::hpke): HpkeSuite, HpkeContextS, HpkeContextR, KemId, KdfId, AeadId (RFC 9180).
• RNG: random_bytes, random_nonce, random_range, reseed.

Optional adapter modules

Feature Flags

Feature → algorithm matrix

Error variants

The crate uses the shared oxicrypto_core::CryptoError, re-exported at the root.

Prelude

use oxicrypto::prelude::*;

Imports the core traits (Aead, Hash, Mac, Signer, Verifier, Kdf, KeyAgreement, KeyPair, Kem, PasswordHash, Rng, StreamingAead, StreamingHash, StreamingMac, ConstantTimeEq, SecretKey, SecretVec, Zeroize, ZeroizeOnDrop, AlgorithmId, AlgorithmCategory, CryptoError), the selector enums (AeadAlgo, HashAlgo, KdfAlgo, KexAlgo, MacAlgo, SigAlgo; plus PqKemAlgo/PqSigAlgo under pq-preview), the factory and convenience functions (under pure), and version/available_algorithms/ VersionInfo.

Examples

Runnable examples live under examples/:

cargo run -p oxicrypto --example encrypt   # HKDF-SHA-256 + AES-256-GCM round trip
cargo run -p oxicrypto --example hash      # one-shot hashing
cargo run -p oxicrypto --example sign      # signature sign/verify
cargo run -p oxicrypto --example kex       # key exchange
cargo run -p oxicrypto --example pq_kem --features pq-preview  # ML-KEM (PQ)

Cross-references

• oxicrypto-core — trait surface, CryptoError, AlgorithmId, secure wrappers.
• oxicrypto-hash, oxicrypto-aead, oxicrypto-cipher, oxicrypto-mac, oxicrypto-sig, oxicrypto-kex, oxicrypto-kdf, oxicrypto-rand — the Pure-Rust primitive crates.
• oxicrypto-pq — post-quantum primitives (pq-preview).
• oxicrypto-adapter-aws-lc, oxicrypto-adapter-pkcs11 — opt-in, non-Pure-Rust adapters.
• oxicrypto-bench — Criterion benchmarks against ring and aws-lc-rs.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)