reallyme_crypto/
lib.rs

1// SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2//
3// SPDX-License-Identifier: Apache-2.0
4
5//! # reallyme-crypto
6//!
7//! Umbrella crate that re-exports the ReallyMe cryptographic primitives,
8//! dispatch and signer abstractions behind one dependency and a consistent
9//! feature set.
10//!
11//! ## Platform lanes
12//!
13//! Rust exposes two backend lanes selected by Cargo feature and target:
14//! `native` (portable Rust) and `wasm` (package-owned Rust compiled for
15//! WebAssembly with target-appropriate entropy support).
16//! Swift and Kotlin provider selection lives in their package facades; those
17//! facades call this Rust workspace through FFI/JNI only for algorithms whose
18//! provider policy explicitly selects Rust. A lane never silently falls back to
19//! another backend.
20//!
21//! The canonical contract is not the Rust API by itself. It is the shared set
22//! of protobuf/enums, package algorithm identifiers, typed error taxonomy,
23//! provider manifest, and conformance vectors. Rust is the reference
24//! implementation and the shared implementation for selected primitives; native
25//! platform routes are interchangeable only when vectors and typed-error tests
26//! prove identical input, output, failure, and edge-case behavior.
27//!
28//! ## Security posture
29//!
30//! `#![forbid(unsafe_code)]` here; secret material is returned in zeroizing
31//! wrappers; signature verification fails closed; and cross-implementation
32//! conformance vectors pin the Rust output against an independent oracle.
33//! See `SECURITY.md` and `SECURITY_MEMORY_MODEL.md` at the repository root.
34//!
35//! Compile-checked usage examples live in the crate README so tests remain
36//! separate from production implementation files.
37
38#![doc = include_str!("../README.md")]
39#![forbid(unsafe_code)]
40
41#[cfg(all(feature = "wasm", not(target_arch = "wasm32"), not(feature = "native")))]
42compile_error!(
43    "reallyme-crypto's `wasm` backend lane must be checked with \
44     `--target wasm32-unknown-unknown`. Host builds should use the `native` \
45     backend lane, or include `native` when running all-feature host checks."
46);
47
48pub use crypto_core as core;
49pub use crypto_core::{
50    AeadAlgorithm, Algorithm, CryptoError, HashAlgorithm, KeyWrapAlgorithm, MacAlgorithm,
51};
52
53mod aead_error;
54#[cfg(any(
55    feature = "ml-kem-512",
56    feature = "ml-kem-768",
57    feature = "ml-kem-1024",
58    feature = "x-wing"
59))]
60mod kem_error;
61#[cfg(any(
62    feature = "x25519",
63    feature = "p256",
64    feature = "p384",
65    feature = "p521"
66))]
67mod key_agreement_error;
68mod signature_error;
69
70/// Operation-layer domain conventions shared by Rust and adapter boundaries.
71pub mod operations;
72
73/// Typed ownership, retention, export, and destruction contracts for secrets.
74pub mod secret_material;
75
76/// JSON Web Key envelope types and public-key conversion helpers.
77#[cfg(feature = "jwk")]
78pub use envelopes_jwk as jwk;
79
80/// Bidirectional conversion between JWK and Multikey public-key envelopes.
81#[cfg(feature = "jwk-multikey")]
82pub use envelopes_jwk_multikey as jwk_multikey;
83
84/// Algorithm-selected dispatch: keygen, sign/verify, key agreement, KEM, AEAD,
85/// hashing, and multikey binding routed by an [`core::Algorithm`] selector.
86#[cfg(feature = "dispatch")]
87pub mod dispatch;
88
89/// Primary generated protobuf operation-response boundary.
90#[cfg(feature = "operation-response")]
91pub mod operation_contract;
92
93/// Signer/verifier traits and dispatch-backed implementations for producing and
94/// checking detached signatures.
95#[cfg(feature = "signer")]
96pub mod signer {
97    pub use crypto_signer::{
98        DispatchSigner, DispatchVerifier, Signer, SignerError, SignerFailureKind, Verifier,
99        VerifierError, VerifierFailureKind,
100    };
101}
102
103/// AES-GCM authenticated encryption primitives and their typed key/nonce
104/// wrappers and length constants.
105#[cfg(feature = "aes")]
106pub mod aes;
107
108/// AES-256-GCM authenticated encryption with typed key and nonce boundaries.
109#[cfg(feature = "aes")]
110pub mod aes256_gcm;
111
112/// AES-128, AES-192, and AES-256 Key Wrap (RFC 3394) for compact key material.
113#[cfg(feature = "aes-kw")]
114pub mod aes_kw;
115
116/// AES-256-GCM-SIV nonce-misuse-resistant authenticated encryption primitive and
117/// its typed key/nonce wrappers and length constants.
118#[cfg(feature = "aes-gcm-siv")]
119pub mod aes_gcm_siv;
120
121/// ChaCha20-Poly1305 and XChaCha20-Poly1305 authenticated encryption
122/// primitives with typed key and nonce wrappers.
123#[cfg(feature = "chacha20-poly1305")]
124pub mod chacha20_poly1305;
125
126/// Argon2id password-based key derivation, including platform-tuned cost
127/// profiles and typed salt/secret/derived-key wrappers.
128#[cfg(feature = "argon2id")]
129pub mod argon2id;
130
131/// OS-backed cryptographically secure randomness and typed generators for AEAD
132/// nonces and Argon2 salts.
133#[cfg(feature = "csprng")]
134pub mod csprng {
135    pub use crypto_csprng::{
136        generate_aead_nonce_12, generate_argon2_salt_16, generate_argon2_salt_32, generate_bytes,
137        AeadNonce12, Argon2Salt16, Argon2Salt32, OsSecureRandom, RandomBytes, SecureRandom,
138        AEAD_NONCE_12_LENGTH, ARGON2_SALT_16_LENGTH, ARGON2_SALT_32_LENGTH,
139    };
140}
141
142/// Ed25519 signatures: keypair generation, sign/verify, and public-key encoding.
143#[cfg(feature = "ed25519")]
144pub mod ed25519;
145
146/// HMAC authentication tags over SHA-256, SHA-384, and SHA-512.
147#[cfg(feature = "hmac")]
148pub mod hmac;
149
150/// JWA ECDH-ES Concat KDF over SHA-256 for deriving content-encryption keys
151/// from an ECDH shared secret.
152#[cfg(feature = "concat-kdf")]
153pub mod concat_kdf;
154
155/// NIST P-256 (secp256r1) ECDSA over pre-hashed messages, with public-key
156/// compression and Secure Enclave handle encoding.
157#[cfg(feature = "p256")]
158pub mod p256;
159
160/// NIST P-384 (secp384r1) ECDSA and ECDH, with public-key
161/// compression/decompression helpers.
162#[cfg(feature = "p384")]
163pub mod p384;
164
165/// NIST P-521 (secp521r1) ECDSA and ECDH, with public-key
166/// compression/decompression helpers.
167#[cfg(feature = "p521")]
168pub mod p521;
169
170/// PBKDF2 password-based key derivation conforming to RFC 8018.
171#[cfg(feature = "pbkdf2")]
172pub mod pbkdf2;
173
174/// RSA signature verification for PKCS#1 v1.5 and PSS.
175#[cfg(feature = "rsa")]
176pub mod rsa;
177
178/// secp256k1 ECDSA signs SHA-256(message) once, returns compact low-S `r || s`,
179/// and uses compressed SEC1 public keys as the canonical API representation.
180#[cfg(feature = "secp256k1")]
181pub mod secp256k1;
182
183/// X25519 Diffie–Hellman key agreement and public-key encoding.
184#[cfg(feature = "x25519")]
185pub mod x25519;
186
187/// X-Wing hybrid KEM over X25519 plus ML-KEM-768.
188#[cfg(feature = "x-wing")]
189pub mod x_wing;
190
191/// RFC 9180 HPKE Base-mode encryption over supported DHKEM/HKDF/AEAD suites.
192#[cfg(feature = "hpke")]
193pub mod hpke;
194
195/// HKDF (RFC 5869) extract-and-expand key derivation over the SHA-2/SHA-3 suites,
196/// with domain-separated key derivation helpers.
197#[cfg(feature = "hkdf")]
198pub mod hkdf;
199
200/// KMAC256 key derivation for protocols using NIST SP 800-108 and SP 800-185.
201#[cfg(feature = "kmac")]
202pub mod kmac;
203
204/// ML-DSA-44 (FIPS 204) post-quantum signatures: keygen, sign/verify, and
205/// public-key encoding.
206#[cfg(feature = "ml-dsa-44")]
207pub mod ml_dsa_44;
208
209/// ML-DSA-65 (FIPS 204) post-quantum signatures: keygen, sign/verify, and
210/// public-key encoding.
211#[cfg(feature = "ml-dsa-65")]
212pub mod ml_dsa_65;
213
214/// ML-DSA-87 (FIPS 204) post-quantum signatures: keygen, sign/verify, and
215/// public-key encoding.
216#[cfg(feature = "ml-dsa-87")]
217pub mod ml_dsa_87;
218
219/// SLH-DSA-SHA2-128s (FIPS 205) hash-based post-quantum signatures.
220#[cfg(feature = "slh-dsa")]
221pub mod slh_dsa;
222
223/// ML-KEM-512 (FIPS 203) post-quantum key encapsulation: keygen, encapsulate,
224/// and decapsulate.
225#[cfg(feature = "ml-kem-512")]
226pub mod ml_kem_512;
227
228/// ML-KEM-768 (FIPS 203) post-quantum key encapsulation: keygen, encapsulate,
229/// and decapsulate.
230#[cfg(feature = "ml-kem-768")]
231pub mod ml_kem_768;
232
233/// ML-KEM-1024 (FIPS 203) post-quantum key encapsulation: keygen, encapsulate,
234/// and decapsulate.
235#[cfg(feature = "ml-kem-1024")]
236pub mod ml_kem_1024;
237
238/// SHA-2-256 hashing and its fixed-length digest wrapper.
239#[cfg(feature = "sha2")]
240pub mod sha2;
241
242/// SHA-3-256 hashing and its fixed-length digest wrapper.
243#[cfg(feature = "sha3")]
244pub mod sha3;
reallyme_crypto/lib.rs

reallyme_crypto/
lib.rs
