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-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 "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 ChangeCipherSpec message?
128  //The ChangeCipherSpec message is sent by the server and to notify the
129  //client that subsequent records will be protected under the newly
130  //negotiated CipherSpec and keys
131  error = tlsSendChangeCipherSpec(context);
132  break;
133 
134  //Sending Finished message?
136  //A Finished message is always sent immediately after a ChangeCipherSpec
137  //message to verify that the key exchange and authentication processes
138  //were successful
139  error = tlsSendFinished(context);
140  break;
141 
142 #if (DTLS_SUPPORT == ENABLED)
143  //Sending HelloVerifyRequest message?
145  //When the client sends its ClientHello message to the server, the
146  //server may respond with a HelloVerifyRequest message
147  error = dtlsSendHelloVerifyRequest(context);
148  break;
149 #endif
150 
151 #if (TLS_MAX_VERSION >= SSL_VERSION_3_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
152  //Sending ServerKeyExchange message?
154  //The ServerKeyExchange message is sent by the server only when the
155  //server Certificate message (if sent) does not contain enough data
156  //to allow the client to exchange a premaster secret
157  error = tlsSendServerKeyExchange(context);
158  break;
159 
160  //Sending ServerHelloDone message?
162  //The ServerHelloDone message is sent by the server to indicate the
163  //end of the ServerHello and associated messages
164  error = tlsSendServerHelloDone(context);
165  break;
166 #endif
167 
168 #if (TLS_MAX_VERSION >= TLS_VERSION_1_3 && TLS_MIN_VERSION <= TLS_VERSION_1_3)
169  //Sending HelloRetryRequest message?
171  //The server sends a HelloRetryRequest message if the ClientHello
172  //message does not contain sufficient information to proceed with
173  //the handshake
174  error = tls13SendHelloRetryRequest(context);
175  break;
176 
177  //Handshake traffic key generation?
179  //Compute handshake traffic keys
180  error = tls13GenerateHandshakeTrafficKeys(context);
181  break;
182 
183  //Sending EncryptedExtensions message?
185  //The server sends the EncryptedExtensions message immediately after
186  //the ServerHello message. The EncryptedExtensions message contains
187  //extensions that can be protected
188  error = tls13SendEncryptedExtensions(context);
189  break;
190 
191  //Sending CertificateVerify message?
193  //Servers must send this message when authenticating via a
194  //certificate. When sent, this message must appear immediately
195  //after the Certificate message
196  error = tlsSendCertificateVerify(context);
197  break;
198 
199  //Server application traffic key generation?
201  //Compute server application traffic keys
202  error = tls13GenerateServerAppTrafficKeys(context);
203  break;
204 
205  //Client application traffic key generation?
207  //Compute client application traffic keys
208  error = tls13GenerateClientAppTrafficKeys(context);
209  break;
210 
211  //Sending NewSessionTicket message message?
213  //At any time after the server has received the client Finished
214  //message, it may send a NewSessionTicket message
215  error = tls13SendNewSessionTicket(context);
216  break;
217 
218  //Sending KeyUpdate message?
220  //The KeyUpdate handshake message is used to indicate that the sender
221  //is updating its sending cryptographic keys
222  error = tls13SendKeyUpdate(context);
223  break;
224 #endif
225 
226  //Waiting for a message from the client?
234  //Receive client's message
235  error = tlsReceiveHandshakeMessage(context);
236  break;
237 
238  //Sending Alert message?
239  case TLS_STATE_CLOSING:
240  //Mark the TLS connection as closed
241  context->state = TLS_STATE_CLOSED;
242  break;
243 
244  //TLS connection closed?
245  case TLS_STATE_CLOSED:
246  //Debug message
247  TRACE_WARNING("TLS handshake failure!\r\n");
248  //Report an error
249  error = ERROR_HANDSHAKE_FAILED;
250  break;
251 
252  //Invalid state?
253  default:
254  //Report an error
255  error = ERROR_UNEXPECTED_STATE;
256  break;
257  }
258  }
259 
260  //Successful TLS handshake?
261  if(!error)
262  {
263 #if (TLS_MAX_VERSION >= SSL_VERSION_3_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
264  //Version of TLS prior to TLS 1.3?
265  if(context->version <= TLS_VERSION_1_2)
266  {
267  //Save current session in the session cache for further reuse
268  tlsSaveToCache(context);
269  }
270 #endif
271  }
272  else
273  {
274  //Send an alert message to the client, if applicable
275  tlsProcessError(context, error);
276  }
277 
278  //Return status code
279  return error;
280 }
281 
282 
283 /**
284  * @brief Parse client's handshake message
285  * @param[in] context Pointer to the TLS context
286  * @param[in] msgType Handshake message type
287  * @param[in] message Pointer to the handshake message to parse
288  * @param[in] length Length of the handshake messaged
289  * @return Error code
290  **/
291 
293  const void *message, size_t length)
294 {
295  error_t error;
296 
297  //Check handshake message type
298  switch(msgType)
299  {
300  //ClientHello message received?
302  //When a client first connects to a server, it is required to send the
303  //ClientHello as its first message
304  error = tlsParseClientHello(context, message, length);
305  break;
306 
307  //Certificate message received?
309  //This is the first message the client can send after receiving a
310  //ServerHelloDone message. This message is only sent if the server
311  //requests a certificate
312  error = tlsParseCertificate(context, message, length);
313  break;
314 
315  //CertificateVerify message received?
317  //This message is used to provide explicit verification of a client
318  //certificate. This message is only sent following a client certificate
319  //that has signing capability. When sent, it must immediately follow
320  //the clientKeyExchange message
321  error = tlsParseCertificateVerify(context, message, length);
322  break;
323 
324  //Finished message received?
325  case TLS_TYPE_FINISHED:
326  //A Finished message is always sent immediately after a ChangeCipherSpec
327  //message to verify that the key exchange and authentication processes
328  //were successful
329  error = tlsParseFinished(context, message, length);
330  break;
331 
332 #if (TLS_MAX_VERSION >= SSL_VERSION_3_0 && TLS_MIN_VERSION <= TLS_VERSION_1_2)
333  //ClientKeyExchange message received?
335  //This message must immediately follow the client certificate message, if
336  //it is sent. Otherwise, it must be the first message sent by the client
337  //after it receives the ServerHelloDone message
338  error = tlsParseClientKeyExchange(context, message, length);
339  break;
340 #endif
341 
342 #if (TLS_MAX_VERSION >= TLS_VERSION_1_3 && TLS_MIN_VERSION <= TLS_VERSION_1_3)
343  //KeyUpdate message received?
344  case TLS_TYPE_KEY_UPDATE:
345  //The KeyUpdate handshake message is used to indicate that the client is
346  //updating its sending cryptographic keys. This message can be sent by
347  //the client after it has sent a Finished message
348  error = tls13ParseKeyUpdate(context, message, length);
349  break;
350 #endif
351 
352  //Invalid handshake message received?
353  default:
354  //Report an error
355  error = ERROR_UNEXPECTED_MESSAGE;
356  break;
357  }
358 
359  //Return status code
360  return error;
361 }
362 
363 #endif
TLS helper functions.
uint8_t length
Definition: dtls_misc.h:149
error_t tlsSaveToCache(TlsContext *context)
Save current session in cache.
Definition: tls_cache.c:164
error_t tls13GenerateHandshakeTrafficKeys(TlsContext *context)
TLS state machine (TLS server)
Handshake message processing (TLS 1.3 server)
error_t tlsSendChangeCipherSpec(TlsContext *context)
Send ChangeCipherSpec message.
Definition: tls_common.c:268
TLS handshake.
error_t tlsSendCertificate(TlsContext *context)
Send Certificate message.
Definition: tls_common.c:62
error_t tlsSendCertificateRequest(TlsContext *context)
Send CertificateRequest message.
Definition: tls_server.c:262
error_t tls13SendEncryptedExtensions(TlsContext *context)
error_t tlsPerformServerHandshake(TlsContext *context)
TLS server handshake.
Session cache management.
Handshake message processing (TLS 1.3 client and server)
error_t tlsReceiveHandshakeMessage(TlsContext *context)
Receive peer's message.
error_t tlsParseClientHello(TlsContext *context, const TlsClientHello *message, size_t length)
Parse ClientHello message.
Definition: tls_server.c:1177
error_t tlsSendServerHelloDone(TlsContext *context)
Send ServerHelloDone message.
Definition: tls_server.c:339
error_t tlsParseClientKeyExchange(TlsContext *context, const TlsClientKeyExchange *message, size_t length)
Parse ClientKeyExchange message.
Definition: tls_server.c:1617
error_t tls13GenerateClientAppTrafficKeys(TlsContext *context)
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
error_t tls13SendNewSessionTicket(TlsContext *context)
error_t tls13SendKeyUpdate(TlsContext *context)
error_t tlsSendServerKeyExchange(TlsContext *context)
Send ServerKeyExchange message.
Definition: tls_server.c:179
#define TLS_VERSION_1_2
Definition: tls.h:94
Handshake message processing (TLS client and server)
TLS record protocol.
error_t tls13GenerateServerAppTrafficKeys(TlsContext *context)
error_t tlsParseCertificate(TlsContext *context, const TlsCertificate *message, size_t length)
Parse Certificate message.
Definition: tls_common.c:1231
#define TRACE_WARNING(...)
Definition: debug.h:84
error_t tlsParseFinished(TlsContext *context, const TlsFinished *message, size_t length)
Parse Finished message.
Definition: tls_common.c:1656
Handshake message processing (TLS server)
error_t tlsWriteProtocolData(TlsContext *context, const uint8_t *data, size_t length, TlsContentType contentType)
Write protocol data.
Definition: tls_record.c:55
uint8_t msgType
Definition: dtls_misc.h:186
uint8_t message[]
Definition: chap.h:152
error_t tlsSendFinished(TlsContext *context)
Send Finished message.
Definition: tls_common.c:383
TLS (Transport Layer Security)
error_t tlsParseCertificateVerify(TlsContext *context, const TlsCertificateVerify *message, size_t length)
Parse CertificateVerify message.
Definition: tls_common.c:1432
error_t dtlsSendHelloVerifyRequest(TlsContext *context)
Send HelloVerifyRequest message.
Definition: dtls_misc.c:241
TLS 1.3 key schedule.
void tlsProcessError(TlsContext *context, error_t errorCode)
Translate an error code to an alert message.
Definition: tls_misc.c:56
error_t tlsParseClientHandshakeMessage(TlsContext *context, uint8_t msgType, const void *message, size_t length)
Parse client's handshake message.
error_t tls13ParseKeyUpdate(TlsContext *context, const Tls13KeyUpdate *message, size_t length)
Success.
Definition: error.h:44
Debugging facilities.
error_t tlsSendCertificateVerify(TlsContext *context)
Send CertificateVerify message.
Definition: tls_common.c:192
error_t tls13SendHelloRetryRequest(TlsContext *context)
error_t tlsSendServerHello(TlsContext *context)
Send ServerHello message.
Definition: tls_server.c:83
error_t tlsInitHandshake(TlsContext *context)
TLS handshake initialization.
Definition: tls_handshake.c:56