rustls/crypto/tls13.rs
1use alloc::boxed::Box;
2use alloc::vec::Vec;
3
4use pki_types::FipsStatus;
5use zeroize::Zeroize;
6
7use super::hmac;
8use super::kx::ActiveKeyExchange;
9use crate::enums::ProtocolVersion;
10use crate::error::Error;
11
12/// Implementation of `HkdfExpander` via `hmac::Key`.
13pub struct HkdfExpanderUsingHmac(Box<dyn hmac::Key>);
14
15impl HkdfExpanderUsingHmac {
16 fn expand_unchecked(&self, info: &[&[u8]], output: &mut [u8]) {
17 let mut term = hmac::Tag::new(b"");
18
19 for (n, chunk) in output
20 .chunks_mut(self.0.tag_len())
21 .enumerate()
22 {
23 term = self
24 .0
25 .sign_concat(term.as_ref(), info, &[(n + 1) as u8]);
26 chunk.copy_from_slice(&term.as_ref()[..chunk.len()]);
27 }
28 }
29}
30
31impl HkdfExpander for HkdfExpanderUsingHmac {
32 fn expand_slice(&self, info: &[&[u8]], output: &mut [u8]) -> Result<(), OutputLengthError> {
33 if output.len() > 255 * self.0.tag_len() {
34 return Err(OutputLengthError);
35 }
36
37 self.expand_unchecked(info, output);
38 Ok(())
39 }
40
41 fn expand_block(&self, info: &[&[u8]]) -> OkmBlock {
42 let mut tag = [0u8; hmac::Tag::MAX_LEN];
43 let reduced_tag = &mut tag[..self.0.tag_len()];
44 self.expand_unchecked(info, reduced_tag);
45 OkmBlock::new(reduced_tag)
46 }
47
48 fn hash_len(&self) -> usize {
49 self.0.tag_len()
50 }
51}
52
53/// Implementation of `Hkdf` (and thence `HkdfExpander`) via `hmac::Hmac`.
54#[expect(clippy::exhaustive_structs)]
55pub struct HkdfUsingHmac<'a>(pub &'a dyn hmac::Hmac);
56
57impl Hkdf for HkdfUsingHmac<'_> {
58 fn extract_from_zero_ikm(&self, salt: Option<&[u8]>) -> Box<dyn HkdfExpander> {
59 let zeroes = [0u8; hmac::Tag::MAX_LEN];
60 Box::new(HkdfExpanderUsingHmac(self.0.with_key(
61 &self.extract_prk_from_secret(salt, &zeroes[..self.0.hash_output_len()]),
62 )))
63 }
64
65 fn extract_from_secret(&self, salt: Option<&[u8]>, secret: &[u8]) -> Box<dyn HkdfExpander> {
66 Box::new(HkdfExpanderUsingHmac(
67 self.0
68 .with_key(&self.extract_prk_from_secret(salt, secret)),
69 ))
70 }
71
72 fn expander_for_okm(&self, okm: &OkmBlock) -> Box<dyn HkdfExpander> {
73 Box::new(HkdfExpanderUsingHmac(self.0.with_key(okm.as_ref())))
74 }
75
76 fn hmac_sign(&self, key: &OkmBlock, message: &[u8]) -> hmac::Tag {
77 self.0
78 .with_key(key.as_ref())
79 .sign(&[message])
80 }
81}
82
83impl HkdfPrkExtract for HkdfUsingHmac<'_> {
84 fn extract_prk_from_secret(&self, salt: Option<&[u8]>, secret: &[u8]) -> Vec<u8> {
85 let zeroes = [0u8; hmac::Tag::MAX_LEN];
86 let salt = match salt {
87 Some(salt) => salt,
88 None => &zeroes[..self.0.hash_output_len()],
89 };
90 self.0
91 .with_key(salt)
92 .sign(&[secret])
93 .as_ref()
94 .to_vec()
95 }
96}
97
98/// Implementation of `HKDF-Expand` with an implicitly stored and immutable `PRK`.
99pub trait HkdfExpander: Send + Sync {
100 /// `HKDF-Expand(PRK, info, L)` into a slice.
101 ///
102 /// Where:
103 ///
104 /// - `PRK` is the implicit key material represented by this instance.
105 /// - `L` is `output.len()`.
106 /// - `info` is a slice of byte slices, which should be processed sequentially
107 /// (or concatenated if that is not possible).
108 ///
109 /// Returns `Err(OutputLengthError)` if `L` is larger than `255 * HashLen`.
110 /// Otherwise, writes to `output`.
111 fn expand_slice(&self, info: &[&[u8]], output: &mut [u8]) -> Result<(), OutputLengthError>;
112
113 /// `HKDF-Expand(PRK, info, L=HashLen)` returned as a value.
114 ///
115 /// - `PRK` is the implicit key material represented by this instance.
116 /// - `L := HashLen`.
117 /// - `info` is a slice of byte slices, which should be processed sequentially
118 /// (or concatenated if that is not possible).
119 ///
120 /// This is infallible, because by definition `OkmBlock` is always exactly
121 /// `HashLen` bytes long.
122 fn expand_block(&self, info: &[&[u8]]) -> OkmBlock;
123
124 /// Return what `HashLen` is for this instance.
125 ///
126 /// This must be no larger than [`OkmBlock::MAX_LEN`].
127 fn hash_len(&self) -> usize;
128}
129
130/// A HKDF implementation oriented to the needs of TLS1.3.
131///
132/// See [RFC5869](https://datatracker.ietf.org/doc/html/rfc5869) for the terminology
133/// used in this definition.
134///
135/// You can use [`HkdfUsingHmac`] which implements this trait on top of an implementation
136/// of [`hmac::Hmac`].
137pub trait Hkdf: Send + Sync {
138 /// `HKDF-Extract(salt, 0_HashLen)`
139 ///
140 /// `0_HashLen` is a string of `HashLen` zero bytes.
141 ///
142 /// A `salt` of `None` should be treated as a sequence of `HashLen` zero bytes.
143 fn extract_from_zero_ikm(&self, salt: Option<&[u8]>) -> Box<dyn HkdfExpander>;
144
145 /// `HKDF-Extract(salt, secret)`
146 ///
147 /// A `salt` of `None` should be treated as a sequence of `HashLen` zero bytes.
148 fn extract_from_secret(&self, salt: Option<&[u8]>, secret: &[u8]) -> Box<dyn HkdfExpander>;
149
150 /// `HKDF-Extract(salt, shared_secret)` where `shared_secret` is the result of a key exchange.
151 ///
152 /// Custom implementations should complete the key exchange by calling
153 /// `kx.complete(peer_pub_key)` and then using this as the input keying material to
154 /// `HKDF-Extract`.
155 ///
156 /// A `salt` of `None` should be treated as a sequence of `HashLen` zero bytes.
157 fn extract_from_kx_shared_secret(
158 &self,
159 salt: Option<&[u8]>,
160 kx: Box<dyn ActiveKeyExchange>,
161 peer_pub_key: &[u8],
162 ) -> Result<Box<dyn HkdfExpander>, Error> {
163 Ok(self.extract_from_secret(
164 salt,
165 kx.complete_for_tls_version(peer_pub_key, ProtocolVersion::TLSv1_3)?
166 .secret_bytes(),
167 ))
168 }
169
170 /// Build a `HkdfExpander` using `okm` as the secret PRK.
171 fn expander_for_okm(&self, okm: &OkmBlock) -> Box<dyn HkdfExpander>;
172
173 /// Signs `message` using `key` viewed as a HMAC key.
174 ///
175 /// This should use the same hash function as the HKDF functions in this
176 /// trait.
177 ///
178 /// See [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104) for the
179 /// definition of HMAC.
180 fn hmac_sign(&self, key: &OkmBlock, message: &[u8]) -> hmac::Tag;
181
182 /// Return the FIPS validation status of this implementation.
183 fn fips(&self) -> FipsStatus {
184 FipsStatus::Unvalidated
185 }
186}
187
188/// An extended HKDF implementation that supports directly extracting a pseudo-random key (PRK).
189///
190/// The base [`Hkdf`] trait is tailored to the needs of TLS 1.3, where all extracted PRKs
191/// are expanded as-is, and so can be safely encapsulated without exposing the caller
192/// to the key material.
193///
194/// In other contexts (for example, hybrid public key encryption (HPKE)) it may be necessary
195/// to use the extracted PRK directly for purposes other than an immediate expansion.
196/// This trait can be implemented to offer this functionality when it is required.
197pub trait HkdfPrkExtract: Hkdf {
198 /// `HKDF-Extract(salt, secret)`
199 ///
200 /// A `salt` of `None` should be treated as a sequence of `HashLen` zero bytes.
201 ///
202 /// In most cases you should prefer [`Hkdf::extract_from_secret`] and using the
203 /// returned [HkdfExpander] instead of handling the PRK directly.
204 fn extract_prk_from_secret(&self, salt: Option<&[u8]>, secret: &[u8]) -> Vec<u8>;
205}
206
207/// `HKDF-Expand(PRK, info, L)` to construct any type from a byte array.
208///
209/// - `PRK` is the implicit key material represented by this instance.
210/// - `L := N`; N is the size of the byte array.
211/// - `info` is a slice of byte slices, which should be processed sequentially
212/// (or concatenated if that is not possible).
213///
214/// This is infallible, because the set of types (and therefore their length) is known
215/// at compile time.
216pub fn expand<T, const N: usize>(expander: &dyn HkdfExpander, info: &[&[u8]]) -> T
217where
218 T: From<[u8; N]>,
219{
220 let mut output = [0u8; N];
221 expander
222 .expand_slice(info, &mut output)
223 .expect("expand type parameter T is too large");
224 T::from(output)
225}
226
227/// Output key material from HKDF, as a value type.
228#[derive(Clone)]
229pub struct OkmBlock {
230 buf: [u8; Self::MAX_LEN],
231 used: usize,
232}
233
234impl OkmBlock {
235 /// Build a single OKM block by copying a byte slice.
236 ///
237 /// The slice can be up to [`OkmBlock::MAX_LEN`] bytes in length.
238 pub fn new(bytes: &[u8]) -> Self {
239 let mut tag = Self {
240 buf: [0u8; Self::MAX_LEN],
241 used: bytes.len(),
242 };
243 tag.buf[..bytes.len()].copy_from_slice(bytes);
244 tag
245 }
246
247 /// Maximum supported HMAC tag size: supports up to SHA512.
248 pub const MAX_LEN: usize = 64;
249}
250
251impl Drop for OkmBlock {
252 fn drop(&mut self) {
253 self.buf.zeroize();
254 }
255}
256
257impl AsRef<[u8]> for OkmBlock {
258 fn as_ref(&self) -> &[u8] {
259 &self.buf[..self.used]
260 }
261}
262
263/// An error type used for `HkdfExpander::expand_slice` when
264/// the slice exceeds the maximum HKDF output length.
265#[expect(clippy::exhaustive_structs)]
266#[derive(Debug)]
267pub struct OutputLengthError;