oxicrypto-core 0.1.1

Pure Rust cryptography trait surface (no_std + alloc)
Documentation

oxicrypto-core — Trait surface, error types, and secret wrappers for OxiCrypto

Crates.io License

oxicrypto-core defines the public API surface shared by every oxicrypto-* sub-crate in the OxiCrypto stack: the algorithm trait objects (Aead, Hash, Mac, Kdf, Signer, …), the unified CryptoError enum, constant-time comparison utilities, the canonical AlgorithmId registry, and zeroize-on-drop secret wrappers. No cryptographic algorithm is implemented here — concrete implementations live in oxicrypto-aead, oxicrypto-hash, oxicrypto-kdf, oxicrypto-mac, oxicrypto-sig, oxicrypto-kex, oxicrypto-pq, and oxicrypto-rand.

The crate is Pure Rust and #![no_std] (with alloc) — it pulls in only subtle (constant-time primitives) and zeroize (secure memory wiping), and declares #![forbid(unsafe_code)]. There is no ring, no aws-lc, and no C/C++/Fortran in the default build. The constant-time helpers are built on RustCrypto's subtle crate so equality checks do not leak the position of the first differing byte.

Installation

[dependencies]
oxicrypto-core = "0.1.0"

# Enable std integrations (e.g. `From<CryptoError> for std::io::Error`)
oxicrypto-core = { version = "0.1.0", features = ["std"] }

Quick Start

use oxicrypto_core::{ct_eq, CryptoError, SecretKey};

// Fixed-size secret, zeroized automatically on drop.
let key = SecretKey::<32>::from_slice(&[0xAA; 32])?;
assert_eq!(key.as_bytes().len(), 32);

// Constant-time equality — runtime is independent of where the bytes differ.
assert!(ct_eq(b"tag-bytes", b"tag-bytes"));
assert!(!ct_eq(b"tag-bytes", b"different"));
# Ok::<(), CryptoError>(())

API Overview

Algorithm traits

Every concrete algorithm in OxiCrypto implements one of these traits. The dyn-safe traits are Send + Sync so they can be type-erased behind Box<dyn …>.

Trait Object-safe Key methods Implemented by
Aead yes name, key_len, nonce_len, tag_len, seal, open, seal_to_vec, open_to_vec oxicrypto-aead
StreamingAead no (Sized) init, encrypt_update, encrypt_finalize, decrypt_update, decrypt_finalize, reset oxicrypto-aead
Hash yes name, output_len, hash, hash_to_vec, hash_to_array<N> oxicrypto-hash
StreamingHash yes update, finalize, reset oxicrypto-hash
Mac yes name, key_len, output_len, mac, verify, mac_to_vec oxicrypto-mac
StreamingMac no (Sized) update, finalize, verify oxicrypto-mac
Kdf yes name, derive oxicrypto-kdf
PasswordHash yes name, hash_password oxicrypto-kdf
PasswordHashParams yes memory_cost, time_cost, parallelism oxicrypto-kdf
KeyAgreement yes name, scalar_len, point_len, shared_secret_len, agree, agree_to_vec oxicrypto-kex
Signer yes name, signature_len, sign oxicrypto-sig
Verifier yes name, verify oxicrypto-sig
KeyGenerator yes name, generate_keypair oxicrypto-sig
Kem no (assoc. types) kem_generate, kem_encapsulate, kem_decapsulate oxicrypto-pq
Rng yes fill oxicrypto-rand

The Aead, Hash, Mac, and KeyAgreement traits provide *_to_vec convenience methods as default implementations that allocate the output buffer for you. Hash::hash_to_array<N> returns a fixed-size array and is gated on Self: Sized to preserve dyn Hash object safety. Kem uses associated types (EncapKey, DecapKey, Ciphertext, SharedSecret) rather than a dyn-safe interface.

CryptoError — unified error enum

#[derive(Debug, Clone, PartialEq, Eq)], implements Display and core::error::Error (unconditionally). With the std feature it also implements From<CryptoError> for std::io::Error.

Variant Meaning
InvalidKey Key has the wrong length or is otherwise invalid
InvalidNonce Nonce/IV has the wrong length or is otherwise invalid
InvalidTag AEAD open / MAC verify / password verify failed authentication
BufferTooSmall Output buffer is too small for the requested operation
BadInput General bad-input condition (e.g. zero-length KDF output requested)
Internal(&'static str) Internal or backend error with a static message
Kex Key-exchange or encapsulation/decapsulation failure
Sign Signature generation or verification failure
Rng RNG-specific failure (e.g. getrandom unavailable)
Encoding Encoding/decoding failure (DER, PEM, SEC1, …)
UnsupportedAlgorithm Requested algorithm is not compiled-in or unsupported at runtime

Constant-time utilities (ct module)

Function Description
ct_eq(a, b) -> bool Constant-time byte-slice equality; returns false immediately on length mismatch, otherwise compares in time proportional to the shorter slice
ct_is_zero(data) -> bool Constant-time all-zero check; runtime is proportional to data.len() regardless of content
ct_select(a, b, choice) -> u8 Returns a if choice == 0, else b (any non-0 low bit selects b)

Secret wrappers (secret module)

All three wrappers implement Zeroize + ZeroizeOnDrop and have a redacted Debug impl that never prints key material.

Type Description Key methods
SecretKey<const N: usize> Fixed-size secret wrapping [u8; N] new, from_slice (errors InvalidKey on length mismatch), as_bytes
SecretVec Heap-allocated, variable-length secret new, from_slice, as_bytes, len, is_empty
KeyPair<SK: Zeroize, PK> Bundles a secret half (zeroized on drop) with a public half new, secret, public

Algorithm registry (algo_id module)

AlgorithmId is a #[non_exhaustive] enum cataloguing every algorithm family across the OxiCrypto stack (70+ variants spanning hashes, AEADs, MACs, signatures, key exchange, KDFs, and post-quantum primitives). Each variant exposes:

Method Description
name() -> &'static str Canonical IANA/NIST string (e.g. "AES-256-GCM", "ML-KEM-768")
category() -> AlgorithmCategory Maps the algorithm to its AlgorithmCategory

AlgorithmCategory variants: Hash, Aead, Mac, Signature, KeyExchange, Kdf, PostQuantum.

Coverage by category includes SHA-2 / SHA-3 / BLAKE2 / BLAKE3 hashes; AES-GCM, ChaCha20-Poly1305, AES-GCM-SIV, XChaCha20-Poly1305, AES-CCM, Deoxys-II, and AES key wrap (AEAD category); HMAC, Poly1305, CMAC, and KMAC MACs; Ed25519/Ed448, ECDSA P-256/384/521, RSA PKCS#1v1.5 / PSS, and BIP-340 Schnorr signatures; X25519/X448 and ECDH key exchange; HKDF, PBKDF2, Argon2id, scrypt, and Balloon KDFs; and ML-KEM, ML-DSA, SLH-DSA, plus hybrid KEMs (X-Wing) in the post-quantum category.

Re-exports

For convenience the crate root re-exports Box, String, Vec (from alloc), subtle::ConstantTimeEq, and zeroize::{Zeroize, ZeroizeOnDrop} so downstream crates share a single version of each dependency.

Feature Flags

Feature Default Description
std off Enables From<CryptoError> for std::io::Error. The crate is otherwise no_std + alloc.

Cross-references

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)