tls13_misc.h
Go to the documentation of this file.
1 /**
2  * @file tls13_misc.h
3  * @brief TLS 1.3 helper functions
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2019 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneSSL Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 1.9.6
29  **/
30 
31 #ifndef _TLS13_MISC_H
32 #define _TLS13_MISC_H
33 
34 //DHE key establishment
35 #ifndef TLS13_DHE_KE_SUPPORT
36  #define TLS13_DHE_KE_SUPPORT ENABLED
37 #elif (TLS13_DHE_KE_SUPPORT != ENABLED && TLS13_DHE_KE_SUPPORT != DISABLED)
38  #error TLS13_DHE_KE_SUPPORT parameter is not valid
39 #endif
40 
41 //ECDHE key establishment
42 #ifndef TLS13_ECDHE_KE_SUPPORT
43  #define TLS13_ECDHE_KE_SUPPORT ENABLED
44 #elif (TLS13_ECDHE_KE_SUPPORT != ENABLED && TLS13_ECDHE_KE_SUPPORT != DISABLED)
45  #error TLS13_ECDHE_KE_SUPPORT parameter is not valid
46 #endif
47 
48 //PSK-only key establishment
49 #ifndef TLS13_PSK_KE_SUPPORT
50  #define TLS13_PSK_KE_SUPPORT DISABLED
51 #elif (TLS13_PSK_KE_SUPPORT != ENABLED && TLS13_PSK_KE_SUPPORT != DISABLED)
52  #error TLS13_PSK_KE_SUPPORT parameter is not valid
53 #endif
54 
55 //PSK with DHE key establishment
56 #ifndef TLS13_PSK_DHE_KE_SUPPORT
57  #define TLS13_PSK_DHE_KE_SUPPORT ENABLED
58 #elif (TLS13_PSK_DHE_KE_SUPPORT != ENABLED && TLS13_PSK_DHE_KE_SUPPORT != DISABLED)
59  #error TLS13_PSK_DHE_KE_SUPPORT parameter is not valid
60 #endif
61 
62 //PSK with ECDHE key establishment
63 #ifndef TLS13_PSK_ECDHE_KE_SUPPORT
64  #define TLS13_PSK_ECDHE_KE_SUPPORT ENABLED
65 #elif (TLS13_PSK_ECDHE_KE_SUPPORT != ENABLED && TLS13_PSK_ECDHE_KE_SUPPORT != DISABLED)
66  #error TLS13_PSK_ECDHE_KE_SUPPORT parameter is not valid
67 #endif
68 
69 //Early data support
70 #ifndef TLS13_EARLY_DATA_SUPPORT
71  #define TLS13_EARLY_DATA_SUPPORT DISABLED
72 #elif (TLS13_EARLY_DATA_SUPPORT != ENABLED && TLS13_EARLY_DATA_SUPPORT != DISABLED)
73  #error TLS13_EARLY_DATA_SUPPORT parameter is not valid
74 #endif
75 
76 //Middlebox compatibility mode
77 #ifndef TLS13_MIDDLEBOX_COMPAT_SUPPORT
78  #define TLS13_MIDDLEBOX_COMPAT_SUPPORT ENABLED
79 #elif (TLS13_MIDDLEBOX_COMPAT_SUPPORT != ENABLED && TLS13_MIDDLEBOX_COMPAT_SUPPORT != DISABLED)
80  #error TLS13_MIDDLEBOX_COMPAT_SUPPORT parameter is not valid
81 #endif
82 
83 //Maximum size for cookies
84 #ifndef TLS13_MAX_COOKIE_SIZE
85  #define TLS13_MAX_COOKIE_SIZE 256
86 #elif (TLS13_MAX_COOKIE_SIZE < 32)
87  #error TLS13_MAX_COOKIE_SIZE parameter is not valid
88 #endif
89 
90 //Maximum size for session tickets
91 #ifndef TLS13_MAX_TICKET_SIZE
92  #define TLS13_MAX_TICKET_SIZE 1024
93 #elif (TLS13_MAX_TICKET_SIZE < 32)
94  #error TLS13_MAX_TICKET_SIZE parameter is not valid
95 #endif
96 
97 //Maximum lifetime of session tickets
98 #ifndef TLS13_MAX_TICKET_LIFETIME
99  #define TLS13_MAX_TICKET_LIFETIME 604800
100 #elif (TLS13_MAX_TICKET_LIFETIME < 0)
101  #error TLS13_MAX_TICKET_LIFETIME parameter is not valid
102 #endif
103 
104 //Age tolerance for tickets, in milliseconds
105 #ifndef TLS13_TICKET_AGE_TOLERANCE
106  #define TLS13_TICKET_AGE_TOLERANCE 5000
107 #elif (TLS13_TICKET_AGE_TOLERANCE < 0)
108  #error TLS13_TICKET_AGE_TOLERANCE parameter is not valid
109 #endif
110 
111 //Number of NewSessionTicket message sent by the server
112 #ifndef TLS13_NEW_SESSION_TICKET_COUNT
113  #define TLS13_NEW_SESSION_TICKET_COUNT 2
114 #elif (TLS13_NEW_SESSION_TICKET_COUNT < 0)
115  #error TLS13_NEW_SESSION_TICKET_COUNT parameter is not valid
116 #endif
117 
118 //Maximum size for HKDF digests
119 #if (TLS_SHA384_SUPPORT == ENABLED)
120  #define TLS13_MAX_HKDF_DIGEST_SIZE 48
121 #else
122  #define TLS13_MAX_HKDF_DIGEST_SIZE 32
123 #endif
124 
125 //C++ guard
126 #ifdef __cplusplus
127 extern "C" {
128 #endif
129 
130 
131 /**
132  * @brief Signature schemes (TLS 1.3)
133  **/
134 
135 typedef enum
136 {
158 
159 
160 /**
161  * @brief PSK key exchange modes
162  **/
163 
164 typedef enum
165 {
169 
170 
171 /**
172  * @brief Key update requests
173  **/
174 
175 typedef enum
176 {
180 
181 
182 //CodeWarrior or Win32 compiler?
183 #if defined(__CWCC__) || defined(_WIN32)
184  #pragma pack(push, 1)
185 #endif
186 
187 
188 /**
189  * @brief Cookie
190  **/
191 
192 typedef __start_packed struct
193 {
194  uint16_t length; //0-1
195  uint8_t value[]; //2
197 
198 
199 /**
200  * @brief Key share entry
201  **/
202 
203 typedef __start_packed struct
204 {
205  uint16_t group; //0
206  uint16_t length; //1
207  uint8_t keyExchange[]; //2
209 
210 
211 /**
212  * @brief List of key shares
213  **/
214 
215 typedef __start_packed struct
216 {
217  uint16_t length; //0
218  uint8_t value[]; //1
220 
221 
222 /**
223  * @brief List of PSK key exchange modes
224  **/
225 
226 typedef __start_packed struct
227 {
228  uint8_t length; //0
229  uint8_t value[]; //1
231 
232 
233 /**
234  * @brief PSK identity
235  **/
236 
237 typedef __start_packed struct
238 {
239  uint16_t length; //0-1
240  uint8_t value[]; //2
242 
243 
244 /**
245  * @brief List of PSK identities
246  **/
247 
248 typedef __start_packed struct
249 {
250  uint16_t length; //0-1
251  uint8_t value[]; //2
253 
254 
255 /**
256  * @brief PSK binder
257  **/
258 
259 typedef __start_packed struct
260 {
261  uint8_t length; //0
262  uint8_t value[]; //1
264 
265 
266 /**
267  * @brief List of PSK binders
268  **/
269 
270 typedef __start_packed struct
271 {
272  uint16_t length; //0-1
273  uint8_t value[]; //2
275 
276 
277 /**
278  * @brief Certificate request context
279  **/
280 
281 typedef __start_packed struct
282 {
283  uint8_t length; //0
284  uint8_t value[]; //1
286 
287 
288 /**
289  * @brief Digitally-signed element (TLS 1.3)
290  **/
291 
292 typedef __start_packed struct
293 {
294  uint16_t algorithm; //0-1
295  uint16_t length; //2-3
296  uint8_t value[]; //4
298 
299 
300 /**
301  * @brief HelloRetryRequest message
302  **/
303 
304 typedef __start_packed struct
305 {
306  uint16_t serverVersion; //0-1
307  uint8_t random[32]; //2-33
308  uint8_t sessionIdLen; //34
309  uint8_t sessionId[]; //35
311 
312 
313 /**
314  * @brief EndOfEarlyData message
315  **/
316 
317 typedef void *Tls13EndOfEarlyData;
318 
319 
320 /**
321  * @brief EncryptedExtensions message
322  **/
323 
324 typedef __start_packed struct
325 {
326  uint16_t extensionsLen; //0-1
327  uint8_t extensions[]; //2
329 
330 
331 /**
332  * @brief NewSessionTicket message (TLS 1.3)
333  **/
334 
335 typedef __start_packed struct
336 {
337  uint32_t ticketLifetime; //0-3
338  uint32_t ticketAgeAdd; //4-7
339  uint8_t ticketNonceLen; //8
340  uint8_t ticketNonce[]; //9
342 
343 
344 /**
345  * @brief KeyUpdate message
346  **/
347 
348 typedef __start_packed struct
349 {
350  uint8_t requestUpdate; //0
352 
353 
354 /**
355  * @brief Session ticket
356  **/
357 
358 typedef __start_packed struct
359 {
360  uint16_t length; //0-1
361  uint8_t data[]; //2
363 
364 
365 /**
366  * @brief Session state information
367  **/
368 
369 typedef __start_packed struct
370 {
371  uint16_t version; ///<Protocol version
372  uint16_t cipherSuite; ///<Cipher suite identifier
373  systime_t ticketTimestamp; ///<Timestamp to manage ticket lifetime
374  uint32_t ticketLifetime; ///<Lifetime of the ticket
375  uint32_t ticketAgeAdd; ///<Random value used to obscure the age of the ticket
376  uint8_t ticketNonce[4]; ///<A per-ticket value that is unique across all tickets issued
377  size_t ticketPskLen; ///<Length of the PSK associated with the ticket
378  uint8_t ticketPsk[TLS13_MAX_HKDF_DIGEST_SIZE]; ///<PSK associated with the ticket
380 
381 
382 //CodeWarrior or Win32 compiler?
383 #if defined(__CWCC__) || defined(_WIN32)
384  #pragma pack(pop)
385 #endif
386 
387 
388 //TLS 1.3 related constants
389 extern const uint8_t tls11DowngradeRandom[8];
390 extern const uint8_t tls12DowngradeRandom[8];
391 extern const uint8_t tls13HelloRetryRequestRandom[32];
392 
393 //TLS 1.3 related functions
394 error_t tls13ComputePskBinder(TlsContext *context, const void *clientHello,
395  size_t clientHelloLen, size_t truncatedClientHelloLen,
396  const Tls13PskIdentity *identity, uint8_t *binder, size_t binderLen);
397 
398 error_t tls13GenerateKeyShare(TlsContext *context, uint16_t namedGroup);
399 
400 error_t tls13GenerateSharedSecret(TlsContext *context, const uint8_t *keyShare,
401  size_t length);
402 
403 error_t tls13GenerateSignature(TlsContext *context, uint8_t *p,
404  size_t *length);
405 
406 error_t tls13VerifySignature(TlsContext *context, const uint8_t *p,
407  size_t length);
408 
410 
413 
414 bool_t tls13IsGroupSupported(TlsContext *context, uint16_t namedGroup);
415 bool_t tls13IsEcdheGroupSupported(TlsContext *context, uint16_t namedGroup);
416 bool_t tls13IsFfdheGroupSupported(TlsContext *context, uint16_t namedGroup);
417 
418 error_t tls13CheckDuplicateKeyShare(uint16_t namedGroup, const uint8_t *p,
419  size_t length);
420 
421 error_t tls13FormatCertExtensions(uint8_t *p, size_t *written);
422 
423 error_t tls13ParseCertExtensions(const uint8_t *p, size_t length,
424  size_t *consumed);
425 
426 //C++ guard
427 #ifdef __cplusplus
428 }
429 #endif
430 
431 #endif
uint16_t algorithm
Definition: tls13_misc.h:294
uint16_t extensionsLen
Definition: tls13_misc.h:326
uint8_t sessionId[]
Definition: tls13_misc.h:309
uint32_t ticketLifetime
Lifetime of the ticket.
Definition: tls13_misc.h:337
__start_packed struct @94 Tls13PskIdentity
PSK identity.
__start_packed struct @95 Tls13PskIdentityList
List of PSK identities.
#define TLS13_MAX_HKDF_DIGEST_SIZE
Definition: tls13_misc.h:120
uint8_t keyExchange[]
Definition: tls13_misc.h:207
int bool_t
Definition: compiler_port.h:49
@ TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP256R1_TLS13_SHA256
Definition: tls13_misc.h:152
@ TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA256
Definition: tls13_misc.h:142
@ TLS_SIGN_SCHEME_RSA_PKCS1_SHA512
Definition: tls13_misc.h:141
error_t tls13GenerateKeyShare(TlsContext *context, uint16_t namedGroup)
__start_packed struct @97 Tls13PskBinderList
List of PSK binders.
uint8_t p
Definition: ndp.h:298
uint16_t length
Definition: tls13_misc.h:194
__start_packed struct @100 Tls13HelloRetryRequest
HelloRetryRequest message.
error_t tls13DigestClientHello1(TlsContext *context)
@ TLS_SIGN_SCHEME_ED25519
Definition: tls13_misc.h:155
__start_packed struct @91 Tls13KeyShareEntry
Key share entry.
__start_packed struct @103 Tls13KeyUpdate
KeyUpdate message.
uint16_t serverVersion
Definition: tls13_misc.h:306
uint8_t data[]
Definition: tls13_misc.h:361
error_t tls13ParseCertExtensions(const uint8_t *p, size_t length, size_t *consumed)
size_t ticketPskLen
Length of the PSK associated with the ticket.
Definition: tls13_misc.h:377
@ TLS_SIGN_SCHEME_RSA_PKCS1_SHA384
Definition: tls13_misc.h:140
__start_packed struct @93 Tls13PskKeModeList
List of PSK key exchange modes.
__start_packed struct @90 Tls13Cookie
Cookie.
@ TLS_SIGN_SCHEME_ECDSA_SECP256R1_SHA256
Definition: tls13_misc.h:149
@ TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA384
Definition: tls13_misc.h:146
@ TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP384R1_TLS13_SHA384
Definition: tls13_misc.h:153
uint8_t ticketNonceLen
Definition: tls13_misc.h:339
uint8_t requestUpdate
Definition: tls13_misc.h:350
Tls13KeyUpdateRequest
Key update requests.
Definition: tls13_misc.h:175
uint8_t ticketPsk[TLS13_MAX_HKDF_DIGEST_SIZE]
PSK associated with the ticket.
Definition: tls13_misc.h:378
@ TLS_PSK_KEY_EXCH_MODE_PSK_KE
Definition: tls13_misc.h:166
@ TLS_SIGN_SCHEME_RSA_PKCS1_SHA256
Definition: tls13_misc.h:139
@ TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE
Definition: tls13_misc.h:167
bool_t tls13IsGroupSupported(TlsContext *context, uint16_t namedGroup)
Tls13PskKeyExchMode
PSK key exchange modes.
Definition: tls13_misc.h:164
Tls13SignatureScheme
Signature schemes (TLS 1.3)
Definition: tls13_misc.h:135
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
@ TLS_SIGN_SCHEME_ECDSA_SECP384R1_SHA384
Definition: tls13_misc.h:150
@ TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA512
Definition: tls13_misc.h:147
__start_packed struct @101 Tls13EncryptedExtensions
EncryptedExtensions message.
systime_t ticketTimestamp
Timestamp to manage ticket lifetime.
Definition: tls13_misc.h:373
@ TLS_SIGN_SCHEME_ED448
Definition: tls13_misc.h:156
@ TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA256
Definition: tls13_misc.h:145
__start_packed struct _Ipv4Header __end_packed
@ TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA512
Definition: tls13_misc.h:144
@ TLS_SIGN_SCHEME_RSA_PKCS1_SHA1
Definition: tls13_misc.h:138
error_t tls13VerifySignature(TlsContext *context, const uint8_t *p, size_t length)
@ TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP512R1_TLS13_SHA512
Definition: tls13_misc.h:154
@ TLS_SIGN_SCHEME_ECDSA_SECP521R1_SHA512
Definition: tls13_misc.h:151
error_t tls13GenerateSharedSecret(TlsContext *context, const uint8_t *keyShare, size_t length)
uint16_t version
Protocol version.
Definition: tls13_misc.h:371
uint16_t group
Definition: tls13_misc.h:205
__start_packed struct @98 Tls13CertRequestContext
Certificate request context.
error_t tls13ComputePskBinder(TlsContext *context, const void *clientHello, size_t clientHelloLen, size_t truncatedClientHelloLen, const Tls13PskIdentity *identity, uint8_t *binder, size_t binderLen)
bool_t tls13IsEcdheGroupSupported(TlsContext *context, uint16_t namedGroup)
@ TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA384
Definition: tls13_misc.h:143
uint8_t sessionIdLen
Definition: tls13_misc.h:308
error_t tls13GenerateSignature(TlsContext *context, uint8_t *p, size_t *length)
uint8_t extensions[]
Definition: tls13_misc.h:327
uint16_t cipherSuite
Cipher suite identifier.
Definition: tls13_misc.h:372
uint8_t value[]
Definition: tls13_misc.h:195
uint8_t random[32]
Definition: tls13_misc.h:307
@ TLS_SIGN_SCHEME_ECDSA_SHA1
Definition: tls13_misc.h:148
bool_t tls13IsPskValid(TlsContext *context)
bool_t tls13IsFfdheGroupSupported(TlsContext *context, uint16_t namedGroup)
__start_packed struct @99 Tls13DigitalSignature
Digitally-signed element (TLS 1.3)
bool_t tls13IsTicketValid(TlsContext *context)
@ TLS_KEY_UPDATE_REQUESTED
Definition: tls13_misc.h:178
const uint8_t tls11DowngradeRandom[8]
const uint8_t tls12DowngradeRandom[8]
__start_packed struct @102 Tls13NewSessionTicket
NewSessionTicket message (TLS 1.3)
void * Tls13EndOfEarlyData
EndOfEarlyData message.
Definition: tls13_misc.h:317
uint8_t ticketNonce[]
A per-ticket value that is unique across all tickets issued.
Definition: tls13_misc.h:340
@ TLS_SIGN_SCHEME_NONE
Definition: tls13_misc.h:137
__start_packed struct @92 Tls13KeyShareList
List of key shares.
@ TLS_KEY_UPDATE_NOT_REQUESTED
Definition: tls13_misc.h:177
__start_packed struct @104 Tls13Ticket
Session ticket.
uint32_t ticketAgeAdd
Random value used to obscure the age of the ticket.
Definition: tls13_misc.h:338
__start_packed struct @96 Tls13PskBinder
PSK binder.
uint32_t systime_t
Definition: compiler_port.h:46
__start_packed struct @105 Tls13SessionState
Session state information.
error_t tls13CheckDuplicateKeyShare(uint16_t namedGroup, const uint8_t *p, size_t length)
error_t tls13FormatCertExtensions(uint8_t *p, size_t *written)
const uint8_t tls13HelloRetryRequestRandom[32]