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