1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
/***************************************************************************
* Copyright (c) 2024 Microsoft Corporation
* Copyright (c) 2025-present Eclipse ThreadX Contributors
*
* This program and the accompanying materials are made available under the
* terms of the MIT License which is available at
* https://opensource.org/licenses/MIT.
*
* SPDX-License-Identifier: MIT
**************************************************************************/
/**************************************************************************/
/**************************************************************************/
/** */
/** NetX Secure Component */
/** */
/** Transport Layer Security (TLS) - Generate Session Keys */
/** */
/**************************************************************************/
/**************************************************************************/
#define NX_SECURE_SOURCE_CODE
#include "nx_secure_tls.h"
#ifdef NX_SECURE_ENABLE_DTLS
#include "nx_secure_dtls.h"
#endif /* NX_SECURE_ENABLE_DTLS */
/* This local static buffer needs to be large enough to hold both the server random and the client random. */
static UCHAR _nx_secure_tls_gen_keys_random[NX_SECURE_TLS_RANDOM_SIZE << 1];
/**************************************************************************/
/* */
/* FUNCTION RELEASE */
/* */
/* _nx_secure_generate_session_keys PORTABLE C */
/* 6.4.3 */
/* AUTHOR */
/* */
/* Yanwu Cai, Microsoft Corporation */
/* */
/* DESCRIPTION */
/* */
/* This function generates the session keys used by TLS to encrypt */
/* the data being transmitted. It uses data gathered during the TLS */
/* handshake to generate a block of "key material" that is split into */
/* the various keys needed for each session. */
/* */
/* INPUT */
/* */
/* ciphersuite Selected cipher suite */
/* protocol_version Selected TLS version */
/* session_prf_method Pointer to PRF crypto method */
/* tls_key_material TLS key material */
/* master_sec Pointer to master secret */
/* prf_metadata Metadata for PRF crypto method*/
/* prf_metadata_size Size of PRF metadata */
/* */
/* OUTPUT */
/* */
/* status Completion status */
/* */
/* CALLS */
/* */
/* [nx_crypto_init] Initialize crypto */
/* [nx_crypto_operation] Crypto operation */
/* */
/* CALLED BY */
/* */
/* _nx_secure_tls_generate_keys Generate session keys */
/* */
/**************************************************************************/
UINT _nx_secure_generate_session_keys(const NX_SECURE_TLS_CIPHERSUITE_INFO *ciphersuite, USHORT protocol_version,
const NX_CRYPTO_METHOD *session_prf_method, NX_SECURE_TLS_KEY_MATERIAL *tls_key_material,
UCHAR *master_sec, VOID *prf_metadata, ULONG prf_metadata_size)
{
UCHAR *key_block; /* Maximum ciphersuite key size - AES_256_CBC_SHA, 2x32 byte keys + 2x20 byte MAC secrets + 2x16 IVs. */
UINT key_block_size;
UINT key_size;
UINT hash_size;
UINT iv_size;
UINT status;
const NX_CRYPTO_METHOD *session_cipher_method = NX_NULL;
VOID *handler = NX_NULL;
NX_PARAMETER_NOT_USED(protocol_version);
key_block_size = 0;
/* Working pointer into our new key material block since we are generating new keys. */
key_block = tls_key_material -> nx_secure_tls_new_key_material_data;
/* Get our session cipher method so we can get key sizes. */
session_cipher_method = ciphersuite -> nx_secure_tls_session_cipher;
/* Lookup ciphersuite data for key size. We need 2 keys for each session. */
key_size = session_cipher_method -> nx_crypto_key_size_in_bits >> 3;
/* Lookup ciphersuite data for hash size - used for the MAC secret. */
hash_size = ciphersuite -> nx_secure_tls_hash_size;
/* Lookup initialization vector size. */
iv_size = session_cipher_method -> nx_crypto_IV_size_in_bits >> 3;
/* Now calculate block size. Need client and server for each key, hash, and iv. Note that
key size and iv size may be zero depending on the ciphersuite, particularly when using
the NULL ciphers. */
key_block_size = 2 * (key_size + hash_size + iv_size);
/* Now generate keys from the master secret we obtained above. */
/* From the RFC (TLS 1.1):
To generate the key material, compute
key_block = PRF(SecurityParameters.master_secret,
"key expansion",
SecurityParameters.server_random +
SecurityParameters.client_random);
until enough output has been generated. Then the key_block is
partitioned as follows:
client_write_MAC_secret[SecurityParameters.hash_size]
server_write_MAC_secret[SecurityParameters.hash_size]
client_write_key[SecurityParameters.key_material_length]
server_write_key[SecurityParameters.key_material_length]
*/
/* The order of the randoms is reversed from that used for the master secret
when generating the key block. */
NX_SECURE_MEMCPY(_nx_secure_tls_gen_keys_random, tls_key_material -> nx_secure_tls_server_random,
NX_SECURE_TLS_RANDOM_SIZE); /* Use case of memcpy is verified. */
NX_SECURE_MEMCPY(&_nx_secure_tls_gen_keys_random[NX_SECURE_TLS_RANDOM_SIZE],
tls_key_material -> nx_secure_tls_client_random, NX_SECURE_TLS_RANDOM_SIZE); /* Use case of memcpy is verified. */
/* Key expansion uses the PRF to generate a block of key material from the master secret (generated
above) and the client and server random values transmitted during the initial hello negotiation. */
if (session_prf_method -> nx_crypto_init != NX_NULL)
{
status = session_prf_method -> nx_crypto_init((NX_CRYPTO_METHOD*)session_prf_method,
master_sec, 48,
&handler,
prf_metadata,
prf_metadata_size);
if(status != NX_CRYPTO_SUCCESS)
{
#ifdef NX_SECURE_KEY_CLEAR
NX_SECURE_MEMSET(_nx_secure_tls_gen_keys_random, 0, sizeof(_nx_secure_tls_gen_keys_random));
#endif /* NX_SECURE_KEY_CLEAR */
return(status);
}
}
if (session_prf_method -> nx_crypto_operation != NX_NULL)
{
status = session_prf_method -> nx_crypto_operation(NX_CRYPTO_PRF,
handler,
(NX_CRYPTO_METHOD*)session_prf_method,
(UCHAR *)"key expansion",
13,
_nx_secure_tls_gen_keys_random,
64,
NX_NULL,
key_block,
key_block_size,
prf_metadata,
prf_metadata_size,
NX_NULL,
NX_NULL);
#ifdef NX_SECURE_KEY_CLEAR
/* We now have a key block, clear our temporary secrets buffer. */
NX_SECURE_MEMSET(_nx_secure_tls_gen_keys_random, 0, sizeof(_nx_secure_tls_gen_keys_random));
#endif /* NX_SECURE_KEY_CLEAR */
if(status != NX_CRYPTO_SUCCESS)
{
/* Secrets cleared above. */
return(status);
}
}
if (session_prf_method -> nx_crypto_cleanup)
{
status = session_prf_method -> nx_crypto_cleanup(prf_metadata);
if(status != NX_CRYPTO_SUCCESS)
{
/* Secrets cleared above. */
return(status);
}
}
return(NX_SECURE_TLS_SUCCESS);
}
|
