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