tls13_client_extensions.c
Go to the documentation of this file.
1 /**
2  * @file tls13_client_extensions.c
3  * @brief Formatting and parsing of extensions (TLS 1.3 client)
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2026 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 2.6.6
29  **/
30 
31 //Switch to the appropriate trace level
32 #define TRACE_LEVEL TLS_TRACE_LEVEL
33 
34 //Dependencies
35 #include "tls/tls.h"
36 #include "tls/tls_misc.h"
38 #include "tls13/tls13_ticket.h"
39 #include "debug.h"
40 
41 //Check TLS library configuration
42 #if (TLS_SUPPORT == ENABLED && TLS_CLIENT_SUPPORT == ENABLED && \
43  TLS_MAX_VERSION >= TLS_VERSION_1_3)
44 
45 
46 /**
47  * @brief Format Cookie extension
48  * @param[in] context Pointer to the TLS context
49  * @param[in] p Output stream where to write the Cookie extension
50  * @param[out] written Total number of bytes that have been written
51  * @return Error code
52  **/
53 
55  size_t *written)
56 {
57  size_t n;
58  TlsExtension *extension;
60 
61  //Initialize length field
62  n = 0;
63 
64  //When sending a HelloRetryRequest, the server may provide a Cookie
65  //extension to the client
66  if(context->cookieLen > 0)
67  {
68  //Add the Cookie extension
69  extension = (TlsExtension *) p;
70  //Type of the extension
71  extension->type = HTONS(TLS_EXT_COOKIE);
72 
73  //Point to the extension data field
74  cookie = (Tls13Cookie *) extension->value;
75 
76  //When sending the new ClientHello, the client must copy the contents
77  //of the Cookie extension received in the HelloRetryRequest
78  osMemcpy(cookie->value, context->cookie, context->cookieLen);
79 
80  //Set the length of the cookie
81  cookie->length = ntohs(context->cookieLen);
82 
83  //Consider the 2-byte length field that precedes the cookie
84  n = sizeof(Tls13Cookie) + context->cookieLen;
85  //Fix the length of the extension
86  extension->length = htons(n);
87 
88  //Compute the length, in bytes, of the Cookie extension
89  n += sizeof(TlsExtension);
90  }
91 
92  //Total number of bytes that have been written
93  *written = n;
94 
95  //Successful processing
96  return NO_ERROR;
97 }
98 
99 
100 /**
101  * @brief Format KeyShare extension (ClientHello message)
102  * @param[in] context Pointer to the TLS context
103  * @param[in] p Output stream where to write the KeyShare extension
104  * @param[out] written Total number of bytes that have been written
105  * @return Error code
106  **/
107 
109  uint8_t *p, size_t *written)
110 {
111  size_t n = 0;
112 
113 #if (TLS13_DHE_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
114  TLS13_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || \
115  TLS13_MLKEM_KE_SUPPORT == ENABLED || TLS13_PSK_MLKEM_KE_SUPPORT == ENABLED || \
116  TLS13_HYBRID_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
117  error_t error;
118  TlsExtension *extension;
119  Tls13KeyShareList *keyShareList;
120  Tls13KeyShareEntry *keyShareEntry;
121 
122  //Add the KeyShare extension
123  extension = (TlsExtension *) p;
124  //Type of the extension
125  extension->type = HTONS(TLS_EXT_KEY_SHARE);
126 
127  //The extension contains a list of offered KeyShareEntry values in
128  //descending order of client preference
129  keyShareList = (Tls13KeyShareList *) extension->value;
130 
131  //Point to the KeyShareEntry
132  keyShareEntry = (Tls13KeyShareEntry *) keyShareList->value;
133 
134 #if (TLS13_DHE_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED)
135  //Finite field group?
136  if(tls13IsFfdheGroupSupported(context, context->namedGroup))
137  {
138  //Specify the named group for the key being exchanged
139  keyShareEntry->group = htons(context->namedGroup);
140 
141  //Diffie-Hellman parameters are encoded in the opaque key_exchange field
142  //of the KeyShareEntry. The opaque value contains the Diffie-Hellman
143  //public value for the specified group encoded as a big-endian integer
144  //and padded to the left with zeros to the size of p in bytes
145  error = dhExportPublicKey(&context->dhContext,
146  keyShareEntry->keyExchange, &n, MPI_FORMAT_BIG_ENDIAN);
147  //Any error to report?
148  if(error)
149  return error;
150 
151  //Set the length of the key_exchange field
152  keyShareEntry->length = htons(n);
153 
154  //Compute the length of the KeyShareEntry
155  n += sizeof(Tls13KeyShareEntry);
156  }
157  else
158 #endif
159 #if (TLS13_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED)
160  //Elliptic curve group?
161  if(tls13IsEcdheGroupSupported(context, context->namedGroup))
162  {
163  //Specify the named group for the key being exchanged
164  keyShareEntry->group = htons(context->namedGroup);
165 
166  //ECDHE parameters are encoded in the opaque key_exchange field of
167  //the KeyShareEntry
168  error = ecdhExportPublicKey(&context->ecdhContext,
169  keyShareEntry->keyExchange, &n, EC_PUBLIC_KEY_FORMAT_X963);
170  //Any error to report?
171  if(error)
172  return error;
173 
174  //Set the length of the key_exchange field
175  keyShareEntry->length = htons(n);
176 
177  //Compute the length of the KeyShareEntry
178  n += sizeof(Tls13KeyShareEntry);
179  }
180  else
181 #endif
182 #if (TLS13_MLKEM_KE_SUPPORT == ENABLED || TLS13_PSK_MLKEM_KE_SUPPORT == ENABLED)
183  //ML-KEM key exchange method?
184  if(tls13IsMlkemGroupSupported(context, context->namedGroup))
185  {
186  const KemAlgo *kemAlgo;
187 
188  //Point to the KEM algorithm
189  kemAlgo = context->kemContext.kemAlgo;
190 
191  //Specify the named group for the key being exchanged
192  keyShareEntry->group = htons(context->namedGroup);
193 
194  //For the client's share, the key_exchange value contains the pk output
195  //of the corresponding KEM's KeyGen algorithm
196  osMemcpy(keyShareEntry->keyExchange, context->kemContext.pk,
197  kemAlgo->publicKeySize);
198 
199  //The length of the public key is fixed
200  n = kemAlgo->publicKeySize;
201 
202  //Set the length of the key_exchange field
203  keyShareEntry->length = htons(n);
204 
205  //Compute the length of the KeyShareEntry
206  n += sizeof(Tls13KeyShareEntry);
207  }
208  else
209 #endif
210 #if (TLS13_HYBRID_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
211  //Hybrid key exchange method?
212  if(tls13IsHybridGroupSupported(context, context->namedGroup))
213  {
214  size_t offset;
215  const KemAlgo *kemAlgo;
216 
217  //Point to the KEM algorithm
218  kemAlgo = context->kemContext.kemAlgo;
219 
220  //Specify the named group for the key being exchanged
221  keyShareEntry->group = htons(context->namedGroup);
222 
223  //The group name X25519MLKEM768 does not adhere to the naming convention
224  //outlined in Section 3.2 of RFC 9954. Specifically, the order of shares
225  //in the concatenation has been reversed. This is due to historical
226  //reasons (refer to RFC 10024, section 4.1)
227  if(context->namedGroup == TLS_GROUP_X25519_MLKEM768)
228  {
229  offset = kemAlgo->publicKeySize;
230  }
231  else
232  {
233  offset = 0;
234  }
235 
236  //The ECDHE share is the serialized value of the uncompressed ECDH point
237  //representation
238  error = ecdhExportPublicKey(&context->ecdhContext,
239  keyShareEntry->keyExchange + offset, &n, EC_PUBLIC_KEY_FORMAT_X963);
240  //Any error to report?
241  if(error)
242  return error;
243 
244  //X25519MLKEM768 group?
245  if(context->namedGroup == TLS_GROUP_X25519_MLKEM768)
246  {
247  offset = 0;
248  }
249  else
250  {
251  offset = n;
252  }
253 
254  //The ML-KEM's ephemeral share is the public key of the KeyGen step
255  //represented as an octet string
256  osMemcpy(keyShareEntry->keyExchange + offset, context->kemContext.pk,
257  kemAlgo->publicKeySize);
258 
259  //The client's share is a fixed-size concatenation of the ECDHE share
260  //and ML-KEM's public key
261  n += kemAlgo->publicKeySize;
262 
263  //Set the length of the key_exchange field
264  keyShareEntry->length = htons(n);
265 
266  //Compute the length of the KeyShareEntry
267  n += sizeof(Tls13KeyShareEntry);
268  }
269  else
270 #endif
271  //Unknown group?
272  {
273  //Clients may send an empty client_shares vector in order to request group
274  //selection from the server, at the cost of an additional round trip
275  }
276 
277  //Fix the length of the list of offered key shares
278  keyShareList->length = htons(n);
279 
280  //Consider the 2-byte length field that precedes the list
281  n += sizeof(Tls13KeyShareList);
282  //Fix the length of the extension
283  extension->length = htons(n);
284 
285  //Compute the length, in bytes, of the KeyShare extension
286  n += sizeof(TlsExtension);
287 #endif
288 
289  //Total number of bytes that have been written
290  *written = n;
291 
292  //Successful processing
293  return NO_ERROR;
294 }
295 
296 
297 /**
298  * @brief Format PskKeyExchangeModes extension
299  * @param[in] context Pointer to the TLS context
300  * @param[in] p Output stream where to write the PskKeyExchangeModes extension
301  * @param[out] written Total number of bytes that have been written
302  * @return Error code
303  **/
304 
306  uint8_t *p, size_t *written)
307 {
308  size_t n = 0;
309 
310 #if (TLS13_PSK_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
311  TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
312  TlsExtension *extension;
313  Tls13PskKeModeList *pskKeModeList;
314 
315  //Add the PskKeyExchangeModes extension
316  extension = (TlsExtension *) p;
317  //Type of the extension
318  extension->type = HTONS(TLS_EXT_PSK_KEY_EXCHANGE_MODES);
319 
320  //Point to the extension data field
321  pskKeModeList = (Tls13PskKeModeList *) extension->value;
322  //The extension contains a list of supported PSK key exchange modes
323  n = 0;
324 
327  //PSK with (EC)DHE key establishment
328  pskKeModeList->value[n++] = TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE;
329 #endif
330 #if (TLS13_PSK_KE_SUPPORT == ENABLED)
331  //PSK-only key establishment
332  pskKeModeList->value[n++] = TLS_PSK_KEY_EXCH_MODE_PSK_KE;
333 #endif
334 
335  //Fix the length of the list
336  pskKeModeList->length = (uint8_t) n;
337 
338  //Consider the length field that precedes the list
339  n += sizeof(Tls13PskKeModeList);
340  //Fix the length of the extension
341  extension->length = htons(n);
342 
343  //Compute the length, in bytes, of the PskKeyExchangeModes extension
344  n += sizeof(TlsExtension);
345 #endif
346 
347  //Total number of bytes that have been written
348  *written = n;
349 
350  //Successful processing
351  return NO_ERROR;
352 }
353 
354 
355 /**
356  * @brief Format PreSharedKey extension
357  * @param[in] context Pointer to the TLS context
358  * @param[in] p Output stream where to write the PreSharedKey extension
359  * @param[out] written Total number of bytes that have been written
360  * @param[out] identityList Pointer to the list of the identities that the
361  * client is willing to negotiate with the server
362  * @param[out] binderList Pointer to the list of HMAC values, one for each PSK
363  * offered in the PreSharedKey extension
364  * @return Error code
365  **/
366 
368  uint8_t *p, size_t *written, Tls13PskIdentityList **identityList,
369  Tls13PskBinderList **binderList)
370 {
371  size_t n = 0;
372 
373 #if (TLS13_PSK_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
374  TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
375  //Check whether the client is attempting a PSK key establishment
376  if(tls13IsPskValid(context) || tls13IsTicketValid(context))
377  {
378  error_t error;
379  size_t m;
380  uint16_t cipherSuite;
381  uint32_t ticketAge;
382  TlsExtension *extension;
383  TlsPskIdentity *pskIdentity;
384  Tls13PskBinder *pskBinder;
385  const HashAlgo *hashAlgo;
386 
387  //Add the PreSharedKey extension
388  extension = (TlsExtension *) p;
389  //Type of the extension
390  extension->type = HTONS(TLS_EXT_PRE_SHARED_KEY);
391 
392  //Point to the extension data field
393  *identityList = (Tls13PskIdentityList *) extension->value;
394  //Point to the first PskIdentity entry of the list
395  pskIdentity = (TlsPskIdentity *) (*identityList)->value;
396 
397  //Although PSKs can be established out of band, PSKs can also be
398  //established in a previous connection
399  if(tls13IsPskValid(context))
400  {
401  //Retrieve the length of the PSK identity
402  n = osStrlen(context->pskIdentity);
403  //Copy PSK identity
404  osMemcpy(pskIdentity->value, context->pskIdentity, n);
405 
406  //For externally established PSKs, the hash algorithm must be set when
407  //the PSK is established or default to SHA-256 if no such algorithm is
408  //defined
409  hashAlgo = tlsGetHashAlgo(context->pskHashAlgo);
410 
411  //Retrieve the cipher suite associated with the PSK, if any
412  cipherSuite = context->pskCipherSuite;
413 
414  //For PSK identities established externally, an obfuscated_ticket_age
415  //of 0 should be used (refer to RFC 8446, section 4.2.11)
416  ticketAge = 0;
417  }
418  else if(tls13IsTicketValid(context))
419  {
420  //Retrieve the length of the session ticket
421  n = context->ticketLen;
422  //Copy session ticket
423  osMemcpy(pskIdentity->value, context->ticket, n);
424 
425  //Each PSK is associated with a single hash algorithm. For PSKs
426  //established via the ticket mechanism, this is the KDF hash algorithm
427  //on the connection where the ticket was established
428  hashAlgo = tlsGetHashAlgo(context->ticketHashAlgo);
429 
430  //Retrieve the cipher suite associated with the ticket
431  cipherSuite = context->ticketCipherSuite;
432 
433  //The client's view of the age of a ticket is the time since the
434  //receipt of the NewSessionTicket message
435  ticketAge = context->clientHelloTimestamp - context->ticketTimestamp;
436 
437  //The obfuscated_ticket_age field contains an obfuscated version of
438  //the ticket age formed by taking the age in milliseconds and adding
439  //the ticket_age_add value that was included with the ticket
440  ticketAge += context->ticketAgeAdd;
441  }
442  else
443  {
444  //Just for sanity
445  return ERROR_FAILURE;
446  }
447 
448  //Valid cipher suite provisioned?
449  if(cipherSuite != 0)
450  {
451  //Restore the cipher suite associated with the PSK
452  error = tlsSelectCipherSuite(context, cipherSuite);
453  //Any error to report?
454  if(error)
455  return error;
456  }
457  else
458  {
459  //Make sure the hash algorithm is valid
460  if(hashAlgo == NULL)
461  return ERROR_FAILURE;
462 
463  //Restore the hash algorithm associated with the PSK
464  context->cipherSuite.prfHashAlgo = hashAlgo;
465  }
466 
467  //Fix the length of the PSK identity
468  pskIdentity->length = htons(n);
469  //Consider the length field that precedes the PSK identity
470  n += sizeof(TlsPskIdentity);
471 
472  //The obfuscated_ticket_age field is a 32-bit unsigned integer
473  STORE32BE(ticketAge, (uint8_t *) pskIdentity + n);
474  //Compute the length of the PskIdentity entry
475  n += sizeof(uint32_t);
476 
477  //Fix the length of the list of PSK identities
478  (*identityList)->length = htons(n);
479  //Consider the 2-byte length field that precedes the list
480  n += sizeof(Tls13PskIdentityList);
481 
482  //Point to the list of PSK binders
483  *binderList = (Tls13PskBinderList *) ((uint8_t *) *identityList + n);
484  //Point to the first PskBinderEntry of the list
485  pskBinder = (Tls13PskBinder *) (*binderList)->value;
486 
487  //The PSK binder consists of Hash.length bytes
488  m = hashAlgo->digestSize;
489  //The value of the PSK binder will be calculated in a second step
490  osMemset(pskBinder->value, 0, m);
491 
492  //Fix the length of the PSK binder
493  pskBinder->length = (uint8_t) m;
494  //Consider the length field that precedes the PSK binder
495  m += sizeof(Tls13PskBinder);
496 
497  //Fix the length of the list of PSK binders
498  (*binderList)->length = htons(m);
499  //Consider the 2-byte length field that precedes the list
500  n += sizeof(Tls13PskBinderList) + m;
501 
502  //Fix the length of the extension
503  extension->length = htons(n);
504  //Compute the length, in bytes, of the PreSharedKey extension
505  n += sizeof(TlsExtension);
506  }
507  else
508 #endif
509  {
510  //PSK key establishment is not used
511  *identityList = NULL;
512  *binderList = NULL;
513  }
514 
515  //Total number of bytes that have been written
516  *written = n;
517 
518  //Successful processing
519  return NO_ERROR;
520 }
521 
522 
523 /**
524  * @brief Format EarlyData extension
525  * @param[in] context Pointer to the TLS context
526  * @param[in] p Output stream where to write the EarlyData extension
527  * @param[out] written Total number of bytes that have been written
528  * @return Error code
529  **/
530 
532  uint8_t *p, size_t *written)
533 {
534  size_t n = 0;
535 
536 #if (TLS13_EARLY_DATA_SUPPORT == ENABLED)
537  //If the client opts to send application data in its first flight of
538  //messages, it must supply both the PreSharedKey and EarlyData extensions
539  if(context->earlyDataEnabled && !context->earlyDataRejected)
540  {
541  TlsExtension *extension;
542 
543  //Add the EarlyData extension
544  extension = (TlsExtension *) p;
545  //Type of the extension
546  extension->type = HTONS(TLS_EXT_EARLY_DATA);
547 
548  //The extension data field of this extension is empty
549  extension->length = HTONS(0);
550 
551  //Compute the length, in bytes, of the EarlyData extension
552  n = sizeof(TlsExtension);
553  }
554 #endif
555 
556  //Total number of bytes that have been written
557  *written = n;
558 
559  //Successful processing
560  return NO_ERROR;
561 }
562 
563 
564 /**
565  * @brief Parse SupportedVersions extension
566  * @param[in] context Pointer to the TLS context
567  * @param[in] selectedVersion Pointer to the SupportedVersions extension
568  * @return Error code
569  **/
570 
572  const TlsExtension *selectedVersion)
573 {
574  error_t error;
575  uint16_t version;
576 
577  //The extension contains the selected version value
578  version = LOAD16BE(selectedVersion->value);
579 
580  //Debug message
581  TRACE_INFO(" selectedVersion = 0x%04" PRIX16 " (%s)\r\n",
583 
584 #if (DTLS_SUPPORT == ENABLED)
585  //DTLS protocol?
586  if(context->transportProtocol == TLS_TRANSPORT_PROTOCOL_DATAGRAM)
587  {
588  //Version of DTLS prior to DTLS 1.3?
590  {
591  //The client must abort the handshake with an illegal_parameter alert
592  error = ERROR_ILLEGAL_PARAMETER;
593  }
594  else
595  {
596  //Set the DTLS version to be used
597  error = dtlsSelectVersion(context, version);
598  }
599  }
600  else
601 #endif
602  //TLS protocol?
603  {
604  //Version of TLS prior to TLS 1.3?
606  {
607  //The client must abort the handshake with an illegal_parameter alert
608  error = ERROR_ILLEGAL_PARAMETER;
609  }
610  else
611  {
612  //Set the TLS version to be used
613  error = tlsSelectVersion(context, version);
614  }
615  }
616 
617  //Return status code
618  return error;
619 }
620 
621 
622 /**
623  * @brief Parse Cookie extension
624  * @param[in] context Pointer to the TLS context
625  * @param[in] cookie Pointer to the Cookie extension
626  * @return Error code
627  **/
628 
630  const Tls13Cookie *cookie)
631 {
632  //Cookie extension found?
633  if(cookie != NULL)
634  {
635  size_t n;
636 
637  //Retrieve the length of the cookie
638  n = ntohs(cookie->length);
639 
640  //Clients must abort the handshake with an illegal_parameter alert if the
641  //HelloRetryRequest would not result in any change in the ClientHello
642  if(n == 0)
644 
645  //Check the length of the cookie
648 
649  //Release cookie
650  if(context->cookie != NULL)
651  {
652  tlsFreeMem(context->cookie);
653  context->cookie = NULL;
654  context->cookieLen = 0;
655  }
656 
657  //Allocate a memory block to store the cookie
658  context->cookie = tlsAllocMem(n);
659  //Failed to allocate memory?
660  if(context->cookie == NULL)
661  return ERROR_OUT_OF_MEMORY;
662 
663  //Save cookie
664  osMemcpy(context->cookie, cookie->value, n);
665  context->cookieLen = n;
666  }
667 
668  //Successful processing
669  return NO_ERROR;
670 }
671 
672 
673 /**
674  * @brief Parse KeyShare extension (HelloRetryRequest message)
675  * @param[in] context Pointer to the TLS context
676  * @param[in] selectedGroup Pointer to the KeyShare extension
677  * @return Error code
678  **/
679 
681  const TlsExtension *selectedGroup)
682 {
683  error_t error;
684 
685  //Initialize status code
686  error = NO_ERROR;
687 
688 #if (TLS13_DHE_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
689  TLS13_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || \
690  TLS13_MLKEM_KE_SUPPORT == ENABLED || TLS13_PSK_MLKEM_KE_SUPPORT == ENABLED || \
691  TLS13_HYBRID_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
692  //KeyShare extension found?
693  if(selectedGroup != NULL)
694  {
695  uint16_t namedGroup;
696 
697  //The KeyShare extension contains the mutually supported group the server
698  //intends to negotiate
699  namedGroup = LOAD16BE(selectedGroup->value);
700 
701  //Check whether the server has selected a different ECDHE or FFDHE group
702  if(namedGroup != context->namedGroup)
703  {
704  //Generate an ephemeral key pair
705  error = tls13GenerateKeyShare(context, namedGroup);
706  }
707  }
708 #else
709  //KeyShare extension found?
710  if(selectedGroup != NULL)
711  {
712  //If a client receives an extension type that it did not request in the
713  //ClientHello, it must abort the handshake with an unsupported_extension
714  //fatal alert
716  }
717 #endif
718 
719  //Return status code
720  return error;
721 }
722 
723 
724 /**
725  * @brief Parse KeyShare extension (ServerHello message)
726  * @param[in] context Pointer to the TLS context
727  * @param[in] serverShare Pointer to the KeyShare extension
728  * @return Error code
729  **/
730 
732  const Tls13KeyShareEntry *serverShare)
733 {
734  error_t error;
735 
736  //Initialize status code
737  error = NO_ERROR;
738 
739 #if (TLS13_DHE_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
740  TLS13_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || \
741  TLS13_MLKEM_KE_SUPPORT == ENABLED || TLS13_PSK_MLKEM_KE_SUPPORT == ENABLED || \
742  TLS13_HYBRID_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
743  //If using (EC)DHE key establishment, servers offer exactly one KeyShareEntry
744  //in the ServerHello
745  if(serverShare != NULL)
746  {
747  uint16_t namedGroup;
748 
749  //Convert the selected NamedGroup to host byte order
750  namedGroup = ntohs(serverShare->group);
751 
752  //The client must verify that the selected NamedGroup in the ServerHello
753  //is the same as that in the HelloRetryRequest
754  if(namedGroup == context->namedGroup)
755  {
756  //Finite field group?
757  if(tls13IsFfdheGroupSupported(context, namedGroup))
758  {
759  //DHE key exchange mechanism provides forward secrecy
760  context->keyExchMethod = TLS13_KEY_EXCH_DHE;
761 
762  //Compute DHE shared secret
763  error = tls13GenerateSharedSecret(context, serverShare->keyExchange,
764  ntohs(serverShare->length));
765  }
766  //Elliptic curve group?
767  else if(tls13IsEcdheGroupSupported(context, namedGroup))
768  {
769  //ECDHE key exchange mechanism provides forward secrecy
770  context->keyExchMethod = TLS13_KEY_EXCH_ECDHE;
771 
772  //Compute ECDHE shared secret
773  error = tls13GenerateSharedSecret(context, serverShare->keyExchange,
774  ntohs(serverShare->length));
775  }
776  //ML-KEM key exchange method?
777  else if(tls13IsMlkemGroupSupported(context, namedGroup))
778  {
779  //ML-KEM-512, ML-KEM-768, and ML-KEM-1024 can be used as a
780  //standalone algorithm to achieve post-quantum key agreement
781  context->keyExchMethod = TLS13_KEY_EXCH_MLKEM;
782 
783  //Decapsulation algorithm
784  error = tls13Decapsulate(context, serverShare->keyExchange,
785  ntohs(serverShare->length));
786  }
787  //Hybrid key exchange method?
788  else if(tls13IsHybridGroupSupported(context, namedGroup))
789  {
790  //Hybrid key exchange makes use of two key exchange algorithms
791  //based on different cryptographic assumptions
792  context->keyExchMethod = TLS13_KEY_EXCH_HYBRID;
793 
794  //Decapsulation algorithm
795  error = tls13Decapsulate(context, serverShare->keyExchange,
796  ntohs(serverShare->length));
797  }
798  //Unknown group?
799  else
800  {
801  //Servers must not send a KeyShareEntry for any group not indicated
802  //in the client's SupportedGroups extension
803  error = ERROR_ILLEGAL_PARAMETER;
804  }
805  }
806  else
807  {
808  //If this check fails, the client must abort the handshake with an
809  //illegal_parameter alert
810  error = ERROR_ILLEGAL_PARAMETER;
811  }
812  }
813  else
814  {
815  //PSKs can be used alone, at the cost of losing forward secrecy for the
816  //application data
817  context->keyExchMethod = TLS_KEY_EXCH_NONE;
818  }
819 #else
820  //KeyShareEntry extension found?
821  if(serverShare != NULL)
822  {
823  //If a client receives an extension type that it did not request in the
824  //ClientHello, it must abort the handshake with an unsupported_extension
825  //fatal alert
827  }
828  else
829  {
830  //Perform a PSK handshake if possible
831  context->keyExchMethod = TLS_KEY_EXCH_NONE;
832  }
833 #endif
834 
835  //Return status code
836  return error;
837 }
838 
839 
840 /**
841  * @brief Parse PreSharedKey extension
842  * @param[in] context Pointer to the TLS context
843  * @param[in] selectedIdentity Pointer to the PreSharedKey extension
844  * @return Error code
845  **/
846 
848  const TlsExtension *selectedIdentity)
849 {
850  //Reset the server's selected_identity to its default value
851  context->selectedIdentity = -1;
852 
853 #if (TLS13_PSK_KE_SUPPORT == ENABLED || TLS13_PSK_DHE_KE_SUPPORT == ENABLED || \
854  TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED || TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
855  //PreSharedKey extension found?
856  if(selectedIdentity != NULL)
857  {
858  const HashAlgo *hashAlgo;
859 
860  //If a client receives an extension type that it did not request in the
861  //ClientHello, it must abort the handshake with an unsupported_extension
862  //fatal alert
863  if(!tls13IsPskValid(context) && !tls13IsTicketValid(context))
865 
866  //In order to accept PSK key establishment, the server sends a
867  //PreSharedKey extension indicating the selected identity
868  context->selectedIdentity = LOAD16BE(selectedIdentity->value);
869 
870  //Clients must verify that the server's selected_identity is within the
871  //range supplied by the client (refer to RFC 8446, section 4.2.11)
872  if(context->selectedIdentity != 0)
874 
875  //Point to the cipher suite hash algorithm
876  hashAlgo = context->cipherSuite.prfHashAlgo;
877  //Make sure the hash algorithm is valid
878  if(hashAlgo == NULL)
879  return ERROR_FAILURE;
880 
881  //Clients must also verify that the server has selected a cipher suite
882  //indicating a hash algorithm associated with the PSK
883  if(tls13IsPskValid(context))
884  {
885  //PSK incompatible with the selected cipher suite?
886  if(tlsGetHashAlgo(context->pskHashAlgo) != hashAlgo)
888  }
889  else if(tls13IsTicketValid(context))
890  {
891  //PSK incompatible with the selected cipher suite?
892  if(tlsGetHashAlgo(context->ticketHashAlgo) != hashAlgo)
894  }
895  else
896  {
897  //Just for sanity
898  }
899 
900  //PSKs can be used with (EC)DHE key exchange in order to provide forward
901  //secrecy in combination with shared keys, or can be used alone, at the
902  //cost of losing forward secrecy for the application data
903 #if (TLS13_PSK_KE_SUPPORT == ENABLED)
904  if(context->keyExchMethod == TLS_KEY_EXCH_NONE)
905  {
906  context->keyExchMethod = TLS13_KEY_EXCH_PSK;
907  }
908 #endif
909 #if (TLS13_PSK_DHE_KE_SUPPORT == ENABLED)
910  if(context->keyExchMethod == TLS13_KEY_EXCH_DHE)
911  {
912  context->keyExchMethod = TLS13_KEY_EXCH_PSK_DHE;
913  }
914 #endif
915 #if (TLS13_PSK_ECDHE_KE_SUPPORT == ENABLED)
916  if(context->keyExchMethod == TLS13_KEY_EXCH_ECDHE)
917  {
918  context->keyExchMethod = TLS13_KEY_EXCH_PSK_ECDHE;
919  }
920 #endif
921 #if (TLS13_PSK_MLKEM_KE_SUPPORT == ENABLED)
922  if(context->keyExchMethod == TLS13_KEY_EXCH_MLKEM)
923  {
924  context->keyExchMethod = TLS13_KEY_EXCH_PSK_MLKEM;
925  }
926 #endif
927 #if (TLS13_PSK_HYBRID_KE_SUPPORT == ENABLED)
928  if(context->keyExchMethod == TLS13_KEY_EXCH_HYBRID)
929  {
930  context->keyExchMethod = TLS13_KEY_EXCH_PSK_HYBRID;
931  }
932 #endif
933  }
934 #else
935  //PreSharedKey extension found?
936  if(selectedIdentity != NULL)
937  {
938  //If a client receives an extension type that it did not request in the
939  //ClientHello, it must abort the handshake with an unsupported_extension
940  //fatal alert
942  }
943 #endif
944 
945  //Successful processing
946  return NO_ERROR;
947 }
948 
949 
950 /**
951  * @brief Parse EarlyData extension
952  * @param[in] msgType Handshake message type
953  * @param[in] context Pointer to the TLS context
954  * @param[in] earlyDataIndication Pointer to the EarlyData extension
955  * @return Error code
956  **/
957 
959  TlsMessageType msgType, const TlsExtension *earlyDataIndication)
960 {
961 #if (TLS13_EARLY_DATA_SUPPORT == ENABLED)
962  //The extension may appear in EncryptedExtensions and NewSessionTicket
963  //messages
965  {
966  //EarlyData extension found?
967  if(earlyDataIndication != NULL)
968  {
969  //If a client receives an extension type that it did not request in the
970  //ClientHello, it must abort the handshake with an unsupported_extension
971  //fatal alert
972  if(!context->earlyDataEnabled || context->earlyDataRejected)
974 
975  //If the server has supplied an EarlyData extension, the client must
976  //verify that the server's selected_identity is 0. If any other value
977  //is returned, it must abort the handshake with an illegal_parameter
978  //fatal alert
979  if(context->selectedIdentity != 0)
981 
982  //A valid EarlyData extension has been received
983  context->earlyDataExtReceived = TRUE;
984  }
985  else
986  {
987  //The EncryptedExtensions message does not contain any EarlyData
988  //extension
989  context->earlyDataExtReceived = FALSE;
990  }
991  }
993  {
994  //The extension contains the maximum amount of 0-RTT data that the client
995  //is allowed to send
996  if(earlyDataIndication != NULL)
997  {
998  context->maxEarlyDataSize = LOAD32BE(earlyDataIndication->value);
999  }
1000  else
1001  {
1002  context->maxEarlyDataSize = 0;
1003  }
1004  }
1005  else
1006  {
1007  //Just for sanity
1008  }
1009 #else
1010  //Check message type
1012  {
1013  //EarlyData extension found?
1014  if(earlyDataIndication != NULL)
1015  {
1016  //If a client receives an extension type that it did not request in the
1017  //ClientHello, it must abort the handshake with an unsupported_extension
1018  //fatal alert
1020  }
1021  }
1023  {
1024  //Early data is not implemented
1025  context->maxEarlyDataSize = 0;
1026  }
1027  else
1028  {
1029  //Just for sanity
1030  }
1031 #endif
1032 
1033  //Successful processing
1034  return NO_ERROR;
1035 }
1036 
1037 #endif
@ TLS_GROUP_X25519_MLKEM768
Definition: tls.h:1546
@ TLS13_KEY_EXCH_PSK
Definition: tls.h:1247
@ TLS_EXT_PSK_KEY_EXCHANGE_MODES
Definition: tls.h:1432
#define tlsAllocMem(size)
Definition: tls.h:911
#define htons(value)
Definition: cpu_endian.h:413
TLS helper functions.
#define TLS13_PSK_DHE_KE_SUPPORT
Definition: tls13_misc.h:71
Tls13PskBinderList
Definition: tls13_misc.h:275
uint16_t cipherSuite
Cipher suite identifier.
Definition: tls.h:2052
error_t dtlsSelectVersion(TlsContext *context, uint16_t version)
Set the DTLS version to be used.
Definition: dtls_misc.c:53
const HashAlgo * tlsGetHashAlgo(TlsHashAlgo hashAlgoId)
Get the hash algorithm that matches the specified identifier.
Definition: tls_misc.c:1431
@ TLS13_KEY_EXCH_MLKEM
Definition: tls.h:1245
@ TLS13_KEY_EXCH_PSK_DHE
Definition: tls.h:1248
Tls13Cookie
Definition: tls13_misc.h:197
#define LOAD32BE(p)
Definition: cpu_endian.h:210
@ ERROR_ILLEGAL_PARAMETER
Definition: error.h:244
uint8_t p
Definition: ndp.h:300
error_t tlsSelectVersion(TlsContext *context, uint16_t version)
Set the TLS version to be used.
Definition: tls_misc.c:305
#define TRUE
Definition: os_port.h:50
size_t digestSize
Definition: crypto.h:1249
#define TLS13_MAX_COOKIE_SIZE
Definition: tls13_misc.h:113
error_t tls13ParseServerKeyShareExtension(TlsContext *context, const Tls13KeyShareEntry *serverShare)
Parse KeyShare extension (ServerHello message)
TLS 1.3 session tickets.
@ TLS_TRANSPORT_PROTOCOL_DATAGRAM
Definition: tls.h:1039
TlsPskIdentity
Definition: tls.h:1864
TlsMessageType
Handshake message type.
Definition: tls.h:1122
@ TLS13_KEY_EXCH_PSK_MLKEM
Definition: tls.h:1250
bool_t tls13IsMlkemGroupSupported(TlsContext *context, uint16_t namedGroup)
Check whether a given ML-KEM exchange method is supported.
Definition: tls13_misc.c:1088
@ ERROR_OUT_OF_MEMORY
Definition: error.h:63
@ TLS13_KEY_EXCH_ECDHE
Definition: tls.h:1244
@ EC_PUBLIC_KEY_FORMAT_X963
Definition: ec.h:386
size_t publicKeySize
Definition: crypto.h:1306
#define osStrlen(s)
Definition: os_port.h:171
uint8_t version
Definition: coap_common.h:177
Tls13KeyShareEntry
Definition: tls13_misc.h:209
TlsExtension
Definition: tls.h:1742
@ TLS_EXT_EARLY_DATA
Definition: tls.h:1429
@ TLS13_KEY_EXCH_PSK_HYBRID
Definition: tls.h:1251
error_t tls13FormatClientEarlyDataExtension(TlsContext *context, uint8_t *p, size_t *written)
Format EarlyData extension.
@ TLS_PSK_KEY_EXCH_MODE_PSK_KE
Definition: tls13_misc.h:165
error_t tls13ParseSelectedGroupExtension(TlsContext *context, const TlsExtension *selectedGroup)
Parse KeyShare extension (HelloRetryRequest message)
@ TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE
Definition: tls13_misc.h:166
#define FALSE
Definition: os_port.h:46
error_t tls13ParseServerCookieExtension(TlsContext *context, const Tls13Cookie *cookie)
Parse Cookie extension.
error_t tls13ParseServerSupportedVersionsExtension(TlsContext *context, const TlsExtension *selectedVersion)
Parse SupportedVersions extension.
#define osMemcpy(dest, src, length)
Definition: os_port.h:147
@ ERROR_UNSUPPORTED_EXTENSION
Definition: error.h:246
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:43
bool_t tls13IsEcdheGroupSupported(TlsContext *context, uint16_t namedGroup)
Check whether a given ECDHE group is supported.
Definition: tls13_misc.c:1030
@ ERROR_FAILURE
Generic error code.
Definition: error.h:45
@ TLS13_KEY_EXCH_DHE
Definition: tls.h:1243
error_t tlsSelectCipherSuite(TlsContext *context, uint16_t identifier)
Set cipher suite.
Definition: tls_misc.c:333
error_t tls13Decapsulate(TlsContext *context, const uint8_t *keyShare, size_t length)
Decapsulation algorithm.
Definition: tls13_misc.c:661
@ TLS_EXT_KEY_SHARE
Definition: tls.h:1437
error_t tls13FormatClientKeyShareExtension(TlsContext *context, uint8_t *p, size_t *written)
Format KeyShare extension (ClientHello message)
#define TLS_VERSION_1_3
Definition: tls.h:99
error_t tls13FormatClientCookieExtension(TlsContext *context, uint8_t *p, size_t *written)
Format Cookie extension.
@ TLS_TYPE_ENCRYPTED_EXTENSIONS
Definition: tls.h:1130
bool_t tls13IsTicketValid(TlsContext *context)
Check whether a session ticket is valid.
Definition: tls13_ticket.c:51
@ TLS_EXT_COOKIE
Definition: tls.h:1431
bool_t tls13IsFfdheGroupSupported(TlsContext *context, uint16_t namedGroup)
Check whether a given FFDHE group is supported.
Definition: tls13_misc.c:990
Tls13PskBinder
Definition: tls13_misc.h:264
bool_t tls13IsHybridGroupSupported(TlsContext *context, uint16_t namedGroup)
Check whether a given hybrid key exchange method is supported.
Definition: tls13_misc.c:1129
error_t tls13FormatClientPreSharedKeyExtension(TlsContext *context, uint8_t *p, size_t *written, Tls13PskIdentityList **identityList, Tls13PskBinderList **binderList)
Format PreSharedKey extension.
#define TRACE_INFO(...)
Definition: debug.h:105
error_t dhExportPublicKey(DhContext *context, uint8_t *output, size_t *written, MpiFormat format)
Export our own public key.
Definition: dh.c:185
#define ENABLED
Definition: os_port.h:37
Tls13KeyShareList
Definition: tls13_misc.h:220
#define ntohs(value)
Definition: cpu_endian.h:421
#define TLS13_PSK_HYBRID_KE_SUPPORT
Definition: tls13_misc.h:92
@ TLS_KEY_EXCH_NONE
Definition: tls.h:1224
@ TLS13_KEY_EXCH_PSK_ECDHE
Definition: tls.h:1249
uint8_t msgType
error_t tls13GenerateSharedSecret(TlsContext *context, const uint8_t *keyShare, size_t length)
(EC)DHE shared secret generation
Definition: tls13_misc.c:407
bool_t tls13IsPskValid(TlsContext *context)
Check whether an externally established PSK is valid.
Definition: tls13_misc.c:911
error_t tls13GenerateKeyShare(TlsContext *context, uint16_t namedGroup)
Key share generation.
Definition: tls13_misc.c:234
uint8_t m
Definition: ndp.h:304
#define HTONS(value)
Definition: cpu_endian.h:410
uint8_t n
error_t tls13ParseServerPreSharedKeyExtension(TlsContext *context, const TlsExtension *selectedIdentity)
Parse PreSharedKey extension.
#define DTLS_VERSION_1_3
Definition: dtls_misc.h:37
@ TLS13_KEY_EXCH_HYBRID
Definition: tls.h:1246
error_t tls13FormatPskKeModesExtension(TlsContext *context, uint8_t *p, size_t *written)
Format PskKeyExchangeModes extension.
Common interface for key encapsulation mechanisms (KEM)
Definition: crypto.h:1304
Tls13PskKeModeList
Definition: tls13_misc.h:231
Formatting and parsing of extensions (TLS 1.3 client)
@ TLS_EXT_PRE_SHARED_KEY
Definition: tls.h:1428
@ MPI_FORMAT_BIG_ENDIAN
Definition: mpi.h:93
TLS (Transport Layer Security)
uint8_t cookie[]
Definition: dtls_misc.h:211
Common interface for hash algorithms.
Definition: crypto.h:1243
const char_t * tlsGetVersionName(uint16_t version)
Convert TLS version to string representation.
Definition: tls_misc.c:1370
@ TLS_TYPE_NEW_SESSION_TICKET
Definition: tls.h:1127
Tls13PskIdentityList
Definition: tls13_misc.h:253
#define LOAD16BE(p)
Definition: cpu_endian.h:186
#define osMemset(p, value, length)
Definition: os_port.h:141
#define TLS13_PSK_ECDHE_KE_SUPPORT
Definition: tls13_misc.h:78
#define tlsFreeMem(p)
Definition: tls.h:916
error_t ecdhExportPublicKey(EcdhContext *context, uint8_t *output, size_t *written, EcPublicKeyFormat format)
Export our own public key.
Definition: ecdh.c:257
#define STORE32BE(a, p)
Definition: cpu_endian.h:286
@ NO_ERROR
Success.
Definition: error.h:44
Debugging facilities.
error_t tls13ParseServerEarlyDataExtension(TlsContext *context, TlsMessageType msgType, const TlsExtension *earlyDataIndication)
Parse EarlyData extension.