1 | // Copyright 2015 Brian Smith. |
2 | // |
3 | // Permission to use, copy, modify, and/or distribute this software for any |
4 | // purpose with or without fee is hereby granted, provided that the above |
5 | // copyright notice and this permission notice appear in all copies. |
6 | // |
7 | // THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES |
8 | // WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
9 | // MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY |
10 | // SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
11 | // WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION |
12 | // OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN |
13 | // CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
14 | |
15 | //! HMAC-based Extract-and-Expand Key Derivation Function. |
16 | //! |
17 | //! HKDF is specified in [RFC 5869]. |
18 | //! |
19 | //! [RFC 5869]: https://tools.ietf.org/html/rfc5869 |
20 | |
21 | use crate::{error, hmac}; |
22 | |
23 | /// An HKDF algorithm. |
24 | #[derive (Clone, Copy, Debug, Eq, PartialEq)] |
25 | pub struct Algorithm(hmac::Algorithm); |
26 | |
27 | impl Algorithm { |
28 | /// The underlying HMAC algorithm. |
29 | #[inline ] |
30 | pub fn hmac_algorithm(&self) -> hmac::Algorithm { |
31 | self.0 |
32 | } |
33 | } |
34 | |
35 | /// HKDF using HMAC-SHA-1. Obsolete. |
36 | pub static HKDF_SHA1_FOR_LEGACY_USE_ONLY: Algorithm = |
37 | Algorithm(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY); |
38 | |
39 | /// HKDF using HMAC-SHA-256. |
40 | pub static HKDF_SHA256: Algorithm = Algorithm(hmac::HMAC_SHA256); |
41 | |
42 | /// HKDF using HMAC-SHA-384. |
43 | pub static HKDF_SHA384: Algorithm = Algorithm(hmac::HMAC_SHA384); |
44 | |
45 | /// HKDF using HMAC-SHA-512. |
46 | pub static HKDF_SHA512: Algorithm = Algorithm(hmac::HMAC_SHA512); |
47 | |
48 | impl KeyType for Algorithm { |
49 | fn len(&self) -> usize { |
50 | self.0.digest_algorithm().output_len() |
51 | } |
52 | } |
53 | |
54 | /// A salt for HKDF operations. |
55 | #[derive (Debug)] |
56 | pub struct Salt(hmac::Key); |
57 | |
58 | impl Salt { |
59 | /// Constructs a new `Salt` with the given value based on the given digest |
60 | /// algorithm. |
61 | /// |
62 | /// Constructing a `Salt` is relatively expensive so it is good to reuse a |
63 | /// `Salt` object instead of re-constructing `Salt`s with the same value. |
64 | pub fn new(algorithm: Algorithm, value: &[u8]) -> Self { |
65 | Self(hmac::Key::new(algorithm.0, value)) |
66 | } |
67 | |
68 | /// The [HKDF-Extract] operation. |
69 | /// |
70 | /// [HKDF-Extract]: https://tools.ietf.org/html/rfc5869#section-2.2 |
71 | pub fn extract(&self, secret: &[u8]) -> Prk { |
72 | // The spec says that if no salt is provided then a key of |
73 | // `digest_alg.output_len` bytes of zeros is used. But, HMAC keys are |
74 | // already zero-padded to the block length, which is larger than the output |
75 | // length of the extract step (the length of the digest). Consequently the |
76 | // `Key` constructor will automatically do the right thing for a |
77 | // zero-length string. |
78 | let salt = &self.0; |
79 | let prk = hmac::sign(salt, secret); |
80 | Prk(hmac::Key::new(salt.algorithm(), prk.as_ref())) |
81 | } |
82 | |
83 | /// The algorithm used to derive this salt. |
84 | #[inline ] |
85 | pub fn algorithm(&self) -> Algorithm { |
86 | Algorithm(self.0.algorithm()) |
87 | } |
88 | } |
89 | |
90 | impl From<Okm<'_, Algorithm>> for Salt { |
91 | fn from(okm: Okm<'_, Algorithm>) -> Self { |
92 | Self(hmac::Key::from(Okm { |
93 | prk: okm.prk, |
94 | info: okm.info, |
95 | len: okm.len().0, |
96 | len_cached: okm.len_cached, |
97 | })) |
98 | } |
99 | } |
100 | |
101 | /// The length of the OKM (Output Keying Material) for a `Prk::expand()` call. |
102 | pub trait KeyType { |
103 | /// The length that `Prk::expand()` should expand its input to. |
104 | fn len(&self) -> usize; |
105 | } |
106 | |
107 | /// A HKDF PRK (pseudorandom key). |
108 | #[derive (Clone, Debug)] |
109 | pub struct Prk(hmac::Key); |
110 | |
111 | impl Prk { |
112 | /// Construct a new `Prk` directly with the given value. |
113 | /// |
114 | /// Usually one can avoid using this. It is useful when the application |
115 | /// intentionally wants to leak the PRK secret, e.g. to implement |
116 | /// `SSLKEYLOGFILE` functionality. |
117 | pub fn new_less_safe(algorithm: Algorithm, value: &[u8]) -> Self { |
118 | Self(hmac::Key::new(algorithm.hmac_algorithm(), value)) |
119 | } |
120 | |
121 | /// The [HKDF-Expand] operation. |
122 | /// |
123 | /// [HKDF-Expand]: https://tools.ietf.org/html/rfc5869#section-2.3 |
124 | /// |
125 | /// Fails if (and only if) `len` is too large. |
126 | #[inline ] |
127 | pub fn expand<'a, L: KeyType>( |
128 | &'a self, |
129 | info: &'a [&'a [u8]], |
130 | len: L, |
131 | ) -> Result<Okm<'a, L>, error::Unspecified> { |
132 | let len_cached = len.len(); |
133 | if len_cached > 255 * self.0.algorithm().digest_algorithm().output_len() { |
134 | return Err(error::Unspecified); |
135 | } |
136 | Ok(Okm { |
137 | prk: self, |
138 | info, |
139 | len, |
140 | len_cached, |
141 | }) |
142 | } |
143 | } |
144 | |
145 | impl From<Okm<'_, Algorithm>> for Prk { |
146 | fn from(okm: Okm<Algorithm>) -> Self { |
147 | Self(hmac::Key::from(Okm { |
148 | prk: okm.prk, |
149 | info: okm.info, |
150 | len: okm.len().0, |
151 | len_cached: okm.len_cached, |
152 | })) |
153 | } |
154 | } |
155 | |
156 | /// An HKDF OKM (Output Keying Material) |
157 | /// |
158 | /// Intentionally not `Clone` or `Copy` as an OKM is generally only safe to |
159 | /// use once. |
160 | #[derive (Debug)] |
161 | pub struct Okm<'a, L: KeyType> { |
162 | prk: &'a Prk, |
163 | info: &'a [&'a [u8]], |
164 | len: L, |
165 | len_cached: usize, |
166 | } |
167 | |
168 | impl<L: KeyType> Okm<'_, L> { |
169 | /// The `OkmLength` given to `Prk::expand()`. |
170 | #[inline ] |
171 | pub fn len(&self) -> &L { |
172 | &self.len |
173 | } |
174 | |
175 | /// Fills `out` with the output of the HKDF-Expand operation for the given |
176 | /// inputs. |
177 | /// |
178 | /// Fails if (and only if) the requested output length is larger than 255 |
179 | /// times the size of the digest algorithm's output. (This is the limit |
180 | /// imposed by the HKDF specification due to the way HKDF's counter is |
181 | /// constructed.) |
182 | #[inline ] |
183 | pub fn fill(self, out: &mut [u8]) -> Result<(), error::Unspecified> { |
184 | fill_okm(self.prk, self.info, out, self.len_cached) |
185 | } |
186 | } |
187 | |
188 | fn fill_okm( |
189 | prk: &Prk, |
190 | info: &[&[u8]], |
191 | out: &mut [u8], |
192 | len: usize, |
193 | ) -> Result<(), error::Unspecified> { |
194 | if out.len() != len { |
195 | return Err(error::Unspecified); |
196 | } |
197 | |
198 | let digest_alg = prk.0.algorithm().digest_algorithm(); |
199 | assert!(digest_alg.block_len() >= digest_alg.output_len()); |
200 | |
201 | let mut ctx = hmac::Context::with_key(&prk.0); |
202 | |
203 | let mut n = 1u8; |
204 | let mut out = out; |
205 | loop { |
206 | for info in info { |
207 | ctx.update(info); |
208 | } |
209 | ctx.update(&[n]); |
210 | |
211 | let t = ctx.sign(); |
212 | let t = t.as_ref(); |
213 | |
214 | // Append `t` to the output. |
215 | out = if out.len() < digest_alg.output_len() { |
216 | let len = out.len(); |
217 | out.copy_from_slice(&t[..len]); |
218 | &mut [] |
219 | } else { |
220 | let (this_chunk, rest) = out.split_at_mut(digest_alg.output_len()); |
221 | this_chunk.copy_from_slice(t); |
222 | rest |
223 | }; |
224 | |
225 | if out.is_empty() { |
226 | return Ok(()); |
227 | } |
228 | |
229 | ctx = hmac::Context::with_key(&prk.0); |
230 | ctx.update(t); |
231 | n = n.checked_add(1).unwrap(); |
232 | } |
233 | } |
234 | |