1 /**************************************************************************/
2 /* */
3 /* Copyright (c) Microsoft Corporation. All rights reserved. */
4 /* */
5 /* This software is licensed under the Microsoft Software License */
6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */
7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */
8 /* and in the root directory of this software. */
9 /* */
10 /**************************************************************************/
11
12
13 /**************************************************************************/
14 /**************************************************************************/
15 /** */
16 /** NetX Secure Component */
17 /** */
18 /** Transport Layer Security (TLS) */
19 /** */
20 /**************************************************************************/
21 /**************************************************************************/
22
23 #define NX_SECURE_SOURCE_CODE
24
25 #include "nx_secure_tls.h"
26
27
28 /**************************************************************************/
29 /* */
30 /* FUNCTION RELEASE */
31 /* */
32 /* _nx_secure_tls_1_3_transcript_hash_save PORTABLE C */
33 /* 6.1.8 */
34 /* AUTHOR */
35 /* */
36 /* Timothy Stapko, Microsoft Corporation */
37 /* */
38 /* DESCRIPTION */
39 /* */
40 /* TLS 1.3 requires that a hash of handshake messages (the */
41 /* "transcript hash") be generated at various points to be fed into */
42 /* secrets and key generation process. This Function is used to */
43 /* indicate when a hash needs to be generated, and what that hash is */
44 /* stored as (e.g. ClientHello transcript hash). */
45 /* */
46 /* INPUT */
47 /* */
48 /* tls_session TLS control block */
49 /* */
50 /* OUTPUT */
51 /* */
52 /* status Completion status */
53 /* */
54 /* CALLS */
55 /* */
56 /* */
57 /* CALLED BY */
58 /* */
59 /* */
60 /* */
61 /* RELEASE HISTORY */
62 /* */
63 /* DATE NAME DESCRIPTION */
64 /* */
65 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */
66 /* 09-30-2020 Timothy Stapko Modified comment(s), */
67 /* verified memcpy use cases, */
68 /* resulting in version 6.1 */
69 /* 08-02-2021 Timothy Stapko Modified comment(s), added */
70 /* hash clone and cleanup, */
71 /* resulting in version 6.1.8 */
72 /* */
73 /**************************************************************************/
74 #if (NX_SECURE_TLS_TLS_1_3_ENABLED)
75
_nx_secure_tls_1_3_transcript_hash_save(NX_SECURE_TLS_SESSION * tls_session,UINT hash_index,UINT need_copy)76 UINT _nx_secure_tls_1_3_transcript_hash_save(NX_SECURE_TLS_SESSION *tls_session, UINT hash_index, UINT need_copy)
77 {
78 UINT status = NX_NOT_SUCCESSFUL;
79 const NX_CRYPTO_METHOD *method_ptr;
80 UINT hash_size;
81 CHAR *metadata;
82
83
84 /* Don't oveflow the hash array. */
85 if(hash_index > NX_SECURE_TLS_1_3_MAX_TRANSCRIPT_HASHES)
86 {
87 return(NX_INVALID_PARAMETERS);
88 }
89
90 /* Hash handshake record using ciphersuite hash routine. */
91 if (tls_session -> nx_secure_tls_session_ciphersuite == NX_NULL)
92 {
93 /* Set the hash method to the default of SHA-256 if no ciphersuite is available. */
94 method_ptr = tls_session -> nx_secure_tls_crypto_table->nx_secure_tls_handshake_hash_sha256_method;
95
96 }
97 else
98 {
99 /* The handshake transcript hash in TLS 1.3 uses the hash routine associated with the chosen ciphersuite. */
100 method_ptr = tls_session -> nx_secure_tls_session_ciphersuite -> nx_secure_tls_hash;
101 }
102
103 /* Generate the "transcript hash" for the point in the handshake where this message falls.
104 * This is needed for TLS 1.3 key generation which uses the hash of all previous handshake
105 * messages at multiple points during the handshake. Instead of saving the entirety of the
106 * handshake messages, just generate a hash when each record is hashed. */
107
108 /* If nx_secure_tls_handshake_hash_sha256_metadata can't be modified for it will be used later, copy it to scratch buffer. */
109 if (need_copy)
110 {
111
112 /* Copy over the handshake hash state into a local structure to do the intermediate calculation. */
113 NX_SECURE_HASH_METADATA_CLONE(tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_scratch,
114 tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_metadata,
115 tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_metadata_size); /* Use case of memcpy is verified. */
116
117 metadata = tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_scratch;
118 }
119 else
120 {
121 metadata = tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_metadata;
122 }
123
124 /* Get hash output size. */
125 hash_size = (method_ptr ->nx_crypto_ICV_size_in_bits >> 3);
126
127
128 /* Generate a hash using our temporary copy of the hash metadata, place it into the TLS Session transcript hash array. */
129 if (method_ptr -> nx_crypto_operation != NX_NULL)
130 {
131 status = method_ptr -> nx_crypto_operation(NX_CRYPTO_HASH_CALCULATE,
132 tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_handler,
133 (NX_CRYPTO_METHOD*)method_ptr,
134 NX_NULL,
135 0,
136 NX_NULL,
137 0,
138 NX_NULL,
139 &tls_session->nx_secure_tls_key_material.nx_secure_tls_transcript_hashes[hash_index][0],
140 hash_size,
141 metadata,
142 tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_metadata_size,
143 NX_NULL,
144 NX_NULL);
145 }
146
147 if (need_copy)
148 {
149 NX_SECURE_HASH_CLONE_CLEANUP(metadata, tls_session -> nx_secure_tls_handshake_hash.nx_secure_tls_handshake_hash_sha256_metadata_size);
150 }
151
152 return(status);
153 }
154
155 #endif
156
