rscrypto 0.8.0

Pure Rust Cryptography: RSA, Ed25519, X25519, SHA-2/3, BLAKE2/3, AES-GCM/GCM-SIV, X/ChaCha20-Poly1305, Argon2, HMAC/HKDF, CRC. no_std, WASM, hardware acceleration.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276

//! Authentication and key-derivation primitives.
//!
//! # Quick Start
//!
//! ```rust
//! # #[cfg(feature = "auth")]
//! # {
//! use rscrypto::{Ed25519Keypair, Ed25519SecretKey, HkdfSha256, HmacSha256, Mac};
//!
//! let key = b"shared-secret";
//! let data = b"hello world";
//!
//! let tag = HmacSha256::mac(key, data);
//!
//! let mut mac = HmacSha256::new(key);
//! mac.update(b"hello ");
//! mac.update(b"world");
//! assert!(mac.verify(&tag).is_ok());
//!
//! let mut okm = [0u8; 32];
//! HkdfSha256::new(b"salt", b"input key material").expand(b"context", &mut okm)?;
//! assert_ne!(okm, [0u8; 32]);
//!
//! let keypair = Ed25519Keypair::from_secret_key(Ed25519SecretKey::from_bytes([7u8; 32]));
//! let sig = keypair.sign(b"auth");
//! assert!(keypair.public_key().verify(b"auth", &sig).is_ok());
//!
//! let mut kmac = rscrypto::Kmac256::new(b"shared-secret", b"svc=v1");
//! kmac.update(b"auth");
//! let mut kmac_tag = [0u8; 32];
//! kmac.finalize_into(&mut kmac_tag);
//! assert!(rscrypto::Kmac256::verify_tag(b"shared-secret", b"svc=v1", b"auth", &kmac_tag).is_ok());
//!
//! let alice = rscrypto::X25519SecretKey::from_bytes([7u8; 32]);
//! let bob = rscrypto::X25519SecretKey::from_bytes([9u8; 32]);
//! let alice_shared = alice.diffie_hellman(&bob.public_key())?;
//! let bob_shared = bob.diffie_hellman(&alice.public_key())?;
//! assert!(alice_shared.ct_eq(&bob_shared).declassify());
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Feature Selection
//!
//! Use leaves for minimum size and bundles when you want the category:
//!
//! ```toml
//! [dependencies]
//! # MAC bundle: HMAC-SHA-2/SHA-3, KMAC128/256, and standalone Poly1305
//! rscrypto = { version = "0.6.4", default-features = false, features = ["macs"] }
//!
//! # HKDF only
//! rscrypto = { version = "0.6.4", default-features = false, features = ["hkdf"] }
//!
//! # Ed25519 only
//! rscrypto = { version = "0.6.4", default-features = false, features = ["ed25519"] }
//!
//! # ECDSA P-256/P-384 signing and verification
//! rscrypto = { version = "0.6.4", default-features = false, features = ["ecdsa"] }
//!
//! # RSA
//! rscrypto = { version = "0.6.4", default-features = false, features = ["rsa"] }
//!
//! # Signature primitives
//! rscrypto = { version = "0.6.4", default-features = false, features = ["signatures"] }
//!
//! # X25519 only
//! rscrypto = { version = "0.6.4", default-features = false, features = ["key-exchange"] }
//!
//! # Everything in auth/key-derivation
//! rscrypto = { version = "0.6.4", default-features = false, features = ["auth"] }
//! ```
//!
//! # API Conventions
//!
//! - Fixed-output MACs use `Type::mac(key, data)` and `Type::verify_tag(key, data, tag)` for
//!   one-shot helpers, plus `new` / `update` / `finalize` / `reset` for streaming.
//! - KMAC is variable-output, so the streaming path uses `finalize_into`.
//! - Standalone Poly1305 consumes a `Poly1305OneTimeKey`; it intentionally does not implement the
//!   reusable-key `Mac` trait.
//! - HKDF uses `new(salt, ikm)` for extract state, then `expand` / `expand_array`; one-shot helpers
//!   are `derive` / `derive_array`.
//! - ML-KEM uses FIPS 203 names: encapsulation keys are public, decapsulation keys are secret.
//! - Key generation uses `try_generate_with(fill)` for caller-owned entropy and `try_generate()` /
//!   `try_generate_keypair()` when `getrandom` is enabled.
//! - Native generic signing uses `TrySigner`, `TrySignerInto`, and `Verifier`; RSA generic
//!   signing/verifying goes through profile-bound wrappers.
//! - Public values use typed `from_bytes` / `to_bytes` / `as_bytes` wrappers.
//! - Secret values use typed `from_bytes` / `as_bytes` wrappers and require explicit
//!   `expose_secret()` opt-in for owned extraction.
//! - Verb-based operations such as `sign`, `verify`, and `diffie_hellman` stay on the typed
//!   wrappers.
//!
//! # Error Conventions
//!
//! - Authentication failures use [`crate::VerificationError`].
//! - HKDF oversized-output requests use `HkdfOutputLengthError`.
//! - X25519 low-order public inputs use `X25519Error`.
//!
//! # Modules
//!
//! - `argon2` - Argon2d/Argon2i/Argon2id password hashing (RFC 9106).
//! - `ecdsa` - ECDSA P-256/SHA-256 and P-384/SHA-384 signing and verification.
//! - `ed25519` - Ed25519 key and signature types.
//! - `hmac` - HMAC-based authentication.
//! - `hmac_sha3` - HMAC-SHA3 authentication.
//! - `hkdf` - HKDF extract-then-expand key derivation.
//! - `kmac` - KMAC128/KMAC256 variable-output MACs.
//! - `mlkem` - ML-KEM typed key, ciphertext, and shared-secret foundations.
//! - `poly1305` - Standalone Poly1305 one-time authenticator.
//! - `rsa` - RSA key import/export/generation, signing, verification, OAEP, and legacy
//!   RSAES-PKCS1-v1_5.
//! - `scrypt` - scrypt password hashing (RFC 7914).
//! - `x25519` - X25519 Diffie-Hellman key agreement.

#[cfg(feature = "argon2")]
pub mod argon2;
#[cfg(any(feature = "ed25519", feature = "x25519"))]
pub(crate) mod curve25519_edwards;
#[cfg(any(feature = "ecdsa-p256", feature = "ecdsa-p384"))]
pub mod ecdsa;
#[cfg(feature = "ed25519")]
pub mod ed25519;
#[cfg(feature = "hkdf")]
pub mod hkdf;
#[cfg(feature = "hmac")]
pub mod hmac;
#[cfg(feature = "hmac-sha3")]
pub mod hmac_sha3;
#[cfg(feature = "kmac")]
pub mod kmac;
#[cfg(feature = "ml-kem")]
pub mod mlkem;
#[cfg(feature = "pbkdf2")]
pub mod pbkdf2;
#[cfg(feature = "phc-strings")]
pub(crate) mod phc;
#[cfg(feature = "poly1305")]
pub mod poly1305;
#[cfg(feature = "rsa")]
pub mod rsa;
#[cfg(feature = "scrypt")]
pub mod scrypt;
#[cfg(feature = "x25519")]
pub mod x25519;

#[cfg(all(feature = "phc-strings", any(feature = "argon2", feature = "scrypt")))]
/// Result of a successful password verification.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum PasswordStatus {
  /// The stored cost profile and salt length match the generation profile.
  Current,
  /// The password is correct, but the stored profile should be regenerated.
  NeedsRehash,
}

#[cfg(all(feature = "phc-strings", any(feature = "argon2", feature = "scrypt")))]
impl PasswordStatus {
  /// Whether the verified password should be hashed again with the current profile.
  #[must_use]
  pub const fn needs_rehash(self) -> bool {
    matches!(self, Self::NeedsRehash)
  }
}

#[cfg(feature = "argon2")]
pub use argon2::{Argon2Context, Argon2Error, Argon2Params, Argon2d, Argon2i, Argon2id};
#[cfg(all(feature = "argon2", feature = "phc-strings"))]
pub use argon2::{Argon2VerificationLimits, Argon2idPassword};
#[cfg(all(feature = "diag", feature = "ed25519"))]
pub use curve25519_edwards::diag_ed25519_select_basepoint_cached_limb_digest;
#[cfg(all(feature = "diag", feature = "ed25519", target_arch = "x86_64"))]
pub use curve25519_edwards::{
  diag_ed25519_select_basepoint_cached_avx2_limb_digest, diag_ed25519_select_basepoint_cached_ifma_limb_digest,
};
#[cfg(any(feature = "ecdsa-p256", feature = "ecdsa-p384"))]
pub use ecdsa::{EcdsaError, EcdsaKeyGenerationError};
#[cfg(feature = "ecdsa-p256")]
pub use ecdsa::{EcdsaP256Keypair, EcdsaP256PublicKey, EcdsaP256SecretKey, EcdsaP256Signature};
#[cfg(feature = "ecdsa-p384")]
pub use ecdsa::{EcdsaP384Keypair, EcdsaP384PublicKey, EcdsaP384SecretKey, EcdsaP384Signature};
#[cfg(all(feature = "diag", feature = "ecdsa-p256"))]
pub use ecdsa::{
  diag_ecdsa_p256_basepoint_blinded_limb_digest, diag_ecdsa_p256_final_multiply_limb_digest,
  diag_ecdsa_p256_nonce_inverse_limb_digest, diag_ecdsa_p256_nonce_reduce_limb_digest,
  diag_ecdsa_p256_order_mul_blinded_fixed_r_limb_digest, diag_ecdsa_p256_order_mul_fixed_r_limb_digest,
  diag_ecdsa_p256_reduce_wide_order_limb_digest, diag_ecdsa_p256_scalar_finish_limb_digest,
  diag_ecdsa_p256_select_signing_generator_affine_limb_digest,
};
#[cfg(all(feature = "diag", feature = "ecdsa-p384"))]
pub use ecdsa::{
  diag_ecdsa_p384_basepoint_blinded_limb_digest, diag_ecdsa_p384_basepoint_r_limb_digest,
  diag_ecdsa_p384_final_multiply_limb_digest, diag_ecdsa_p384_nonce_inverse_limb_digest,
  diag_ecdsa_p384_nonce_reduce_limb_digest, diag_ecdsa_p384_order_mul_fixed_r_limb_digest,
  diag_ecdsa_p384_reduce_wide_order_limb_digest, diag_ecdsa_p384_scalar_finish_limb_digest,
  diag_ecdsa_p384_select_signing_generator_affine_limb_digest,
};
#[cfg(all(
  feature = "diag",
  feature = "ed25519",
  target_arch = "aarch64",
  any(target_os = "macos", target_os = "linux"),
  not(feature = "portable-only"),
  not(miri)
))]
pub use ed25519::diag_ed25519_verify_aarch64_asm_double_scalar_digest;
#[cfg(all(feature = "diag", feature = "ed25519"))]
pub use ed25519::{
  DiagEd25519VerifyScalars, diag_ed25519_verify_challenge_reduce_digest,
  diag_ed25519_verify_portable_double_scalar_digest, diag_ed25519_verify_public_decode_digest,
  diag_ed25519_verify_r_decode_digest, diag_ed25519_verify_scalars,
};
#[cfg(feature = "ed25519")]
pub use ed25519::{Ed25519Keypair, Ed25519PublicKey, Ed25519SecretKey, Ed25519Signature};
#[cfg(feature = "hkdf")]
pub use hkdf::{HkdfOutputLengthError, HkdfSha256, HkdfSha384, HkdfSha512};
#[cfg(all(feature = "diag", feature = "hkdf"))]
pub use hkdf::{diag_hkdf_sha256_derive_portable, diag_hkdf_sha384_derive_portable, diag_hkdf_sha512_derive_portable};
#[cfg(feature = "hmac")]
pub use hmac::{HmacSha256, HmacSha256Tag, HmacSha384, HmacSha384Tag, HmacSha512, HmacSha512Tag};
#[cfg(all(feature = "diag", feature = "hmac"))]
pub use hmac::{diag_hmac_sha256_verify_portable, diag_hmac_sha384_verify_portable, diag_hmac_sha512_verify_portable};
#[cfg(feature = "hmac-sha3")]
pub use hmac_sha3::{
  HmacSha3_224, HmacSha3_224Tag, HmacSha3_256, HmacSha3_256Tag, HmacSha3_384, HmacSha3_384Tag, HmacSha3_512,
  HmacSha3_512Tag,
};
#[cfg(feature = "kmac")]
pub use kmac::{Kmac128, Kmac256};
#[cfg(feature = "ml-kem")]
pub use mlkem::{
  MlKem512, MlKem512Ciphertext, MlKem512DecapsulationKey, MlKem512EncapsulationKey, MlKem512PreparedDecapsulationKey,
  MlKem512PreparedEncapsulationKey, MlKem512SharedSecret, MlKem768, MlKem768Ciphertext, MlKem768DecapsulationKey,
  MlKem768EncapsulationKey, MlKem768PreparedDecapsulationKey, MlKem768PreparedEncapsulationKey, MlKem768SharedSecret,
  MlKem1024, MlKem1024Ciphertext, MlKem1024DecapsulationKey, MlKem1024EncapsulationKey,
  MlKem1024PreparedDecapsulationKey, MlKem1024PreparedEncapsulationKey, MlKem1024SharedSecret, MlKemError,
};
#[cfg(all(feature = "diag", feature = "ml-kem"))]
pub use mlkem::{
  diag_mlkem_compress_decompress_values_digest, diag_mlkem_from_montgomery_product_domain_input_digest,
  diag_mlkem_inverse_ntt_montgomery_product_input_digest, diag_mlkem_multiply_ntts_add_assign_input_digest,
  diag_mlkem_ntt_input_digest, diag_mlkem_to_montgomery_product_domain_input_digest,
  diag_mlkem512_keygen_secret_noise_digest, diag_mlkem768_keygen_secret_noise_digest,
  diag_mlkem768_multiply_ntts_accumulate_input_digest, diag_mlkem1024_keygen_secret_noise_digest,
  diag_mlkem1024_multiply_ntts_accumulate_input_digest,
};
#[cfg(feature = "pbkdf2")]
pub use pbkdf2::{Pbkdf2Error, Pbkdf2Params, Pbkdf2Sha256, Pbkdf2Sha512, Pbkdf2VerifyPolicy};
#[cfg(all(feature = "diag", feature = "pbkdf2"))]
pub use pbkdf2::{diag_pbkdf2_sha256_verify_portable, diag_pbkdf2_sha512_verify_portable};
#[cfg(feature = "poly1305")]
pub use poly1305::{Poly1305, Poly1305OneTimeKey, Poly1305Tag};
#[cfg(feature = "rsa")]
pub use rsa::{
  RsaEncryptionError, RsaJwtAlgorithm, RsaJwtVerifier, RsaKeyError, RsaKeyGenerationContract, RsaKeyGenerationError,
  RsaOaepProfile, RsaPkcs1v15Profile, RsaPrivateKey, RsaPrivateKeyParts, RsaPrivateOpError, RsaPrivateScratch,
  RsaProtocolAlgorithmError, RsaPssProfile, RsaPublicExponent, RsaPublicExponentPolicy, RsaPublicKey,
  RsaPublicKeyPolicy, RsaPublicOpError, RsaPublicScratch, RsaSignatureProfile, RsaSignatureSigner,
  RsaSignatureVerifier, RsaTlsSignatureSchemes, RsaX509PublicKey, RsaX509PublicKeyAlgorithm,
};
#[cfg(all(feature = "rsa", feature = "diag"))]
pub use rsa::{
  diag_rsa_import_pkcs8_private_key_der_stage, diag_rsa_private_component_validation_32,
  diag_rsa_private_select_window_power_4, diag_rsa_validate_pkcs8_private_key_der,
  diag_rsa_validate_pkcs8_private_key_der_stage,
};
#[cfg(feature = "scrypt")]
pub use scrypt::{Scrypt, ScryptError, ScryptParams};
#[cfg(all(feature = "scrypt", feature = "phc-strings"))]
pub use scrypt::{ScryptPassword, ScryptVerificationLimits};
#[cfg(feature = "x25519")]
pub use x25519::{X25519Error, X25519PublicKey, X25519SecretKey, X25519SharedSecret};

#[cfg(all(feature = "diag", feature = "x25519"))]
pub use crate::backend::curve25519::diag_curve25519_conditional_swap;
pub use crate::traits::Mac;