Debian Codegraph @

test/hkdf.c

raw
1 /**************************** hkdf.c ***************************/
2 /***************** See RFC 6234 for details. *******************/
3 /* Copyright (c) 2011 IETF Trust and the persons identified as */
4 /* authors of the code. All rights reserved. */
5 /* See sha.h for terms of use and redistribution. */
6 /* */
7 /* SPDX-License-Identifier: BSD-3-Clause */
8
9 /*
10 * Description:
11 * This file implements the HKDF algorithm (HMAC-based
12 * Extract-and-Expand Key Derivation Function, RFC 5869),
13 * expressed in terms of the various SHA algorithms.
14 *
15 * Note:
16 * Prefix for internal API changed from "hkdf" to "RRFC5869Hkdf".
17 */
18
19 #include "sha.h"
20 #include <string.h>
21 #include <stdlib.h>
22
23 /*
24 * RFC5869Hkdf
25 *
26 * Description:
27 * This function will generate keying material using HKDF.
28 *
29 * Parameters:
30 * whichSha: [in]
31 * One of SHA1, SHA224, SHA256, SHA384, SHA512
32 * salt[ ]: [in]
33 * The optional salt value (a non-secret random value);
34 * if not provided (salt == NULL), it is set internally
35 * to a string of HashLen(whichSha) zeros.
36 * salt_len: [in]
37 * The length of the salt value. (Ignored if salt == NULL.)
38 * ikm[ ]: [in]
39 * Input keying material.
40 * ikm_len: [in]
41 * The length of the input keying material.
42 * info[ ]: [in]
43 * The optional context and application specific information.
44 * If info == NULL or a zero-length string, it is ignored.
45 * info_len: [in]
46 * The length of the optional context and application specific
47 * information. (Ignored if info == NULL.)
48 * okm[ ]: [out]
49 * Where the HKDF is to be stored.
50 * okm_len: [in]
51 * The length of the buffer to hold okm.
52 * okm_len must be <= 255 * USHABlockSize(whichSha)
53 *
54 * Notes:
55 * Calls hkdfExtract() and hkdfExpand().
56 *
57 * Returns:
58 * sha Error Code.
59 *
60 */
61 int RFC5869Hkdf(SHAversion whichSha,
62 const unsigned char *salt, int salt_len,
63 const unsigned char *ikm, int ikm_len,
64 const unsigned char *info, int info_len,
65 uint8_t okm[ ], int okm_len)
66 {
67 uint8_t prk[USHAMaxHashSize];
68 return RFC5869HkdfExtract(whichSha, salt, salt_len, ikm, ikm_len, prk) ||
69 RFC5869HkdfExpand(whichSha, prk, USHAHashSize(whichSha), info,
70 info_len, okm, okm_len);
71 }
72
73 /*
74 * RFC5869HkdfExtract
75 *
76 * Description:
77 * This function will perform HKDF extraction.
78 *
79 * Parameters:
80 * whichSha: [in]
81 * One of SHA1, SHA224, SHA256, SHA384, SHA512
82 * salt[ ]: [in]
83 * The optional salt value (a non-secret random value);
84 * if not provided (salt == NULL), it is set internally
85 * to a string of HashLen(whichSha) zeros.
86 * salt_len: [in]
87 * The length of the salt value. (Ignored if salt == NULL.)
88 * ikm[ ]: [in]
89 * Input keying material.
90 * ikm_len: [in]
91 * The length of the input keying material.
92 * prk[ ]: [out]
93 * Array where the HKDF extraction is to be stored.
94 * Must be larger than USHAHashSize(whichSha);
95 *
96 * Returns:
97 * sha Error Code.
98 *
99 */
100 int RFC5869HkdfExtract(SHAversion whichSha,
101 const unsigned char *salt, int salt_len,
102 const unsigned char *ikm, int ikm_len,
103 uint8_t prk[USHAMaxHashSize])
104 {
105 unsigned char nullSalt[USHAMaxHashSize];
106 if (salt == 0) {
107 salt = nullSalt;
108 salt_len = USHAHashSize(whichSha);
109 memset(nullSalt, '\0', salt_len);
110 } else if (salt_len < 0) {
111 return shaBadParam;
112 }
113 return RFC2104Hmac(whichSha, ikm, ikm_len, salt, salt_len, prk);
114 }
115
116 /*
117 * RFC5869HkdfExpand
118 *
119 * Description:
120 * This function will perform HKDF expansion.
121 *
122 * Parameters:
123 * whichSha: [in]
124 * One of SHA1, SHA224, SHA256, SHA384, SHA512
125 * prk[ ]: [in]
126 * The pseudo-random key to be expanded; either obtained
127 * directly from a cryptographically strong, uniformly
128 * distributed pseudo-random number generator, or as the
129 * output from hkdfExtract().
130 * prk_len: [in]
131 * The length of the pseudo-random key in prk;
132 * should at least be equal to USHAHashSize(whichSHA).
133 * info[ ]: [in]
134 * The optional context and application specific information.
135 * If info == NULL or a zero-length string, it is ignored.
136 * info_len: [in]
137 * The length of the optional context and application specific
138 * information. (Ignored if info == NULL.)
139 * okm[ ]: [out]
140 * Where the HKDF is to be stored.
141 * okm_len: [in]
142 * The length of the buffer to hold okm.
143 * okm_len must be <= 255 * USHABlockSize(whichSha)
144 *
145 * Returns:
146 * sha Error Code.
147 *
148 */
149 int RFC5869HkdfExpand(SHAversion whichSha, const uint8_t prk[ ], int prk_len,
150 const unsigned char *info, int info_len,
151 uint8_t okm[ ], int okm_len)
152 {
153 int hash_len, N;
154 unsigned char T[USHAMaxHashSize];
155 int Tlen, where, i;
156
157 if (info == 0) {
158 info = (const unsigned char *)"";
159 info_len = 0;
160 } else if (info_len < 0) {
161 return shaBadParam;
162 }
163 if (okm_len <= 0) return shaBadParam;
164 if (!okm) return shaBadParam;
165
166 hash_len = USHAHashSize(whichSha);
167 if (prk_len < hash_len) return shaBadParam;
168 N = okm_len / hash_len;
169 if ((okm_len % hash_len) != 0) N++;
170 if (N > 255) return shaBadParam;
171
172 Tlen = 0;
173 where = 0;
174 for (i = 1; i <= N; i++) {
175 HMACContext context;
176 unsigned char c = i;
177 int ret = RFC2104HmacReset(&context, whichSha, prk, prk_len) ||
178 RFC2104HmacInput(&context, T, Tlen) ||
179 RFC2104HmacInput(&context, info, info_len) ||
180 RFC2104HmacInput(&context, &c, 1) ||
181 RFC2104HmacResult(&context, T);
182 if (ret != shaSuccess) return ret;
183 memcpy(okm + where, T,
184 (i != N) ? hash_len : (okm_len - where));
185 where += hash_len;
186 Tlen = hash_len;
187 }
188 return shaSuccess;
189 }
190
191 /*
192 * RFC5869HkdfReset
193 *
194 * Description:
195 * This function will initialize the hkdfContext in preparation
196 * for key derivation using the modular HKDF interface for
197 * arbitrary length inputs.
198 *
199 * Parameters:
200 * context: [in/out]
201 * The context to reset.
202 * whichSha: [in]
203 * One of SHA1, SHA224, SHA256, SHA384, SHA512
204 * salt[ ]: [in]
205 * The optional salt value (a non-secret random value);
206 * if not provided (salt == NULL), it is set internally
207 * to a string of HashLen(whichSha) zeros.
208 * salt_len: [in]
209 * The length of the salt value. (Ignored if salt == NULL.)
210 *
211 * Returns:
212 * sha Error Code.
213 *
214 */
215 int RFC5869HkdfReset(HKDFContext *context, enum SHAversion whichSha,
216 const unsigned char *salt, int salt_len)
217 {
218 unsigned char nullSalt[USHAMaxHashSize];
219 if (!context) return shaNull;
220
221 context->whichSha = whichSha;
222 context->hashSize = USHAHashSize(whichSha);
223 if (salt == 0) {
224 salt = nullSalt;
225 salt_len = context->hashSize;
226 memset(nullSalt, '\0', salt_len);
227 }
228
229 return RFC2104HmacReset(&context->hmacContext, whichSha, salt, salt_len);
230 }
231
232 /*
233 * hkdfInput
234 *
235 * Description:
236 * This function accepts an array of octets as the next portion
237 * of the input keying material. It may be called multiple times.
238 *
239 * Parameters:
240 * context: [in/out]
241 * The HKDF context to update.
242 * ikm[ ]: [in]
243 * An array of octets representing the next portion of
244 * the input keying material.
245 * ikm_len: [in]
246 * The length of ikm.
247 *
248 * Returns:
249 * sha Error Code.
250 *
251 */
252 int RFC5869HkdfInput(HKDFContext *context, const unsigned char *ikm,
253 int ikm_len)
254 {
255 if (!context) return shaNull;
256 if (context->Corrupted) return context->Corrupted;
257 if (context->Computed) return context->Corrupted = shaStateError;
258 return RFC2104HmacInput(&context->hmacContext, ikm, ikm_len);
259 }
260
261 /*
262 * RFC5869HkdfFinalBits
263 *
264 * Description:
265 * This function will add in any final bits of the
266 * input keying material.
267 *
268 * Parameters:
269 * context: [in/out]
270 * The HKDF context to update
271 * ikm_bits: [in]
272 * The final bits of the input keying material, in the upper
273 * portion of the byte. (Use 0b###00000 instead of 0b00000###
274 * to input the three bits ###.)
275 * ikm_bit_count: [in]
276 * The number of bits in message_bits, between 1 and 7.
277 *
278 * Returns:
279 * sha Error Code.
280 */
281 int RFC5869HkdfFinalBits(HKDFContext *context, uint8_t ikm_bits,
282 unsigned int ikm_bit_count)
283 {
284 if (!context) return shaNull;
285 if (context->Corrupted) return context->Corrupted;
286 if (context->Computed) return context->Corrupted = shaStateError;
287 return RFC2104HmacFinalBits(&context->hmacContext, ikm_bits, ikm_bit_count);
288 }
289
290 /*
291 * RFC5869HkdfResult
292 *
293 * Description:
294 * This function will finish the HKDF extraction and perform the
295 * final HKDF expansion.
296 *
297 * Parameters:
298 * context: [in/out]
299 * The HKDF context to use to calculate the HKDF hash.
300 * prk[ ]: [out]
301 * An optional location to store the HKDF extraction.
302 * Either NULL, or pointer to a buffer that must be
303 * larger than USHAHashSize(whichSha);
304 * info[ ]: [in]
305 * The optional context and application specific information.
306 * If info == NULL or a zero-length string, it is ignored.
307 * info_len: [in]
308 * The length of the optional context and application specific
309 * information. (Ignored if info == NULL.)
310 * okm[ ]: [out]
311 * Where the HKDF is to be stored.
312 * okm_len: [in]
313 * The length of the buffer to hold okm.
314 * okm_len must be <= 255 * USHABlockSize(whichSha)
315 *
316 * Returns:
317 * sha Error Code.
318 *
319 */
320 int RFC5869HkdfResult(HKDFContext *context,
321 uint8_t prk[USHAMaxHashSize],
322 const unsigned char *info, int info_len,
323 uint8_t okm[ ], int okm_len)
324 {
325 uint8_t prkbuf[USHAMaxHashSize];
326 int ret;
327
328 if (!context) return shaNull;
329 if (context->Corrupted) return context->Corrupted;
330 if (context->Computed) return context->Corrupted = shaStateError;
331 if (!okm) return context->Corrupted = shaBadParam;
332 if (!prk) prk = prkbuf;
333
334 ret = RFC2104HmacResult(&context->hmacContext, prk) ||
335 RFC5869HkdfExpand(context->whichSha, prk, context->hashSize, info,
336 info_len, okm, okm_len);
337 context->Computed = 1;
338 return context->Corrupted = ret;
339 }