tls13_server.c
Go to the documentation of this file.
1 /**
2  * @file tls13_server.c
3  * @brief Handshake message processing (TLS 1.3 server)
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 //Switch to the appropriate trace level
32 #define TRACE_LEVEL TLS_TRACE_LEVEL
33 
34 //Dependencies
35 #include <string.h>
36 #include "tls.h"
37 #include "tls_handshake.h"
38 #include "tls_server_extensions.h"
39 #include "tls_server_misc.h"
40 #include "tls_extensions.h"
41 #include "tls_transcript_hash.h"
42 #include "tls_ffdhe.h"
43 #include "tls_misc.h"
44 #include "tls13_server.h"
46 #include "tls13_server_misc.h"
47 #include "tls13_misc.h"
48 #include "debug.h"
49 
50 //Check TLS library configuration
51 #if (TLS_SUPPORT == ENABLED && TLS_SERVER_SUPPORT == ENABLED && \
52  TLS_MAX_VERSION >= TLS_VERSION_1_3)
53 
54 
55 /**
56  * @brief Send HelloRetryRequest message
57  *
58  * The server will send this message in response to a ClientHello message if it
59  * is able to find an acceptable set of parameters but the ClientHello does not
60  * contain sufficient information to proceed with the handshake
61  *
62  * @param[in] context Pointer to the TLS context
63  * @return Error code
64  **/
65 
67 {
68  error_t error;
69  size_t length;
71 
72  //Point to the buffer where to format the message
73  message = (Tls13HelloRetryRequest *) (context->txBuffer + context->txBufferLen);
74 
75  //When the server responds to a ClientHello with a HelloRetryRequest, the
76  //value of ClientHello1 is replaced with a special synthetic handshake
77  //message of handshake type MessageHash containing Hash(ClientHello1)
78  error = tls13DigestClientHello1(context);
79 
80  //Check status code
81  if(!error)
82  {
83  //Format HelloRetryRequest message
84  error = tls13FormatHelloRetryRequest(context, message, &length);
85  }
86 
87  //Check status code
88  if(!error)
89  {
90  //Debug message
91  TRACE_INFO("Sending HelloRetryRequest message (%" PRIuSIZE " bytes)...\r\n", length);
93 
94  //For reasons of backward compatibility with middleboxes the
95  //HelloRetryRequest message uses the same format as the ServerHello
96  error = tlsSendHandshakeMessage(context, message, length,
98  }
99 
100  //Check status code
101  if(error == NO_ERROR || error == ERROR_WOULD_BLOCK || error == ERROR_TIMEOUT)
102  {
103 #if (TLS13_MIDDLEBOX_COMPAT_SUPPORT == ENABLED)
104  //In middlebox compatibility mode, the server sends a dummy ChangeCipherSpec
105  //record immediately after its first handshake message. This may either be
106  //after a ServerHello or a HelloRetryRequest
107  context->state = TLS_STATE_SERVER_CHANGE_CIPHER_SPEC_2;
108 #else
109  //Wait for the second updated ClientHello
110  context->state = TLS_STATE_CLIENT_HELLO_2;
111 #endif
112  }
113 
114  //Return status code
115  return error;
116 }
117 
118 
119 /**
120  * @brief Send EncryptedExtensions message
121  *
122  * The server sends the EncryptedExtensions message immediately after the
123  * ServerHello message. The EncryptedExtensions message contains extensions
124  * that can be protected
125  *
126  * @param[in] context Pointer to the TLS context
127  * @return Error code
128  **/
129 
131 {
132  error_t error;
133  size_t length;
135 
136  //Point to the buffer where to format the message
137  message = (Tls13EncryptedExtensions *) (context->txBuffer + context->txBufferLen);
138 
139  //Format EncryptedExtensions message
140  error = tls13FormatEncryptedExtensions(context, message, &length);
141 
142  //Check status code
143  if(!error)
144  {
145  //Debug message
146  TRACE_INFO("Sending EncryptedExtensions message (%" PRIuSIZE " bytes)...\r\n", length);
148 
149  //Send handshake message
150  error = tlsSendHandshakeMessage(context, message, length,
152  }
153 
154  //Check status code
155  if(error == NO_ERROR || error == ERROR_WOULD_BLOCK || error == ERROR_TIMEOUT)
156  {
157  //PSK key exchange method?
158  if(context->keyExchMethod == TLS13_KEY_EXCH_PSK ||
159  context->keyExchMethod == TLS13_KEY_EXCH_PSK_DHE ||
160  context->keyExchMethod == TLS13_KEY_EXCH_PSK_ECDHE)
161  {
162  //As the server is authenticating via a PSK, it does not send a
163  //Certificate or a CertificateVerify message
164  context->state = TLS_STATE_SERVER_FINISHED;
165  }
166  else
167  {
168  //A server can optionally request a certificate from the client
169  context->state = TLS_STATE_CERTIFICATE_REQUEST;
170  }
171  }
172 
173  //Return status code
174  return error;
175 }
176 
177 
178 /**
179  * @brief Send NewSessionTicket message
180  *
181  * At any time after the server has received the client Finished message, it
182  * may send a NewSessionTicket message
183  *
184  * @param[in] context Pointer to the TLS context
185  * @return Error code
186  **/
187 
189 {
190  error_t error;
191  size_t length;
193 
194  //Initialize status code
195  error = NO_ERROR;
196 
197  //Send as many NewSessionTicket messages as requested
198  if(context->newSessionTicketCount < TLS13_NEW_SESSION_TICKET_COUNT)
199  {
200  //Point to the buffer where to format the message
201  message = (Tls13NewSessionTicket *) (context->txBuffer + context->txBufferLen);
202 
203  //Format NewSessionTicket message
204  error = tls13FormatNewSessionTicket(context, message, &length);
205 
206  //Check status code
207  if(!error)
208  {
209  //Increment the number of NewSessionTicket messages that have been sent
210  context->newSessionTicketCount++;
211 
212  //Debug message
213  TRACE_INFO("Sending NewSessionTicket message (%" PRIuSIZE " bytes)...\r\n", length);
215 
216  //Send handshake message
217  error = tlsSendHandshakeMessage(context, message, length,
219  }
220  }
221  else
222  {
223  //The client and server can now exchange application-layer data
224  context->state = TLS_STATE_APPLICATION_DATA;
225  }
226 
227  //Return status code
228  return error;
229 }
230 
231 
232 /**
233  * @brief Format HelloRetryRequest message
234  * @param[in] context Pointer to the TLS context
235  * @param[out] message Buffer where to format the HelloRetryRequest message
236  * @param[out] length Length of the resulting HelloRetryRequest message
237  * @return Error code
238  **/
239 
242 {
243  error_t error;
244  size_t n;
245  uint8_t *p;
246  TlsExtensionList *extensionList;
247 
248  //In TLS 1.3, the client indicates its version preferences in the
249  //SupportedVersions extension and the legacy_version field must be set
250  //to 0x0303, which is the version number for TLS 1.2
251  if(context->transportProtocol == TLS_TRANSPORT_PROTOCOL_DATAGRAM)
252  message->serverVersion = HTONS(DTLS_VERSION_1_2);
253  else
254  message->serverVersion = HTONS(TLS_VERSION_1_2);
255 
256  //For backward compatibility with middleboxes the HelloRetryRequest message
257  //uses the same structure as the ServerHello, but with Random field set to
258  //a special value
259  memcpy(message->random, tls13HelloRetryRequestRandom, 32);
260 
261  //Point to the session ID
262  p = message->sessionId;
263  //Length of the handshake message
264  *length = sizeof(Tls13HelloRetryRequest);
265 
266  //The legacy_session_id_echo echoes the contents of the client's
267  //legacy_session_id field
268  memcpy(message->sessionId, context->sessionId, context->sessionIdLen);
269  message->sessionIdLen = (uint8_t) context->sessionIdLen;
270 
271  //Debug message
272  TRACE_INFO("Session ID (%" PRIu8 " bytes):\r\n", message->sessionIdLen);
273  TRACE_INFO_ARRAY(" ", message->sessionId, message->sessionIdLen);
274 
275  //Advance data pointer
276  p += message->sessionIdLen;
277  //Adjust the length of the message
278  *length += message->sessionIdLen;
279 
280  //The cipher_suite field contains the cipher suite selected by the server
281  STORE16BE(context->cipherSuite.identifier, p);
282  //Advance data pointer
283  p += sizeof(uint16_t);
284  //Adjust the length of the message
285  *length += sizeof(uint16_t);
286 
287  //The legacy_compression_method field must have the value 0
289  //Advance data pointer
290  p += sizeof(uint8_t);
291  //Adjust the length of the message
292  *length += sizeof(uint8_t);
293 
294  //Point to the list of extensions
295  extensionList = (TlsExtensionList *) p;
296  //Total length of the extension list
297  extensionList->length = 0;
298 
299  //Point to the first extension of the list
300  p += sizeof(TlsExtensionList);
301  //Adjust the length of the message
302  *length += sizeof(TlsExtensionList);
303 
304  //The HelloRetryRequest message must contain a SupportedVersions extension
305  error = tls13FormatServerSupportedVersionsExtension(context, p, &n);
306  //Any error to report?
307  if(error)
308  return error;
309 
310  //Fix the length of the extension list
311  extensionList->length += (uint16_t) n;
312  //Point to the next field
313  p += n;
314 
315  //The KeyShare extension contains the mutually supported group the server
316  //intends to negotiate
317  error = tls13FormatSelectedGroupExtension(context, p, &n);
318  //Any error to report?
319  if(error)
320  return error;
321 
322  //Fix the length of the extension list
323  extensionList->length += (uint16_t) n;
324  //Point to the next field
325  p += n;
326 
327  //Convert the length of the extension list to network byte order
328  extensionList->length = htons(extensionList->length);
329  //Total length of the message
330  *length += htons(extensionList->length);
331 
332  //Successful processing
333  return NO_ERROR;
334 }
335 
336 
337 /**
338  * @brief Format EncryptedExtensions message
339  * @param[in] context Pointer to the TLS context
340  * @param[out] message Buffer where to format the EncryptedExtensions message
341  * @param[out] length Length of the resulting EncryptedExtensions message
342  * @return Error code
343  **/
344 
347 {
348  error_t error;
349  size_t n;
350  uint8_t *p;
351 
352  //Point to the extension of the list
353  p = message->extensions;
354  //Length of the handshake message
355  *length = sizeof(Tls13EncryptedExtensions);
356 
357  //Total length of the extension list
358  message->extensionsLen = 0;
359 
360 #if (TLS_SNI_SUPPORT == ENABLED)
361  //The server may include a SNI extension in the ServerHello
362  error = tlsFormatServerSniExtension(context, p, &n);
363  //Any error to report?
364  if(error)
365  return error;
366 
367  //Fix the length of the extension list
368  message->extensionsLen += (uint16_t) n;
369  //Point to the next field
370  p += n;
371 #endif
372 
373 #if (TLS_MAX_FRAG_LEN_SUPPORT == ENABLED)
374  //Servers that receive an ClientHello containing a MaxFragmentLength
375  //extension may accept the requested maximum fragment length by including
376  //an extension of type MaxFragmentLength in the ServerHello
377  error = tlsFormatServerMaxFragLenExtension(context, p, &n);
378  //Any error to report?
379  if(error)
380  return error;
381 
382  //Fix the length of the extension list
383  message->extensionsLen += (uint16_t) n;
384  //Point to the next field
385  p += n;
386 #endif
387 
388 #if (TLS_RECORD_SIZE_LIMIT_SUPPORT == ENABLED)
389  //The value of RecordSizeLimit is the maximum size of record in octets
390  //that the endpoint is willing to receive
391  error = tlsFormatServerRecordSizeLimitExtension(context, p, &n);
392  //Any error to report?
393  if(error)
394  return error;
395 
396  //Fix the length of the extension list
397  message->extensionsLen += (uint16_t) n;
398  //Point to the next field
399  p += n;
400 #endif
401 
402 #if (TLS_ALPN_SUPPORT == ENABLED)
403  //The ALPN extension contains the name of the selected protocol
404  error = tlsFormatServerAlpnExtension(context, p, &n);
405  //Any error to report?
406  if(error)
407  return error;
408 
409  //Fix the length of the extension list
410  message->extensionsLen += (uint16_t) n;
411  //Point to the next field
412  p += n;
413 #endif
414 
415 #if (TLS_RAW_PUBLIC_KEY_SUPPORT == ENABLED)
416  //The ClientCertType extension in the ServerHello indicates the type
417  //of certificates the client is requested to provide in a subsequent
418  //certificate payload
419  error = tlsFormatClientCertTypeExtension(context, p, &n);
420  //Any error to report?
421  if(error)
422  return error;
423 
424  //Fix the length of the extension list
425  message->extensionsLen += (uint16_t) n;
426  //Point to the next field
427  p += n;
428 
429  //With the ServerCertType extension in the ServerHello, the TLS server
430  //indicates the certificate type carried in the certificate payload
431  error = tlsFormatServerCertTypeExtension(context, p, &n);
432  //Any error to report?
433  if(error)
434  return error;
435 
436  //Fix the length of the extension list
437  message->extensionsLen += (uint16_t) n;
438  //Point to the next field
439  p += n;
440 #endif
441 
442 #if (TLS13_EARLY_DATA_SUPPORT == ENABLED)
443  //If the server intends to process the early data, then it returns its
444  //own EarlyData extension in the EncryptedExtensions message
445  error = tls13FormatServerEarlyDataExtension(context,
447  //Any error to report?
448  if(error)
449  return error;
450 
451  //Fix the length of the extension list
452  message->extensionsLen += (uint16_t) n;
453  //Point to the next field
454  p += n;
455 #endif
456 
457  //Convert the length of the extension list to network byte order
458  message->extensionsLen = htons(message->extensionsLen);
459  //Total length of the message
460  *length += htons(message->extensionsLen);
461 
462  //Successful processing
463  return NO_ERROR;
464 }
465 
466 
467 /**
468  * @brief Format NewSessionTicket message
469  * @param[in] context Pointer to the TLS context
470  * @param[out] message Buffer where to format the NewSessionTicket message
471  * @param[out] length Length of the resulting NewSessionTicket message
472  * @return Error code
473  **/
474 
477 {
478 #if (TLS_TICKET_SUPPORT == ENABLED)
479  error_t error;
480  size_t n;
481  uint8_t *p;
482  Tls13Ticket *ticket;
483  TlsExtensionList *extensionList;
484 
485  //Set the lifetime of the ticket, in seconds
486  message->ticketLifetime = HTONL(TLS_TICKET_LIFETIME / 1000);
487 
488  //The ticket_age_add field is used to obscure the age of the ticket
489  error = context->prngAlgo->read(context->prngContext,
490  (uint8_t *) &message->ticketAgeAdd, sizeof(uint32_t));
491  //Any error to report?
492  if(error)
493  return error;
494 
495  //Point to ticket nonce
496  p = message->ticketNonce;
497  //Length of the handshake message
498  *length = sizeof(Tls13NewSessionTicket);
499 
500  //The ticket nonce is a per-ticket value that is unique across all tickets
501  //issued on this connection
502  context->ticketNonce++;
503 
504  //Copy ticket nonce
505  STORE32BE(context->ticketNonce, message->ticketNonce);
506  //Set the length of the nonce
507  message->ticketNonceLen = sizeof(uint32_t);
508 
509  //Advance data pointer
510  p += message->ticketNonceLen;
511  //Adjust the length of the message
512  *length += message->ticketNonceLen;
513 
514  //Point to the value of the ticket
515  ticket = (Tls13Ticket *) p;
516 
517  //The ticket itself is an opaque label. It may be either a database lookup
518  //key or a self-encrypted and self-authenticated value
519  error = tls13GenerateTicket(context, message, ticket->data, &n);
520  //Any error to report?
521  if(error)
522  return error;
523 
524  //Fix the length of the ticket
525  ticket->length = htons(n);
526 
527  //Advance data pointer
528  p += sizeof(Tls13Ticket) + n;
529  //Adjust the length of the message
530  *length += sizeof(Tls13Ticket) + n;
531 
532  //Point to the list of extensions
533  extensionList = (TlsExtensionList *) p;
534  //Total length of the extension list
535  extensionList->length = 0;
536 
537  //Point to the first extension of the list
538  p += sizeof(TlsExtensionList);
539  //Adjust the length of the message
540  *length += sizeof(TlsExtensionList);
541 
542 #if (TLS13_EARLY_DATA_SUPPORT == ENABLED)
543  //The sole extension currently defined for NewSessionTicket is EarlyData
544  //indicating that the ticket may be used to send 0-RTT data
545  error = tls13FormatServerEarlyDataExtension(context,
547  //Any error to report?
548  if(error)
549  return error;
550 
551  //Fix the length of the extension list
552  extensionList->length += (uint16_t) n;
553  //Point to the next field
554  p += n;
555 #endif
556 
557  //Convert the length of the extension list to network byte order
558  extensionList->length = htons(extensionList->length);
559  //Total length of the message
560  *length += htons(extensionList->length);
561 
562  //Successful processing
563  return NO_ERROR;
564 #else
565  //Session ticket mechanism is not implemented
566  return ERROR_NOT_IMPLEMENTED;
567 #endif
568 }
569 
570 #endif
@ TLS13_KEY_EXCH_PSK
Definition: tls.h:1047
error_t tls13FormatNewSessionTicket(TlsContext *context, Tls13NewSessionTicket *message, size_t *length)
#define htons(value)
Definition: cpu_endian.h:392
Parsing and checking of TLS extensions.
TLS helper functions.
#define TRACE_INFO_ARRAY(p, a, n)
Definition: debug.h:95
uint8_t length
Definition: dtls_misc.h:149
error_t tls13FormatSelectedGroupExtension(TlsContext *context, uint8_t *p, size_t *written)
__start_packed struct @69 TlsExtensionList
List of TLS extensions.
Handshake message processing (TLS 1.3 server)
@ ERROR_WOULD_BLOCK
Definition: error.h:95
@ TLS13_KEY_EXCH_PSK_DHE
Definition: tls.h:1048
TLS handshake.
@ TLS_COMPRESSION_METHOD_NULL
Definition: tls.h:1015
error_t tls13GenerateTicket(TlsContext *context, const Tls13NewSessionTicket *message, uint8_t *ticket, size_t *length)
@ ERROR_NOT_IMPLEMENTED
Definition: error.h:66
uint8_t p
Definition: ndp.h:298
__start_packed struct @100 Tls13HelloRetryRequest
HelloRetryRequest message.
error_t tls13DigestClientHello1(TlsContext *context)
error_t tls13SendEncryptedExtensions(TlsContext *context)
@ TLS_STATE_CERTIFICATE_REQUEST
Definition: tls.h:1303
@ TLS_TRANSPORT_PROTOCOL_DATAGRAM
Definition: tls.h:851
@ TLS_STATE_APPLICATION_DATA
Definition: tls.h:1319
error_t tls13FormatHelloRetryRequest(TlsContext *context, Tls13HelloRetryRequest *message, size_t *length)
error_t tlsSendHandshakeMessage(TlsContext *context, const void *data, size_t length, TlsMessageType type)
Send handshake message.
error_t tlsFormatServerSniExtension(TlsContext *context, uint8_t *p, size_t *written)
Format SNI extension.
TLS 1.3 helper functions.
error_t tlsFormatServerRecordSizeLimitExtension(TlsContext *context, uint8_t *p, size_t *written)
Format RecordSizeLimit extension.
#define HTONL(value)
Definition: cpu_endian.h:391
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
error_t tls13SendNewSessionTicket(TlsContext *context)
#define TLS_VERSION_1_2
Definition: tls.h:94
Formatting and parsing of extensions (TLS 1.3 server)
__start_packed struct @101 Tls13EncryptedExtensions
EncryptedExtensions message.
#define STORE16BE(a, p)
Definition: cpu_endian.h:246
error_t tls13FormatServerEarlyDataExtension(TlsContext *context, TlsMessageType msgType, uint8_t *p, size_t *written)
@ TLS_STATE_SERVER_FINISHED
Definition: tls.h:1314
error_t tlsFormatClientCertTypeExtension(TlsContext *context, uint8_t *p, size_t *written)
Format ClientCertType extension.
@ TLS_TYPE_SERVER_HELLO
Definition: tls.h:934
@ TLS_TYPE_ENCRYPTED_EXTENSIONS
Definition: tls.h:939
#define TRACE_INFO(...)
Definition: debug.h:94
Helper functions for TLS 1.3 server.
error_t tlsFormatServerMaxFragLenExtension(TlsContext *context, uint8_t *p, size_t *written)
Format MaxFragmentLength extension.
Transcript hash calculation.
@ ERROR_TIMEOUT
Definition: error.h:94
@ TLS13_KEY_EXCH_PSK_ECDHE
Definition: tls.h:1049
@ TLS_STATE_CLIENT_HELLO_2
Definition: tls.h:1291
error_t tls13FormatEncryptedExtensions(TlsContext *context, Tls13EncryptedExtensions *message, size_t *length)
#define TRACE_DEBUG_ARRAY(p, a, n)
Definition: debug.h:107
#define TLS_TICKET_LIFETIME
Definition: tls.h:155
#define HTONS(value)
Definition: cpu_endian.h:390
uint8_t n
uint8_t message[]
Definition: chap.h:152
TLS (Transport Layer Security)
__start_packed struct @102 Tls13NewSessionTicket
NewSessionTicket message (TLS 1.3)
FFDHE key exchange.
Helper functions for TLS server.
@ TLS_STATE_SERVER_CHANGE_CIPHER_SPEC_2
Definition: tls.h:1313
Formatting and parsing of extensions (TLS server)
@ TLS_TYPE_NEW_SESSION_TICKET
Definition: tls.h:936
__start_packed struct @104 Tls13Ticket
Session ticket.
#define PRIuSIZE
Definition: compiler_port.h:78
error_t tlsFormatServerCertTypeExtension(TlsContext *context, uint8_t *p, size_t *written)
Format ServerCertType extension.
error_t tls13FormatServerSupportedVersionsExtension(TlsContext *context, uint8_t *p, size_t *written)
error_t tlsFormatServerAlpnExtension(TlsContext *context, uint8_t *p, size_t *written)
Format ALPN extension.
#define DTLS_VERSION_1_2
Definition: dtls_misc.h:36
#define STORE32BE(a, p)
Definition: cpu_endian.h:270
@ NO_ERROR
Success.
Definition: error.h:44
Debugging facilities.
const uint8_t tls13HelloRetryRequestRandom[32]
error_t tls13SendHelloRetryRequest(TlsContext *context)
#define TLS13_NEW_SESSION_TICKET_COUNT
Definition: tls13_misc.h:113