/src/nss/lib/ssl/tls13hkdf.c
Line | Count | Source |
1 | | /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
2 | | /* |
3 | | * TLS 1.3 Protocol |
4 | | * |
5 | | * This Source Code Form is subject to the terms of the Mozilla Public |
6 | | * License, v. 2.0. If a copy of the MPL was not distributed with this |
7 | | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
8 | | |
9 | | #include "keyhi.h" |
10 | | #include "pk11func.h" |
11 | | #include "secitem.h" |
12 | | #include "ssl.h" |
13 | | #include "sslt.h" |
14 | | #include "sslerr.h" |
15 | | #include "sslimpl.h" |
16 | | |
17 | | /* This table contains the mapping between TLS hash identifiers and the |
18 | | * PKCS#11 identifiers */ |
19 | | static const struct { |
20 | | SSLHashType hash; |
21 | | CK_MECHANISM_TYPE pkcs11Mech; |
22 | | unsigned int hashSize; |
23 | | } kTlsHkdfInfo[] = { |
24 | | { ssl_hash_none, 0, 0 }, |
25 | | { ssl_hash_md5, 0, 0 }, |
26 | | { ssl_hash_sha1, 0, 0 }, |
27 | | { ssl_hash_sha224, 0 }, |
28 | | { ssl_hash_sha256, CKM_SHA256, 32 }, |
29 | | { ssl_hash_sha384, CKM_SHA384, 48 }, |
30 | | { ssl_hash_sha512, CKM_SHA512, 64 } |
31 | | }; |
32 | | |
33 | | SECStatus |
34 | | tls13_HkdfExtract(PK11SymKey *ikm1, PK11SymKey *ikm2, SSLHashType baseHash, |
35 | | PK11SymKey **prkp) |
36 | 21.8k | { |
37 | 21.8k | CK_HKDF_PARAMS params; |
38 | 21.8k | SECItem paramsi; |
39 | 21.8k | PK11SymKey *prk; |
40 | 21.8k | static const PRUint8 zeroKeyBuf[HASH_LENGTH_MAX]; |
41 | 21.8k | SECItem zeroKeyItem = { siBuffer, CONST_CAST(PRUint8, zeroKeyBuf), kTlsHkdfInfo[baseHash].hashSize }; |
42 | 21.8k | static const PRUint8 zeroSaltBuf[HASH_LENGTH_MAX]; |
43 | 21.8k | SECItem zeroSaltItem = { siBuffer, CONST_CAST(PRUint8, zeroSaltBuf), kTlsHkdfInfo[baseHash].hashSize }; |
44 | 21.8k | PK11SlotInfo *slot = NULL; |
45 | 21.8k | PK11SymKey *newIkm2 = NULL; |
46 | 21.8k | PK11SymKey *movedIkm1 = NULL; |
47 | 21.8k | PK11SymKey *movedIkm2 = NULL; |
48 | 21.8k | SECStatus rv; |
49 | | |
50 | 21.8k | if (!prkp) { |
51 | 0 | PORT_SetError(SEC_ERROR_INVALID_ARGS); |
52 | 0 | return SECFailure; |
53 | 0 | } |
54 | | |
55 | 21.8k | params.bExtract = CK_TRUE; |
56 | 21.8k | params.bExpand = CK_FALSE; |
57 | 21.8k | params.prfHashMechanism = kTlsHkdfInfo[baseHash].pkcs11Mech; |
58 | 21.8k | params.pInfo = NULL; |
59 | 21.8k | params.ulInfoLen = 0UL; |
60 | 21.8k | params.pSalt = NULL; |
61 | 21.8k | params.ulSaltLen = 0UL; |
62 | 21.8k | params.hSaltKey = CK_INVALID_HANDLE; |
63 | 21.8k | params.ulSaltType = 0; |
64 | | |
65 | 21.8k | CK_OBJECT_CLASS ikm2Class = CKO_DATA; /* in case we don't have it we create one of CKO_DATA type */ |
66 | | |
67 | 21.8k | if (ikm2) { |
68 | | /* Get the object class of the key(ikm2) */ |
69 | 11.9k | SECItem classItem = { siBuffer, NULL, 0 }; |
70 | 11.9k | rv = PK11_ReadRawAttribute(PK11_TypeSymKey, ikm2, CKA_CLASS, &classItem); |
71 | 11.9k | if (rv != SECSuccess || classItem.len != sizeof(CK_OBJECT_CLASS)) { |
72 | 0 | SECITEM_FreeItem(&classItem, PR_FALSE); |
73 | 0 | goto cleanup; |
74 | 0 | } |
75 | 11.9k | memcpy(&ikm2Class, classItem.data, sizeof(ikm2Class)); |
76 | 11.9k | SECITEM_FreeItem(&classItem, PR_FALSE); |
77 | 11.9k | } else { |
78 | | /* A zero ikm2 is a key of hash-length 0s. */ |
79 | | /* if we have ikm1, put the zero key in the same slot */ |
80 | 9.93k | if (ikm1) { |
81 | 4.97k | slot = PK11_GetSlotFromKey(ikm1); |
82 | 4.97k | } |
83 | | |
84 | 9.93k | if (!slot || PK11_DoesMechanism(slot, CKM_HKDF_DERIVE) == PR_FALSE) { |
85 | | /* fallback if ikm1 is not provided or the slot doesn't support the mechanism*/ |
86 | 4.96k | if (slot) { |
87 | 0 | PK11_FreeSlot(slot); |
88 | 0 | } |
89 | 4.96k | slot = PK11_GetBestSlot(CKM_HKDF_DERIVE, NULL); |
90 | 4.96k | } |
91 | | |
92 | 9.93k | if (!slot) { |
93 | 0 | rv = SECFailure; |
94 | 0 | goto cleanup; |
95 | 0 | } |
96 | | |
97 | 9.93k | newIkm2 = PK11_ImportDataKey(slot, CKM_HKDF_DERIVE, PK11_OriginUnwrap, |
98 | 9.93k | CKA_DERIVE, &zeroKeyItem, NULL); |
99 | 9.93k | if (!newIkm2) { |
100 | 0 | rv = SECFailure; |
101 | 0 | goto cleanup; |
102 | 0 | } |
103 | 9.93k | ikm2 = newIkm2; |
104 | 9.93k | } |
105 | 21.8k | PORT_Assert(ikm2); |
106 | | |
107 | 21.8k | if (!ikm1) { |
108 | 11.9k | if (ikm2Class == CKO_DATA) { |
109 | | /* since PKCS #11 v3.0 it is mandatory to provide CKF_HKDF_SALT_DATA |
110 | | * if key(ikm2) is of type CKO_DATA. see. Section 6.62.3 */ |
111 | 5.55k | params.pSalt = zeroSaltItem.data; |
112 | 5.55k | params.ulSaltLen = zeroSaltItem.len; |
113 | 5.55k | params.ulSaltType = CKF_HKDF_SALT_DATA; |
114 | 6.36k | } else { |
115 | | /* PKCS #11 v3.0 has and explict NULL value, which equates to |
116 | | * a sequence of zeros equal in length to the HMAC. */ |
117 | 6.36k | params.ulSaltType = CKF_HKDF_SALT_NULL; |
118 | 6.36k | } |
119 | 11.9k | } else { |
120 | | /* PKCS #11 v3.0 can take the salt as a key handle */ |
121 | 9.94k | rv = PK11_SymKeysToSameSlot(CKM_HKDF_DERIVE, |
122 | 9.94k | CKA_DERIVE, CKA_DERIVE, |
123 | 9.94k | ikm2, ikm1, &movedIkm2, &movedIkm1); |
124 | | |
125 | 9.94k | if (rv != SECSuccess) { |
126 | | /* couldn't move the keys, try extracting the salt */ |
127 | 0 | SECItem *salt; |
128 | 0 | rv = PK11_ExtractKeyValue(ikm1); |
129 | 0 | if (rv != SECSuccess) { |
130 | 0 | goto cleanup; |
131 | 0 | } |
132 | 0 | salt = PK11_GetKeyData(ikm1); |
133 | 0 | if (!salt) { |
134 | 0 | rv = SECFailure; |
135 | 0 | goto cleanup; |
136 | 0 | } |
137 | 0 | PORT_Assert(salt->len > 0); |
138 | | /* Set up for Salt as Data instead of Salt as key */ |
139 | 0 | params.pSalt = salt->data; |
140 | 0 | params.ulSaltLen = salt->len; |
141 | 0 | params.ulSaltType = CKF_HKDF_SALT_DATA; |
142 | 9.94k | } else { |
143 | | /* use the moved keys */ |
144 | 9.94k | if (movedIkm1) { |
145 | 4.96k | ikm1 = movedIkm1; |
146 | 4.96k | } |
147 | 9.94k | if (movedIkm2) { |
148 | 0 | ikm2 = movedIkm2; |
149 | 0 | } |
150 | | |
151 | 9.94k | params.hSaltKey = PK11_GetSymKeyHandle(ikm1); |
152 | 9.94k | params.ulSaltType = CKF_HKDF_SALT_KEY; |
153 | 9.94k | } |
154 | 9.94k | } |
155 | | |
156 | 21.8k | paramsi.data = (unsigned char *)¶ms; |
157 | 21.8k | paramsi.len = sizeof(params); |
158 | | |
159 | 21.8k | PORT_Assert(kTlsHkdfInfo[baseHash].pkcs11Mech); |
160 | 21.8k | PORT_Assert(kTlsHkdfInfo[baseHash].hashSize); |
161 | 21.8k | PORT_Assert(kTlsHkdfInfo[baseHash].hash == baseHash); |
162 | | |
163 | 21.8k | if (params.ulSaltType == CKF_HKDF_SALT_DATA) { |
164 | 5.55k | PORT_Assert(params.hSaltKey == CK_INVALID_HANDLE); |
165 | 5.55k | PORT_Assert(params.pSalt != NULL); |
166 | 5.55k | } |
167 | 21.8k | if (params.ulSaltType == CKF_HKDF_SALT_NULL) { |
168 | 6.36k | PORT_Assert(ikm2Class != CKO_DATA); |
169 | 6.36k | PORT_Assert(params.hSaltKey == CK_INVALID_HANDLE); |
170 | 6.36k | PORT_Assert(params.pSalt == NULL); |
171 | 6.36k | PORT_Assert(params.ulSaltLen == 0UL); |
172 | 6.36k | } |
173 | 21.8k | if (params.ulSaltType == CKF_HKDF_SALT_KEY) { |
174 | 9.94k | PORT_Assert(params.hSaltKey != CK_INVALID_HANDLE); |
175 | 9.94k | PORT_Assert(params.pSalt == NULL); |
176 | 9.94k | PORT_Assert(params.ulSaltLen == 0UL); |
177 | 9.94k | } |
178 | | |
179 | 21.8k | PRINT_BUF(50, (NULL, "HKDF Extract: IKM1/Salt", params.pSalt, params.ulSaltLen)); |
180 | 21.8k | PRINT_KEY(50, (NULL, "HKDF Extract: IKM2", ikm2)); |
181 | | |
182 | 21.8k | prk = PK11_Derive(ikm2, CKM_HKDF_DERIVE, ¶msi, CKM_HKDF_DERIVE, |
183 | 21.8k | CKA_DERIVE, 0); |
184 | | |
185 | 21.8k | if (!prk) { |
186 | 0 | rv = SECFailure; |
187 | 0 | goto cleanup; |
188 | 0 | } |
189 | | |
190 | 21.8k | PRINT_KEY(50, (NULL, "HKDF Extract", prk)); |
191 | 21.8k | *prkp = prk; |
192 | 21.8k | rv = SECSuccess; |
193 | | |
194 | 21.8k | cleanup: |
195 | 21.8k | PK11_FreeSymKey(movedIkm1); |
196 | 21.8k | PK11_FreeSymKey(movedIkm2); |
197 | 21.8k | PK11_FreeSymKey(newIkm2); |
198 | 21.8k | if (slot) |
199 | 9.93k | PK11_FreeSlot(slot); |
200 | 21.8k | return rv; |
201 | 21.8k | } |
202 | | |
203 | | SECStatus |
204 | | tls13_HkdfExpandLabelGeneral(CK_MECHANISM_TYPE deriveMech, PK11SymKey *prk, |
205 | | SSLHashType baseHash, |
206 | | const PRUint8 *handshakeHash, unsigned int handshakeHashLen, |
207 | | const char *label, unsigned int labelLen, |
208 | | CK_MECHANISM_TYPE algorithm, unsigned int keySize, |
209 | | SSLProtocolVariant variant, PK11SymKey **keyp) |
210 | 1.88M | { |
211 | 1.88M | CK_HKDF_PARAMS params; |
212 | 1.88M | SECItem paramsi = { siBuffer, NULL, 0 }; |
213 | | /* Size of info array needs to be big enough to hold the maximum Prefix, |
214 | | * Label, plus HandshakeHash. If it's ever to small, the code will abort. |
215 | | */ |
216 | 1.88M | PRUint8 info[256]; |
217 | 1.88M | sslBuffer infoBuf = SSL_BUFFER(info); |
218 | 1.88M | PK11SymKey *derived; |
219 | 1.88M | SECStatus rv; |
220 | 1.88M | const char *kLabelPrefixTls = "tls13 "; |
221 | 1.88M | const char *kLabelPrefixDtls = "dtls13"; |
222 | 1.88M | const unsigned int kLabelPrefixLen = |
223 | 1.88M | (variant == ssl_variant_stream) ? strlen(kLabelPrefixTls) : strlen(kLabelPrefixDtls); |
224 | 1.88M | const char *kLabelPrefix = |
225 | 1.88M | (variant == ssl_variant_stream) ? kLabelPrefixTls : kLabelPrefixDtls; |
226 | 1.88M | CK_FLAGS flags = 0; |
227 | 1.88M | CK_KEY_TYPE targetKeyType = PK11_GetKeyType(algorithm, keySize); |
228 | | |
229 | | /* PKCS #11 Mechanisms v3.0 Sec 2.62.4: CKM_HKDF_DATA outputs CKO_DATA. |
230 | | * Sec 4.5.2: CKO_DATA objects cannot hold crypto operation flags */ |
231 | 1.88M | if (deriveMech != CKM_HKDF_DATA) { |
232 | 1.26M | flags |= CKF_SIGN | CKF_VERIFY; |
233 | | |
234 | | /* PKCS #11 v3.0 Sec 2.8.2: CKK_GENERIC_SECRET and CKK_HKDF |
235 | | * explicitly do not support encrypt/decrypt operations. */ |
236 | 1.26M | if (targetKeyType != CKK_GENERIC_SECRET && targetKeyType != CKK_HKDF) { |
237 | 618k | flags |= CKF_ENCRYPT | CKF_DECRYPT; |
238 | 618k | } |
239 | 1.26M | } |
240 | | |
241 | 1.88M | PORT_Assert(prk); |
242 | 1.88M | PORT_Assert(keyp); |
243 | 1.88M | if ((handshakeHashLen > 255) || |
244 | 1.88M | (handshakeHash == NULL && handshakeHashLen > 0) || |
245 | 1.88M | (labelLen > 255 - kLabelPrefixLen)) { |
246 | 0 | PORT_SetError(SEC_ERROR_INVALID_ARGS); |
247 | 0 | return SECFailure; |
248 | 0 | } |
249 | | |
250 | | /* |
251 | | * [draft-ietf-tls-tls13-11] Section 7.1: |
252 | | * |
253 | | * HKDF-Expand-Label(Secret, Label, HashValue, Length) = |
254 | | * HKDF-Expand(Secret, HkdfLabel, Length) |
255 | | * |
256 | | * Where HkdfLabel is specified as: |
257 | | * |
258 | | * struct HkdfLabel { |
259 | | * uint16 length; |
260 | | * opaque label<9..255>; |
261 | | * opaque hash_value<0..255>; |
262 | | * }; |
263 | | * |
264 | | * Where: |
265 | | * - HkdfLabel.length is Length |
266 | | * - HkdfLabel.hash_value is HashValue. |
267 | | * - HkdfLabel.label is "TLS 1.3, " + Label |
268 | | * |
269 | | */ |
270 | 1.88M | rv = sslBuffer_AppendNumber(&infoBuf, keySize, 2); |
271 | 1.88M | if (rv != SECSuccess) { |
272 | 0 | return SECFailure; |
273 | 0 | } |
274 | 1.88M | rv = sslBuffer_AppendNumber(&infoBuf, labelLen + kLabelPrefixLen, 1); |
275 | 1.88M | if (rv != SECSuccess) { |
276 | 0 | return SECFailure; |
277 | 0 | } |
278 | 1.88M | rv = sslBuffer_Append(&infoBuf, kLabelPrefix, kLabelPrefixLen); |
279 | 1.88M | if (rv != SECSuccess) { |
280 | 0 | return SECFailure; |
281 | 0 | } |
282 | 1.88M | rv = sslBuffer_Append(&infoBuf, label, labelLen); |
283 | 1.88M | if (rv != SECSuccess) { |
284 | 0 | return SECFailure; |
285 | 0 | } |
286 | 1.88M | rv = sslBuffer_AppendVariable(&infoBuf, handshakeHash, handshakeHashLen, 1); |
287 | 1.88M | if (rv != SECSuccess) { |
288 | 0 | return SECFailure; |
289 | 0 | } |
290 | | |
291 | 1.88M | params.bExtract = CK_FALSE; |
292 | 1.88M | params.bExpand = CK_TRUE; |
293 | 1.88M | params.prfHashMechanism = kTlsHkdfInfo[baseHash].pkcs11Mech; |
294 | 1.88M | params.pInfo = SSL_BUFFER_BASE(&infoBuf); |
295 | 1.88M | params.ulInfoLen = SSL_BUFFER_LEN(&infoBuf); |
296 | 1.88M | paramsi.data = (unsigned char *)¶ms; |
297 | 1.88M | paramsi.len = sizeof(params); |
298 | 1.88M | derived = PK11_DeriveWithFlags(prk, deriveMech, |
299 | 1.88M | ¶msi, algorithm, |
300 | 1.88M | CKA_DERIVE, keySize, |
301 | 1.88M | flags); |
302 | 1.88M | if (!derived) { |
303 | 0 | return SECFailure; |
304 | 0 | } |
305 | | |
306 | 1.88M | *keyp = derived; |
307 | | |
308 | 1.88M | #ifdef TRACE |
309 | 1.88M | if (ssl_trace >= 50) { |
310 | | /* Make sure the label is null terminated. */ |
311 | 0 | char labelStr[100]; |
312 | 0 | PORT_Memcpy(labelStr, label, labelLen); |
313 | 0 | labelStr[labelLen] = 0; |
314 | 0 | SSL_TRC(50, ("HKDF Expand: label='tls13 %s',requested length=%d", |
315 | 0 | labelStr, keySize)); |
316 | 0 | } |
317 | 1.88M | PRINT_KEY(50, (NULL, "PRK", prk)); |
318 | 1.88M | PRINT_BUF(50, (NULL, "Hash", handshakeHash, handshakeHashLen)); |
319 | 1.88M | PRINT_BUF(50, (NULL, "Info", SSL_BUFFER_BASE(&infoBuf), |
320 | 1.88M | SSL_BUFFER_LEN(&infoBuf))); |
321 | 1.88M | PRINT_KEY(50, (NULL, "Derived key", derived)); |
322 | 1.88M | #endif |
323 | | |
324 | 1.88M | return SECSuccess; |
325 | 1.88M | } |
326 | | |
327 | | SECStatus |
328 | | tls13_HkdfExpandLabel(PK11SymKey *prk, SSLHashType baseHash, |
329 | | const PRUint8 *handshakeHash, unsigned int handshakeHashLen, |
330 | | const char *label, unsigned int labelLen, |
331 | | CK_MECHANISM_TYPE algorithm, unsigned int keySize, |
332 | | SSLProtocolVariant variant, PK11SymKey **keyp) |
333 | 1.26M | { |
334 | 1.26M | return tls13_HkdfExpandLabelGeneral(CKM_HKDF_DERIVE, prk, baseHash, |
335 | 1.26M | handshakeHash, handshakeHashLen, |
336 | 1.26M | label, labelLen, algorithm, keySize, |
337 | 1.26M | variant, keyp); |
338 | 1.26M | } |
339 | | |
340 | | SECStatus |
341 | | tls13_HkdfExpandLabelRaw(PK11SymKey *prk, SSLHashType baseHash, |
342 | | const PRUint8 *handshakeHash, unsigned int handshakeHashLen, |
343 | | const char *label, unsigned int labelLen, |
344 | | SSLProtocolVariant variant, unsigned char *output, |
345 | | unsigned int outputLen) |
346 | 614k | { |
347 | 614k | PK11SymKey *derived = NULL; |
348 | 614k | SECItem *rawkey; |
349 | 614k | SECStatus rv; |
350 | | |
351 | | /* the result is not really a key, it's a data object */ |
352 | 614k | rv = tls13_HkdfExpandLabelGeneral(CKM_HKDF_DATA, prk, baseHash, |
353 | 614k | handshakeHash, handshakeHashLen, |
354 | 614k | label, labelLen, CKM_HKDF_DERIVE, outputLen, |
355 | 614k | variant, &derived); |
356 | 614k | if (rv != SECSuccess || !derived) { |
357 | 0 | goto abort; |
358 | 0 | } |
359 | | |
360 | 614k | rv = PK11_ExtractKeyValue(derived); |
361 | 614k | if (rv != SECSuccess) { |
362 | 0 | goto abort; |
363 | 0 | } |
364 | | |
365 | 614k | rawkey = PK11_GetKeyData(derived); |
366 | 614k | if (!rawkey) { |
367 | 0 | goto abort; |
368 | 0 | } |
369 | | |
370 | 614k | PORT_Assert(rawkey->len == outputLen); |
371 | 614k | memcpy(output, rawkey->data, outputLen); |
372 | 614k | PK11_FreeSymKey(derived); |
373 | | |
374 | 614k | return SECSuccess; |
375 | | |
376 | 0 | abort: |
377 | 0 | if (derived) { |
378 | 0 | PK11_FreeSymKey(derived); |
379 | 0 | } |
380 | 0 | PORT_SetError(SSL_ERROR_SYM_KEY_CONTEXT_FAILURE); |
381 | 0 | return SECFailure; |
382 | 614k | } |