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
//! Traits and structs for key encapsulation mechanisms
use crate::{Deserializable, HpkeError, Serializable};
use core::fmt::Debug;
use generic_array::{ArrayLength, GenericArray};
use rand_core::{CryptoRng, RngCore};
use zeroize::Zeroize;
mod dhkem;
pub use dhkem::*;
/// Represents authenticated encryption functionality
pub trait Kem: Sized {
/// The key exchange's public key type. If you want to generate a keypair, see
/// `Kem::gen_keypair` or `Kem::derive_keypair`
type PublicKey: Clone + Debug + PartialEq + Eq + Serializable + Deserializable;
/// The key exchange's private key type. If you want to generate a keypair, see
/// `Kem::gen_keypair` or `Kem::derive_keypair`
type PrivateKey: Clone + PartialEq + Eq + Serializable + Deserializable;
/// Computes the public key of a given private key
fn sk_to_pk(sk: &Self::PrivateKey) -> Self::PublicKey;
/// The encapsulated key for this KEM. This is used by the recipient to derive the shared
/// secret.
type EncappedKey: Clone + Serializable + Deserializable;
/// The size of a shared secret in this KEM
#[doc(hidden)]
type NSecret: ArrayLength<u8>;
/// The algorithm identifier for a KEM implementation
const KEM_ID: u16;
/// Deterministically derives a keypair from the given input keying material
///
/// Requirements
/// ============
/// This keying material SHOULD have as many bits of entropy as the bit length of a secret key,
/// i.e., `8 * Self::PrivateKey::size()`. For X25519 and P-256, this is 256 bits of
/// entropy.
fn derive_keypair(ikm: &[u8]) -> (Self::PrivateKey, Self::PublicKey);
/// Generates a random keypair using the given RNG
fn gen_keypair<R: CryptoRng + RngCore>(csprng: &mut R) -> (Self::PrivateKey, Self::PublicKey) {
// Make some keying material that's the size of a private key
let mut ikm: GenericArray<u8, <Self::PrivateKey as Serializable>::OutputSize> =
GenericArray::default();
// Fill it with randomness
csprng.fill_bytes(&mut ikm);
// Run derive_keypair using the KEM's KDF
Self::derive_keypair(&ikm)
}
/// Derives a shared secret given the encapsulated key and the recipients secret key. If
/// `pk_sender_id` is given, the sender's identity will be tied to the shared secret.
///
/// Return Value
/// ============
/// Returns a shared secret on success. If an error happened during key exchange, returns
/// `Err(HpkeError::DecapError)`.
#[doc(hidden)]
fn decap(
sk_recip: &Self::PrivateKey,
pk_sender_id: Option<&Self::PublicKey>,
encapped_key: &Self::EncappedKey,
) -> Result<SharedSecret<Self>, HpkeError>;
/// Derives a shared secret and an ephemeral pubkey that the owner of the reciepint's pubkey
/// can use to derive the same shared secret. If `sk_sender_id` is given, the sender's identity
/// will be tied to the shared secret. All this does is generate an ephemeral keypair and pass
/// to `encap_with_eph`.
///
/// Return Value
/// ============
/// Returns a shared secret and encapped key on success. If an error happened during key
/// exchange, returns `Err(HpkeError::EncapError)`.
#[doc(hidden)]
fn encap<R: CryptoRng + RngCore>(
pk_recip: &Self::PublicKey,
sender_id_keypair: Option<(&Self::PrivateKey, &Self::PublicKey)>,
csprng: &mut R,
) -> Result<(SharedSecret<Self>, Self::EncappedKey), HpkeError>;
}
// Kem is used as a type parameter everywhere. To avoid confusion, alias it
use Kem as KemTrait;
/// A convenience type for `[u8; NSecret]` for any given KEM
#[doc(hidden)]
pub struct SharedSecret<Kem: KemTrait>(pub GenericArray<u8, Kem::NSecret>);
impl<Kem: KemTrait> Default for SharedSecret<Kem> {
fn default() -> SharedSecret<Kem> {
SharedSecret(GenericArray::<u8, Kem::NSecret>::default())
}
}
// SharedSecrets should zeroize on drop
impl<Kem: KemTrait> Zeroize for SharedSecret<Kem> {
fn zeroize(&mut self) {
self.0.zeroize()
}
}
impl<Kem: KemTrait> Drop for SharedSecret<Kem> {
fn drop(&mut self) {
self.zeroize();
}
}
#[cfg(test)]
mod tests {
use crate::{kem::Kem as KemTrait, Deserializable, Serializable};
use rand::{rngs::StdRng, SeedableRng};
macro_rules! test_encap_correctness {
($test_name:ident, $kem_ty:ty) => {
/// Tests that encap and decap produce the same shared secret when composed
#[test]
fn $test_name() {
type Kem = $kem_ty;
let mut csprng = StdRng::from_entropy();
let (sk_recip, pk_recip) = Kem::gen_keypair(&mut csprng);
// Encapsulate a random shared secret
let (auth_shared_secret, encapped_key) =
Kem::encap(&pk_recip, None, &mut csprng).unwrap();
// Decap it
let decapped_auth_shared_secret =
Kem::decap(&sk_recip, None, &encapped_key).unwrap();
// Ensure that the encapsulated secret is what decap() derives
assert_eq!(auth_shared_secret.0, decapped_auth_shared_secret.0);
//
// Now do it with the auth, i.e., using the sender's identity keys
//
// Make a sender identity keypair
let (sk_sender_id, pk_sender_id) = Kem::gen_keypair(&mut csprng);
// Encapsulate a random shared secret
let (auth_shared_secret, encapped_key) = Kem::encap(
&pk_recip,
Some((&sk_sender_id, &pk_sender_id.clone())),
&mut csprng,
)
.unwrap();
// Decap it
let decapped_auth_shared_secret =
Kem::decap(&sk_recip, Some(&pk_sender_id), &encapped_key).unwrap();
// Ensure that the encapsulated secret is what decap() derives
assert_eq!(auth_shared_secret.0, decapped_auth_shared_secret.0);
}
};
}
/// Tests that an deserialize-serialize round trip on an encapped key ends up at the same value
macro_rules! test_encapped_serialize {
($test_name:ident, $kem_ty:ty) => {
#[test]
fn $test_name() {
type Kem = $kem_ty;
// Encapsulate a random shared secret
let encapped_key = {
let mut csprng = StdRng::from_entropy();
let (_, pk_recip) = Kem::gen_keypair(&mut csprng);
Kem::encap(&pk_recip, None, &mut csprng).unwrap().1
};
// Serialize it
let encapped_key_bytes = encapped_key.to_bytes();
// Deserialize it
let new_encapped_key =
<<Kem as KemTrait>::EncappedKey as Deserializable>::from_bytes(
&encapped_key_bytes,
)
.unwrap();
assert_eq!(
new_encapped_key.0, encapped_key.0,
"encapped key doesn't serialize correctly"
);
}
};
}
#[cfg(feature = "secp")]
mod secp_tests {
use super::*;
test_encap_correctness!(test_encap_correctness_secp, crate::kem::SecpK256HkdfSha256);
test_encapped_serialize!(test_encapped_serialize_secp, crate::kem::SecpK256HkdfSha256);
}
}