libcrux_traits/kem/
arrayref.rs

1//! This module contains the trait and related errors for a KEM that takes array references as
2//! arguments and writes to outputs to mutable array references.
3
4use libcrux_secrets::U8;
5
6/// A Key Encapsulation Mechanism (KEM). This trait is the most low-level and mostly used in the
7/// implementation of other, more usabe APIs on top.
8pub trait Kem<
9    const EK_LEN: usize,
10    const DK_LEN: usize,
11    const CT_LEN: usize,
12    const SS_LEN: usize,
13    const RAND_KEYGEN_LEN: usize,
14    const RAND_ENCAPS_LEN: usize,
15>
16{
17    /// Generate a pair of encapsulation and decapsulation keys.
18    /// It is the responsibility of the caller to ensure  that the `rand` argument is actually
19    /// random.
20    fn keygen(
21        ek: &mut [u8; EK_LEN],
22        dk: &mut [U8; DK_LEN],
23        rand: &[U8; RAND_KEYGEN_LEN],
24    ) -> Result<(), KeyGenError>;
25
26    /// Encapsulate a shared secret towards a given encapsulation key.
27    /// It is the responsibility of the caller to ensure  that the `rand` argument is actually
28    /// random.
29    fn encaps(
30        ct: &mut [u8; CT_LEN],
31        ss: &mut [U8; SS_LEN],
32        ek: &[u8; EK_LEN],
33        rand: &[U8; RAND_ENCAPS_LEN],
34    ) -> Result<(), EncapsError>;
35
36    /// Decapsulate a shared secret.
37    fn decaps(
38        ss: &mut [U8; SS_LEN],
39        ct: &[u8; CT_LEN],
40        dk: &[U8; DK_LEN],
41    ) -> Result<(), DecapsError>;
42}
43
44/// Error generating key with provided randomness
45#[derive(Debug)]
46pub enum KeyGenError {
47    /// Error generating key with provided randomness
48    InvalidRandomness,
49
50    /// An unknown error occurred
51    Unknown,
52}
53
54/// Error indicating that encapsulating failed
55#[derive(Debug)]
56pub enum EncapsError {
57    /// Encapsulation key is invalid
58    InvalidEncapsKey,
59
60    /// Error encapsulating key with provided randomness
61    InvalidRandomness,
62
63    /// An unknown error occurred
64    Unknown,
65}
66
67/// Error indicating that decapsulating failed
68#[derive(Debug)]
69pub enum DecapsError {
70    /// Ciphertext key is invalid
71    InvalidCiphertext,
72
73    /// Decapsulation key is invalid
74    InvalidDecapsKey,
75
76    /// An unknown error occurred
77    Unknown,
78}
79
80impl core::fmt::Display for KeyGenError {
81    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
82        let text = match self {
83            KeyGenError::InvalidRandomness => "error generating key with provided randomness",
84            KeyGenError::Unknown => "an unknown error occurred",
85        };
86
87        f.write_str(text)
88    }
89}
90
91impl core::fmt::Display for EncapsError {
92    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
93        let text = match self {
94            EncapsError::InvalidEncapsKey => "encapsulation key is invalid",
95            EncapsError::InvalidRandomness => "error generating key with provided randomness",
96            EncapsError::Unknown => "an unknown error occurred",
97        };
98
99        f.write_str(text)
100    }
101}
102
103impl core::fmt::Display for DecapsError {
104    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
105        let text = match self {
106            DecapsError::InvalidDecapsKey => "encapsulation key is invalid",
107            DecapsError::InvalidCiphertext => "ciphertext is invalid",
108            DecapsError::Unknown => "an unknown error occurred",
109        };
110
111        f.write_str(text)
112    }
113}
114
115#[cfg(feature = "error-in-core")]
116/// Here we implement the Error trait. This has only been added to core relatively recently, so we
117/// are hiding that behind a feature.
118mod error_in_core {
119    impl core::error::Error for super::EncapsError {}
120    impl core::error::Error for super::DecapsError {}
121    impl core::error::Error for super::KeyGenError {}
122}
libcrux_traits/kem/arrayref.rs

libcrux_traits/kem/
arrayref.rs
