1 /**************************************************************************/
2 /* */
3 /* Copyright (c) Microsoft Corporation. All rights reserved. */
4 /* */
5 /* This software is licensed under the Microsoft Software License */
6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */
7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */
8 /* and in the root directory of this software. */
9 /* */
10 /**************************************************************************/
11
12
13 /**************************************************************************/
14 /**************************************************************************/
15 /** */
16 /** NetX Secure Component */
17 /** */
18 /** Transport Layer Security (TLS) */
19 /** */
20 /**************************************************************************/
21 /**************************************************************************/
22
23 #define NX_SECURE_SOURCE_CODE
24
25 #include "nx_secure_tls.h"
26
27 /**************************************************************************/
28 /* */
29 /* FUNCTION RELEASE */
30 /* */
31 /* _nx_secure_tls_map_error_to_alert PORTABLE C */
32 /* 6.1.12 */
33 /* AUTHOR */
34 /* */
35 /* Timothy Stapko, Microsoft Corporation */
36 /* */
37 /* DESCRIPTION */
38 /* */
39 /* This function maps an internal error status to the appropriate TLS */
40 /* alert number to be sent to the remote host. */
41 /* */
42 /* INPUT */
43 /* */
44 /* error_number The error we are mapping */
45 /* alert_number Return the alert number */
46 /* alert_level Return the alert level */
47 /* */
48 /* OUTPUT */
49 /* */
50 /* None */
51 /* */
52 /* CALLS */
53 /* */
54 /* None */
55 /* */
56 /* CALLED BY */
57 /* */
58 /* _nx_secure_dtls_session_receive Receive DTLS data */
59 /* _nx_secure_tls_session_receive_records */
60 /* Receive TLS records */
61 /* */
62 /* RELEASE HISTORY */
63 /* */
64 /* DATE NAME DESCRIPTION */
65 /* */
66 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */
67 /* 09-30-2020 Timothy Stapko Modified comment(s), */
68 /* fixed renegotiation bug, */
69 /* resulting in version 6.1 */
70 /* 04-02-2021 Timothy Stapko Modified comment(s), */
71 /* updated X.509 return value, */
72 /* resulting in version 6.1.6 */
73 /* 07-29-2022 Yuxin Zhou Modified comment(s), and */
74 /* updated alert message for */
75 /* downgrade protection, */
76 /* resulting in version 6.1.12 */
77 /* */
78 /**************************************************************************/
_nx_secure_tls_map_error_to_alert(UINT error_number,UINT * alert_number,UINT * alert_level)79 VOID _nx_secure_tls_map_error_to_alert(UINT error_number, UINT *alert_number, UINT *alert_level)
80 {
81 /* The following alerts are not currently sent by NetX Secure:
82 NX_SECURE_TLS_ALERT_EXPORT_RESTRICTION_RESERVED // MUST NOT be sent per RFC
83 NX_SECURE_TLS_ALERT_INSUFFICIENT_SECURITY // May be used if unsupported ciphersuites aren't strong enough (more specific than unsupported ciphers)
84 NX_SECURE_TLS_ALERT_USER_CANCELED // Only used if the application chooses to abort the connection during the handshake
85 NX_SECURE_TLS_ALERT_ACCESS_DENIED // Only used in systems with access control
86 NX_SECURE_TLS_ALERT_DECRYPTION_FAILED_RESERVED // MUST NOT be sent per RFC
87 NX_SECURE_TLS_ALERT_DECOMPRESSION_FAILURE // No compression methods are used currently
88 NX_SECURE_TLS_ALERT_NO_CERTIFICATE_RESERVED // MUST NOT be sent per RFC
89 NX_SECURE_TLS_ALERT_UNSUPPORTED_EXTENSION // We ignore extensions currently
90 */
91
92 switch (error_number)
93 {
94 /* Unexpected message alerts. */
95 case NX_SECURE_TLS_UNRECOGNIZED_MESSAGE_TYPE:
96 case NX_SECURE_TLS_ALERT_RECEIVED:
97 case NX_SECURE_TLS_UNEXPECTED_CLIENTHELLO:
98 case NX_SECURE_TLS_BAD_CIPHERSPEC:
99 case NX_SECURE_TLS_UNEXPECTED_MESSAGE: /* Deliberate fall-through. */
100 *alert_number = NX_SECURE_TLS_ALERT_UNEXPECTED_MESSAGE;
101 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
102 break;
103
104 /* Hash or decryption failures. */
105 case NX_SECURE_TLS_HASH_MAC_VERIFY_FAILURE:
106 case NX_SECURE_TLS_AEAD_DECRYPT_FAIL:
107 case NX_SECURE_TLS_PADDING_CHECK_FAILED: /* Deliberate fall-through. */
108 *alert_number = NX_SECURE_TLS_ALERT_BAD_RECORD_MAC;
109 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
110 break;
111
112 /* General handshake failures. */
113 case NX_SECURE_TLS_UNKNOWN_CIPHERSUITE:
114 case NX_SECURE_TLS_UNSUPPORTED_CIPHER:
115 case NX_SECURE_TLS_HANDSHAKE_FAILURE:
116 case NX_SECURE_TLS_NO_SUPPORTED_CIPHERS:
117 case NX_SECURE_TLS_UNSUPPORTED_FEATURE:
118 case NX_SECURE_TLS_UNSUPPORTED_ECC_CURVE:
119 case NX_SECURE_TLS_UNSUPPORTED_ECC_FORMAT:
120 case NX_SECURE_TLS_EXTENSION_NOT_FOUND:
121 case NX_SECURE_TLS_SNI_EXTENSION_INVALID:
122 case NX_SECURE_TLS_EMPTY_EC_GROUP:
123 case NX_SECURE_TLS_EMPTY_EC_POINT_FORMAT:
124 case NX_SECURE_TLS_UNSUPPORTED_SIGNATURE_ALGORITHM:
125 case NX_SECURE_TLS_RENEGOTIATION_SESSION_INACTIVE:
126 case NX_SECURE_TLS_RENEGOTIATION_EXTENSION_ERROR: /* Deliberate fall-through. */
127 *alert_number = NX_SECURE_TLS_ALERT_HANDSHAKE_FAILURE;
128 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
129 break;
130
131 /* Invalid certificate issues. */
132 case NX_SECURE_TLS_INVALID_SERVER_CERT:
133 case NX_SECURE_TLS_INVALID_CERTIFICATE:
134 case NX_SECURE_TLS_CERTIFICATE_SIG_CHECK_FAILED:
135 case NX_SECURE_TLS_CERTIFICATE_NOT_FOUND:
136 case NX_SECURE_TLS_CERTIFICATE_VERIFY_FAILURE:
137 case NX_SECURE_TLS_EMPTY_REMOTE_CERTIFICATE_RECEIVED:
138 case NX_SECURE_X509_WRONG_SIGNATURE_METHOD:
139 case NX_SECURE_X509_INVALID_DATE_FORMAT:
140 case NX_SECURE_X509_ASN1_LENGTH_TOO_LONG:
141 case NX_SECURE_X509_CERTIFICATE_NOT_FOUND:
142 case NX_SECURE_X509_PKCS7_PARSING_FAILED: /* Deliberate fall-through. */
143 *alert_number = NX_SECURE_TLS_ALERT_BAD_CERTIFICATE;
144 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
145 break;
146
147 /* Unsupported certificate issues (unsupported ciphers and signature types). */
148 case NX_SECURE_TLS_UNSUPPORTED_PUBLIC_CIPHER:
149 case NX_SECURE_TLS_UNSUPPORTED_CERT_SIGN_TYPE:
150 case NX_SECURE_TLS_UNSUPPORTED_CERT_SIGN_ALG: /* Deliberate fall-through. */
151 *alert_number = NX_SECURE_TLS_ALERT_UNSUPPORTED_CERTIFICATE;
152 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
153 break;
154
155 /* A certificate was revoked by its signer. */
156 case NX_SECURE_X509_CRL_CERTIFICATE_REVOKED:
157 *alert_number = NX_SECURE_TLS_ALERT_CERTIFICATE_REVOKED;
158 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
159 break;
160
161 /* A certificate has expired or is not yet valid. */
162 case NX_SECURE_X509_CERTIFICATE_EXPIRED:
163 case NX_SECURE_X509_CERTIFICATE_NOT_YET_VALID: /* Deliberate fall-through. */
164 *alert_number = NX_SECURE_TLS_ALERT_CERTIFICATE_EXPIRED;
165 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
166 break;
167
168 /* Unknown certificate issues - the certificate was unsupported but for some odd reason (or it was self-signed). */
169 case NX_SECURE_TLS_INVALID_SELF_SIGNED_CERT:
170 case NX_SECURE_TLS_UNKNOWN_CERT_SIG_ALGORITHM:
171 *alert_number = NX_SECURE_TLS_ALERT_CERTIFICATE_UNKNOWN;
172 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
173 break;
174
175 /* Illegal parameters - bad compression method, etc. */
176 case NX_SECURE_TLS_BAD_COMPRESSION_METHOD: /* Deliberate fall-through. */
177 case NX_SECURE_TLS_1_3_UNKNOWN_CIPHERSUITE:
178 case NX_SECURE_TLS_BAD_SERVERHELLO_KEYSHARE:
179 case NX_SECURE_TLS_DOWNGRADE_DETECTED:
180 *alert_number = NX_SECURE_TLS_ALERT_ILLEGAL_PARAMETER;
181 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
182 break;
183
184 /* The issuer for a received certificate was not found in our local store. */
185 case NX_SECURE_TLS_ISSUER_CERTIFICATE_NOT_FOUND:
186 case NX_SECURE_X509_CHAIN_VERIFY_FAILURE:
187 *alert_number = NX_SECURE_TLS_ALERT_UNKNOWN_CA;
188 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
189 break;
190
191 /* Some type of decoding error happened with a received message. */
192 case NX_SECURE_TLS_INCORRECT_MESSAGE_LENGTH:
193 *alert_number = NX_SECURE_TLS_ALERT_DECODE_ERROR;
194 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
195 break;
196
197 /* Decryption error in processing a message. */
198 case NX_SECURE_TLS_FINISHED_HASH_FAILURE:
199 case NX_SECURE_TLS_SIGNATURE_VERIFICATION_ERROR:
200 *alert_number = NX_SECURE_TLS_ALERT_DECRYPT_ERROR;
201 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
202 break;
203
204 /* We received a protocol version that we understand but that version is not supported/enabled. */
205 case NX_SECURE_TLS_PROTOCOL_VERSION_CHANGED:
206 case NX_SECURE_TLS_UNKNOWN_TLS_VERSION:
207 case NX_SECURE_TLS_UNSUPPORTED_TLS_VERSION:
208 *alert_number = NX_SECURE_TLS_ALERT_PROTOCOL_VERSION;
209 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
210 break;
211
212 /* Re-negotiation issues - the client may opt to decline a Hello Request message. */
213 case NX_SECURE_TLS_NO_RENEGOTIATION_ERROR:
214 case NX_SECURE_TLS_RENEGOTIATION_FAILURE:
215 *alert_number = NX_SECURE_TLS_ALERT_NO_RENEGOTIATION;
216 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_WARNING;
217 break;
218
219 /* Unknown PSK errors. */
220 case NX_SECURE_TLS_NO_MATCHING_PSK:
221 *alert_number = NX_SECURE_TLS_ALERT_UNKNOWN_PSK_IDENTITY;
222 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
223 break;
224
225 case NX_SECURE_TLS_INAPPROPRIATE_FALLBACK:
226 *alert_number = NX_SECURE_TLS_ALERT_INAPPROPRIATE_FALLBACK;
227 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
228 break;
229
230 /* Miss extension. */
231 case NX_SECURE_TLS_MISSING_EXTENSION:
232 *alert_number = NX_SECURE_TLS_ALERT_MISSING_EXTENSION;
233 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
234 break;
235
236 /* Require certificate. */
237 case NX_SECURE_TLS_CERTIFICATE_REQUIRED:
238 *alert_number = NX_SECURE_TLS_ALERT_CERTIFICATE_REQUIRED;
239 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
240 break;
241
242 /* Record overflow. */
243 case NX_SECURE_TLS_RECORD_OVERFLOW:
244 *alert_number = NX_SECURE_TLS_ALERT_RECORD_OVERFLOW;
245 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
246 break;
247
248 /* Internal errors. */
249
250 case NX_SECURE_TLS_ALLOCATE_PACKET_FAILED:
251 case NX_SECURE_TLS_SESSION_UNINITIALIZED:
252 case NX_SECURE_TLS_INVALID_STATE:
253 case NX_SECURE_TLS_INVALID_PACKET:
254 case NX_SECURE_TLS_NEED_DTLS_SESSION:
255 case NX_SECURE_TLS_NEED_TLS_SESSION:
256 case NX_SECURE_TLS_INSUFFICIENT_CERT_SPACE:
257 case NX_SECURE_TLS_TCP_SEND_FAILED:
258 case NX_SECURE_TLS_NO_CLOSE_RESPONSE:
259 case NX_SECURE_TLS_NO_MORE_PSK_SPACE:
260 case NX_SECURE_TLS_NO_CERT_SPACE_ALLOCATED:
261 case NX_SECURE_TLS_CLOSE_NOTIFY_RECEIVED:
262 case NX_SECURE_TLS_PACKET_BUFFER_TOO_SMALL:
263 case NX_SECURE_TLS_CERT_ID_INVALID:
264 case NX_SECURE_TLS_CRYPTO_KEYS_TOO_LARGE:
265 case NX_SECURE_TLS_CERT_ID_DUPLICATE: /* Deliberate fall-through. */
266
267 /* DTLS errors. */
268 case NX_SECURE_TLS_OUT_OF_ORDER_MESSAGE:
269 case NX_SECURE_TLS_INVALID_REMOTE_HOST:
270 case NX_SECURE_TLS_INVALID_EPOCH:
271 case NX_SECURE_TLS_REPEAT_MESSAGE_RECEIVED:
272 case NX_SECURE_TLS_SEND_ADDRESS_MISMATCH:
273 case NX_SECURE_TLS_NO_FREE_DTLS_SESSIONS:
274 case NX_SECURE_DTLS_SESSION_NOT_FOUND:
275 case NX_SECURE_TLS_NO_AVAILABLE_SESSIONS: /* Deliberate fall-through. */
276
277 case NX_SECURE_TLS_SUCCESS: /* We should not be mapping success to an error! */
278 default:
279 *alert_number = NX_SECURE_TLS_ALERT_INTERNAL_ERROR;
280 *alert_level = NX_SECURE_TLS_ALERT_LEVEL_FATAL;
281 break;
282 }
283 }
284
285
