rscrypto 0.6.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

//! Key-encapsulation mechanism traits.
//!
//! KEMs establish a shared secret over a public channel through three
//! operations: key generation, encapsulation, and decapsulation. The trait
//! keeps those operations static and typed so implementations can remain
//! `no_std`, allocation-free, and dispatch-free.

use core::fmt::Debug;

/// Key-encapsulation mechanism with fixed-size typed inputs and outputs.
///
/// Probabilistic operations receive randomness from a caller-supplied fill
/// closure. This avoids baking an operating-system RNG dependency into the
/// trait while still giving concrete implementations one explicit place to
/// request fresh random bytes.
pub trait Kem {
  /// Encapsulation key size in bytes.
  const ENCAPSULATION_KEY_SIZE: usize;

  /// Decapsulation key size in bytes.
  const DECAPSULATION_KEY_SIZE: usize;

  /// Ciphertext size in bytes.
  const CIPHERTEXT_SIZE: usize;

  /// Shared-secret size in bytes.
  const SHARED_SECRET_SIZE: usize;

  /// Public key used by the encapsulating party.
  type EncapsulationKey: Clone + Eq + Debug + AsRef<[u8]>;

  /// Private key used by the decapsulating party.
  type DecapsulationKey: Clone + Eq + Debug + AsRef<[u8]>;

  /// Public ciphertext sent by the encapsulating party.
  type Ciphertext: Clone + Eq + Debug + AsRef<[u8]>;

  /// Secret established by encapsulation or decapsulation.
  type SharedSecret: Clone + Eq + Debug + AsRef<[u8]>;

  /// Error returned by key generation.
  type KeyGenerationError;

  /// Error returned by encapsulation.
  type EncapsulationError;

  /// Error returned by decapsulation.
  type DecapsulationError;

  /// Generate an encapsulation/decapsulation key pair.
  ///
  /// Implementations decide how many bytes are requested from `fill_random`.
  /// The closure must provide fresh cryptographic randomness and return an
  /// error if it cannot completely fill the requested buffer.
  fn generate_keypair(
    fill_random: impl FnMut(&mut [u8]) -> Result<(), Self::KeyGenerationError>,
  ) -> Result<(Self::EncapsulationKey, Self::DecapsulationKey), Self::KeyGenerationError>;

  /// Encapsulate to `encapsulation_key`.
  ///
  /// Implementations decide how many bytes are requested from `fill_random`.
  /// The returned ciphertext is public; the returned shared secret is secret
  /// key material and must be handled accordingly.
  #[must_use = "KEM encapsulation output must be used; dropping it loses the established shared secret"]
  fn encapsulate(
    encapsulation_key: &Self::EncapsulationKey,
    fill_random: impl FnMut(&mut [u8]) -> Result<(), Self::EncapsulationError>,
  ) -> Result<(Self::Ciphertext, Self::SharedSecret), Self::EncapsulationError>;

  /// Decapsulate `ciphertext` with `decapsulation_key`.
  ///
  /// Concrete KEMs must preserve their scheme's failure behavior. For ML-KEM,
  /// malformed input handling and implicit rejection must not reveal which
  /// component failed.
  #[must_use = "KEM decapsulation output must be checked and used; dropping the Result can ignore input failure"]
  fn decapsulate(
    decapsulation_key: &Self::DecapsulationKey,
    ciphertext: &Self::Ciphertext,
  ) -> Result<Self::SharedSecret, Self::DecapsulationError>;
}