tls_server_fsm.c
Go to the documentation of this file.
1 /**
2  * @file tls_server_fsm.c
3  * @brief TLS state machine (TLS server)
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 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.4.0
29  **/
30 
31 //Switch to the appropriate trace level
32 #define TRACE_LEVEL TLS_TRACE_LEVEL
33 
34 //Dependencies
35 #include "tls.h"
36 #include "tls_handshake.h"
37 #include "tls_server.h"
38 #include "tls_server_fsm.h"
39 #include "tls_common.h"
40 #include "tls_cache.h"
41 #include "tls_record.h"
42 #include "tls_misc.h"
43 #include "tls13_server.h"
44 #include "tls13_common.h"
45 #include "tls13_key_material.h"
46 #include "debug.h"
47 
48 //Check TLS library configuration
49 #if (TLS_SUPPORT == ENABLED && TLS_SERVER_SUPPORT == ENABLED)
50 
51 
52 /**
53  * @brief TLS server handshake
54  * @param[in] context Pointer to the TLS context
55  * @return Error code
56  **/
57 
59 {
60  error_t error;
61 
62  //Initialize status code
63  error = NO_ERROR;
64 
65  //Wait for the handshake to complete
66  while(!error)
67  {
68  //TLS protocol?
69  if(context->transportProtocol == TLS_TRANSPORT_PROTOCOL_STREAM)
70  {
71  //Check current state
72  if(context->state != TLS_STATE_INIT &&
73  context->state != TLS_STATE_CLOSED)
74  {
75  //Flush send buffer
76  error = tlsWriteProtocolData(context, NULL, 0, TLS_TYPE_NONE);
77  //Any error to report?
78  if(error)
79  break;
80  }
81  }
82 
83  //Check whether the handshake is complete
84  if(context->state == TLS_STATE_APPLICATION_DATA)
85  {
86  //At this is point, the handshake is complete and the server starts
87  //to exchange application-layer data
88  break;
89  }
90 
91  //The TLS handshake is implemented as a state machine representing the
92  //current location in the protocol
93  switch(context->state)
94  {
95  //Initial state?
96  case TLS_STATE_INIT:
97  //TLS handshake initialization
98  error = tlsInitHandshake(context);
99  break;
100 
101  //Sending ServerHello message?
104  //The server will send this message in response to a ClientHello
105  //message when it was able to find an acceptable set of algorithms
106  error = tlsSendServerHello(context);
107  break;
108 
109  //Sending Certificate message?
111  //The server must send a Certificate message whenever the agreed-
112  //upon key exchange method uses certificates for authentication. This
113  //message will always immediately follow the ServerHello message
114  error = tlsSendCertificate(context);
115  break;
116 
117  //Sending Certificate message?
119  //A non-anonymous server can optionally request a certificate from the
120  //client, if appropriate for the selected cipher suite. This message,
121  //if sent, will immediately follow the ServerKeyExchange message
122  error = tlsSendCertificateRequest(context);
123  break;
124 
125  //Sending NewSessionTicket message?
127 #if (TLS_MAX_VERSION >= TLS_VERSION_1_3 && TLS_MIN_VERSION <= TLS_VERSION_1_3)
128  //TLS 1.3 currently selected?
129  if(context->version == TLS_VERSION_1_3)
130  {
131  //At any time after the server has received the client Finished
132  //message, it may send a NewSessionTicket message
133  error = tls13SendNewSessionTicket(context);
134  }
135  else
136 #endif
137  {
138  //The NewSessionTicket message is sent by the server during the TLS
139  //handshake before the ChangeCipherSpec message
140  error = tlsSendNewSessionTicket(context);
141  }
142 
143  break;
144 
145  //Sending ChangeCipherSpec message?
148  //The ChangeCipherSpec message is sent by the server and to notify the
149  //client that subsequent records will be protected under the newly
150  //negotiated CipherSpec and keys
151  error = tlsSendChangeCipherSpec(context);
152  break;
153 
154  //Sending Finished message?
156  //A Finished message is always sent immediately after a ChangeCipherSpec
157  //message to verify that the key exchange and authentication processes
158  //were successful
159  error = tlsSendFinished(context);
160  break;
161 
162 #if (DTLS_SUPPORT == ENABLED)
163  //Sending HelloVerifyRequest message?
165  //When the client sends its ClientHello message to the server, the
166  //server may respond with a HelloVerifyRequest message
167  error = dtlsSendHelloVerifyRequest(context);
168  break;
169 #endif
170 
171 #if (TLS_MAX_VERSION >= TLS_VERSION_1_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
172  //Sending ServerKeyExchange message?
174  //The ServerKeyExchange message is sent by the server only when the
175  //server Certificate message (if sent) does not contain enough data
176  //to allow the client to exchange a premaster secret
177  error = tlsSendServerKeyExchange(context);
178  break;
179 
180  //Sending ServerHelloDone message?
182  //The ServerHelloDone message is sent by the server to indicate the
183  //end of the ServerHello and associated messages
184  error = tlsSendServerHelloDone(context);
185  break;
186 #endif
187 
188 #if (TLS_MAX_VERSION >= TLS_VERSION_1_3 && TLS_MIN_VERSION <= TLS_VERSION_1_3)
189  //Sending HelloRetryRequest message?
191  //The server sends a HelloRetryRequest message if the ClientHello
192  //message does not contain sufficient information to proceed with
193  //the handshake
194  error = tls13SendHelloRetryRequest(context);
195  break;
196 
197  //Handshake traffic key generation?
199  //Compute handshake traffic keys
200  error = tls13GenerateHandshakeTrafficKeys(context);
201  break;
202 
203  //Sending EncryptedExtensions message?
205  //The server sends the EncryptedExtensions message immediately after
206  //the ServerHello message. The EncryptedExtensions message contains
207  //extensions that can be protected
208  error = tls13SendEncryptedExtensions(context);
209  break;
210 
211  //Sending CertificateVerify message?
213  //Servers must send this message when authenticating via a
214  //certificate. When sent, this message must appear immediately
215  //after the Certificate message
216  error = tlsSendCertificateVerify(context);
217  break;
218 
219  //Server application traffic key generation?
221  //Compute server application traffic keys
222  error = tls13GenerateServerAppTrafficKeys(context);
223  break;
224 
225  //Client application traffic key generation?
227  //Compute client application traffic keys
228  error = tls13GenerateClientAppTrafficKeys(context);
229  break;
230 
231  //Sending KeyUpdate message?
233  //The KeyUpdate handshake message is used to indicate that the sender
234  //is updating its sending cryptographic keys
235  error = tls13SendKeyUpdate(context);
236  break;
237 #endif
238 
239  //Waiting for a message from the client?
247  //Receive client's message
248  error = tlsReceiveHandshakeMessage(context);
249  break;
250 
251  //Sending Alert message?
252  case TLS_STATE_CLOSING:
253  //Mark the TLS connection as closed
255  break;
256 
257  //TLS connection closed?
258  case TLS_STATE_CLOSED:
259  //Debug message
260  TRACE_WARNING("TLS handshake failure!\r\n");
261  //Report an error
262  error = ERROR_HANDSHAKE_FAILED;
263  break;
264 
265  //Invalid state?
266  default:
267  //Report an error
268  error = ERROR_UNEXPECTED_STATE;
269  break;
270  }
271  }
272 
273  //Successful TLS handshake?
274  if(!error)
275  {
276 #if (TLS_MAX_VERSION >= TLS_VERSION_1_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
277  //Version of TLS prior to TLS 1.3?
278  if(context->version <= TLS_VERSION_1_2)
279  {
280 #if (TLS_TICKET_SUPPORT == ENABLED)
281  //Any ticket presented by the client?
282  if(context->sessionTicketExtReceived)
283  {
284  //If a ticket is presented by the client, the server must not
285  //attempt to use the Session ID in the ClientHello for stateful
286  //session resumption
287  }
288  else
289 #endif
290  {
291  //Save current session in the session cache for further reuse
292  tlsSaveToCache(context);
293  }
294  }
295 #endif
296  }
297  else
298  {
299  //Send an alert message to the client, if applicable
300  tlsProcessError(context, error);
301  }
302 
303  //Return status code
304  return error;
305 }
306 
307 
308 /**
309  * @brief Parse client's handshake message
310  * @param[in] context Pointer to the TLS context
311  * @param[in] msgType Handshake message type
312  * @param[in] message Pointer to the handshake message to parse
313  * @param[in] length Length of the handshake messaged
314  * @return Error code
315  **/
316 
318  const void *message, size_t length)
319 {
320  error_t error;
321 
322  //Check handshake message type
323  switch(msgType)
324  {
325  //ClientHello message received?
327  //When a client first connects to a server, it is required to send the
328  //ClientHello as its first message
329  error = tlsParseClientHello(context, message, length);
330  break;
331 
332  //Certificate message received?
334  //This is the first message the client can send after receiving a
335  //ServerHelloDone message. This message is only sent if the server
336  //requests a certificate
337  error = tlsParseCertificate(context, message, length);
338  break;
339 
340  //CertificateVerify message received?
342  //This message is used to provide explicit verification of a client
343  //certificate. This message is only sent following a client certificate
344  //that has signing capability. When sent, it must immediately follow
345  //the clientKeyExchange message
346  error = tlsParseCertificateVerify(context, message, length);
347  break;
348 
349  //Finished message received?
350  case TLS_TYPE_FINISHED:
351  //A Finished message is always sent immediately after a ChangeCipherSpec
352  //message to verify that the key exchange and authentication processes
353  //were successful
354  error = tlsParseFinished(context, message, length);
355  break;
356 
357 #if (TLS_MAX_VERSION >= TLS_VERSION_1_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
358  //ClientKeyExchange message received?
360  //This message must immediately follow the client certificate message, if
361  //it is sent. Otherwise, it must be the first message sent by the client
362  //after it receives the ServerHelloDone message
363  error = tlsParseClientKeyExchange(context, message, length);
364  break;
365 #endif
366 
367 #if (TLS_MAX_VERSION >= TLS_VERSION_1_3 && TLS_MIN_VERSION <= TLS_VERSION_1_3)
368  //KeyUpdate message received?
369  case TLS_TYPE_KEY_UPDATE:
370  //The KeyUpdate handshake message is used to indicate that the client is
371  //updating its sending cryptographic keys. This message can be sent by
372  //the client after it has sent a Finished message
373  error = tls13ParseKeyUpdate(context, message, length);
374  break;
375 #endif
376 
377  //Invalid handshake message received?
378  default:
379  //Report an error
380  error = ERROR_UNEXPECTED_MESSAGE;
381  break;
382  }
383 
384  //Return status code
385  return error;
386 }
387 
388 #endif
uint8_t message[]
Definition: chap.h:154
Debugging facilities.
#define TRACE_WARNING(...)
Definition: debug.h:85
error_t dtlsSendHelloVerifyRequest(TlsContext *context)
Send HelloVerifyRequest message.
Definition: dtls_misc.c:247
error_t
Error codes.
Definition: error.h:43
@ ERROR_HANDSHAKE_FAILED
Definition: error.h:232
@ NO_ERROR
Success.
Definition: error.h:44
@ ERROR_UNEXPECTED_STATE
Definition: error.h:99
@ ERROR_UNEXPECTED_MESSAGE
Definition: error.h:194
uint8_t msgType
uint8_t length
Definition: tcp.h:368
error_t tls13SendKeyUpdate(TlsContext *context)
Send KeyUpdate message.
Definition: tls13_common.c:57
error_t tls13ParseKeyUpdate(TlsContext *context, const Tls13KeyUpdate *message, size_t length)
Parse KeyUpdate message.
Definition: tls13_common.c:178
Handshake message processing (TLS 1.3 client and server)
error_t tls13GenerateClientAppTrafficKeys(TlsContext *context)
Compute client application traffic keys.
error_t tls13GenerateServerAppTrafficKeys(TlsContext *context)
Compute server application traffic keys.
error_t tls13GenerateHandshakeTrafficKeys(TlsContext *context)
Compute handshake traffic keys.
TLS 1.3 key schedule.
error_t tls13SendNewSessionTicket(TlsContext *context)
Send NewSessionTicket message.
Definition: tls13_server.c:196
error_t tls13SendEncryptedExtensions(TlsContext *context)
Send EncryptedExtensions message.
Definition: tls13_server.c:138
error_t tls13SendHelloRetryRequest(TlsContext *context)
Send HelloRetryRequest message.
Definition: tls13_server.c:66
Handshake message processing (TLS 1.3 server)
TLS (Transport Layer Security)
@ TLS_STATE_SERVER_CHANGE_CIPHER_SPEC
Definition: tls.h:1461
@ TLS_STATE_SERVER_CERTIFICATE
Definition: tls.h:1449
@ TLS_STATE_CLIENT_CERTIFICATE_VERIFY
Definition: tls.h:1456
@ TLS_STATE_CLOSED
Definition: tls.h:1470
@ TLS_STATE_SERVER_CHANGE_CIPHER_SPEC_2
Definition: tls.h:1462
@ TLS_STATE_SERVER_CERTIFICATE_VERIFY
Definition: tls.h:1451
@ TLS_STATE_SERVER_HELLO_2
Definition: tls.h:1445
@ TLS_STATE_HELLO_VERIFY_REQUEST
Definition: tls.h:1442
@ TLS_STATE_CLIENT_FINISHED
Definition: tls.h:1459
@ TLS_STATE_CLIENT_APP_TRAFFIC_KEYS
Definition: tls.h:1460
@ TLS_STATE_SERVER_APP_TRAFFIC_KEYS
Definition: tls.h:1465
@ TLS_STATE_SERVER_FINISHED
Definition: tls.h:1463
@ TLS_STATE_CLIENT_HELLO_2
Definition: tls.h:1440
@ TLS_STATE_KEY_UPDATE
Definition: tls.h:1467
@ TLS_STATE_SERVER_HELLO
Definition: tls.h:1444
@ TLS_STATE_APPLICATION_DATA
Definition: tls.h:1468
@ TLS_STATE_SERVER_KEY_EXCHANGE
Definition: tls.h:1450
@ TLS_STATE_INIT
Definition: tls.h:1438
@ TLS_STATE_NEW_SESSION_TICKET
Definition: tls.h:1466
@ TLS_STATE_HELLO_RETRY_REQUEST
Definition: tls.h:1443
@ TLS_STATE_CLOSING
Definition: tls.h:1469
@ TLS_STATE_SERVER_HELLO_DONE
Definition: tls.h:1453
@ TLS_STATE_CLIENT_HELLO
Definition: tls.h:1439
@ TLS_STATE_CERTIFICATE_REQUEST
Definition: tls.h:1452
@ TLS_STATE_HANDSHAKE_TRAFFIC_KEYS
Definition: tls.h:1447
@ TLS_STATE_CLIENT_KEY_EXCHANGE
Definition: tls.h:1455
@ TLS_STATE_CLIENT_CERTIFICATE
Definition: tls.h:1454
@ TLS_STATE_CLIENT_CHANGE_CIPHER_SPEC
Definition: tls.h:1457
@ TLS_STATE_ENCRYPTED_EXTENSIONS
Definition: tls.h:1448
@ TLS_TRANSPORT_PROTOCOL_STREAM
Definition: tls.h:941
@ TLS_TYPE_NONE
Definition: tls.h:1008
#define TLS_VERSION_1_3
Definition: tls.h:97
#define TlsContext
Definition: tls.h:36
@ TLS_TYPE_CLIENT_HELLO
Definition: tls.h:1026
@ TLS_TYPE_CERTIFICATE_VERIFY
Definition: tls.h:1039
@ TLS_TYPE_FINISHED
Definition: tls.h:1041
@ TLS_TYPE_CERTIFICATE
Definition: tls.h:1035
@ TLS_TYPE_KEY_UPDATE
Definition: tls.h:1045
@ TLS_TYPE_CLIENT_KEY_EXCHANGE
Definition: tls.h:1040
#define TLS_VERSION_1_2
Definition: tls.h:96
error_t tlsSaveToCache(TlsContext *context)
Save current session in cache.
Definition: tls_cache.c:164
Session cache management.
error_t tlsParseCertificateVerify(TlsContext *context, const TlsCertificateVerify *message, size_t length)
Parse CertificateVerify message.
Definition: tls_common.c:1227
error_t tlsSendChangeCipherSpec(TlsContext *context)
Send ChangeCipherSpec message.
Definition: tls_common.c:273
error_t tlsSendFinished(TlsContext *context)
Send Finished message.
Definition: tls_common.c:394
error_t tlsParseCertificate(TlsContext *context, const TlsCertificate *message, size_t length)
Parse Certificate message.
Definition: tls_common.c:1018
error_t tlsSendCertificateVerify(TlsContext *context)
Send CertificateVerify message.
Definition: tls_common.c:192
error_t tlsParseFinished(TlsContext *context, const TlsFinished *message, size_t length)
Parse Finished message.
Definition: tls_common.c:1455
error_t tlsSendCertificate(TlsContext *context)
Send Certificate message.
Definition: tls_common.c:66
Handshake message processing (TLS client and server)
error_t tlsReceiveHandshakeMessage(TlsContext *context)
Receive peer's message.
error_t tlsInitHandshake(TlsContext *context)
TLS handshake initialization.
Definition: tls_handshake.c:57
TLS handshake.
void tlsChangeState(TlsContext *context, TlsState newState)
Update TLS state.
Definition: tls_misc.c:54
void tlsProcessError(TlsContext *context, error_t errorCode)
Translate an error code to an alert message.
Definition: tls_misc.c:74
TLS helper functions.
error_t tlsWriteProtocolData(TlsContext *context, const uint8_t *data, size_t length, TlsContentType contentType)
Write protocol data.
Definition: tls_record.c:54
TLS record protocol.
error_t tlsSendServerHelloDone(TlsContext *context)
Send ServerHelloDone message.
Definition: tls_server.c:352
error_t tlsParseClientKeyExchange(TlsContext *context, const TlsClientKeyExchange *message, size_t length)
Parse ClientKeyExchange message.
Definition: tls_server.c:1649
error_t tlsParseClientHello(TlsContext *context, const TlsClientHello *message, size_t length)
Parse ClientHello message.
Definition: tls_server.c:1163
error_t tlsSendServerKeyExchange(TlsContext *context)
Send ServerKeyExchange message.
Definition: tls_server.c:192
error_t tlsSendCertificateRequest(TlsContext *context)
Send CertificateRequest message.
Definition: tls_server.c:275
error_t tlsSendServerHello(TlsContext *context)
Send ServerHello message.
Definition: tls_server.c:82
error_t tlsSendNewSessionTicket(TlsContext *context)
Send NewSessionTicket message.
Definition: tls_server.c:405
Handshake message processing (TLS server)
error_t tlsPerformServerHandshake(TlsContext *context)
TLS server handshake.
error_t tlsParseClientHandshakeMessage(TlsContext *context, uint8_t msgType, const void *message, size_t length)
Parse client's handshake message.
TLS state machine (TLS server)