Coverage Report

Created: 2026-11-15 06:55

next uncovered line (L), next uncovered region (R), next uncovered branch (B)
/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 *)&params;
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, &paramsi, 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 *)&params;
297
1.88M
    paramsi.len = sizeof(params);
298
1.88M
    derived = PK11_DeriveWithFlags(prk, deriveMech,
299
1.88M
                                   &paramsi, 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
}