libtls: Add downgrade protection for TLS 1.3 and TLS 1.2
[strongswan.git] / src / libtls / tls.h
1 /*
2 * Copyright (C) 2021 Tobias Brunner
3 * Copyright (C) 2020-2021 Pascal Knecht
4 * HSR Hochschule fuer Technik Rapperswil
5 *
6 * Copyright (C) 2010 Martin Willi
7 * Copyright (C) 2010 revosec AG
8 *
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU General Public License as published by the
11 * Free Software Foundation; either version 2 of the License, or (at your
12 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
13 *
14 * This program is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 * for more details.
18 */
19
20 /**
21 * @defgroup libtls libtls
22 *
23 * @addtogroup libtls
24 * TLS implementation on top of libstrongswan
25 *
26 * @defgroup tls tls
27 * @{ @ingroup libtls
28 */
29
30 #ifndef TLS_H_
31 #define TLS_H_
32
33 /**
34 * Maximum size of a TLS fragment
35 * as defined by section 6.2.1. "Fragmentation" of RFC 5246 TLS 1.2
36 */
37 #define TLS_MAX_FRAGMENT_LEN 16384
38
39 typedef enum tls_version_t tls_version_t;
40 typedef enum tls_content_type_t tls_content_type_t;
41 typedef enum tls_handshake_type_t tls_handshake_type_t;
42 typedef enum tls_purpose_t tls_purpose_t;
43 typedef struct tls_t tls_t;
44
45 #include <library.h>
46
47 #include "tls_application.h"
48 #include "tls_cache.h"
49
50 /**
51 * TLS/SSL version numbers
52 */
53 enum tls_version_t {
54 TLS_UNSPEC = 0,
55 SSL_2_0 = 0x0200,
56 SSL_3_0 = 0x0300,
57 TLS_1_0 = 0x0301,
58 TLS_SUPPORTED_MIN = TLS_1_0,
59 TLS_1_1 = 0x0302,
60 TLS_1_2 = 0x0303,
61 TLS_1_3 = 0x0304,
62 TLS_SUPPORTED_MAX = TLS_1_3,
63 };
64
65 /**
66 * Enum names for tls_version_t
67 */
68 extern enum_name_t *tls_version_names;
69
70 /**
71 * Simple, numeric enum names for tls_version_t (only supported versions)
72 */
73 extern enum_name_t *tls_numeric_version_names;
74
75 /**
76 * TLS higher level content type
77 */
78 enum tls_content_type_t {
79 TLS_CHANGE_CIPHER_SPEC = 20,
80 TLS_ALERT = 21,
81 TLS_HANDSHAKE = 22,
82 TLS_APPLICATION_DATA = 23,
83 };
84
85 /**
86 * Enum names for tls_content_type_t
87 */
88 extern enum_name_t *tls_content_type_names;
89
90 /**
91 * TLS handshake subtype
92 */
93 enum tls_handshake_type_t {
94 TLS_HELLO_REQUEST = 0,
95 TLS_CLIENT_HELLO = 1,
96 TLS_SERVER_HELLO = 2,
97 TLS_HELLO_VERIFY_REQUEST = 3,
98 TLS_NEW_SESSION_TICKET = 4,
99 TLS_END_OF_EARLY_DATA = 5,
100 TLS_HELLO_RETRY_REQUEST = 6,
101 TLS_ENCRYPTED_EXTENSIONS = 8,
102 TLS_CERTIFICATE = 11,
103 TLS_SERVER_KEY_EXCHANGE = 12,
104 TLS_CERTIFICATE_REQUEST = 13,
105 TLS_SERVER_HELLO_DONE = 14,
106 TLS_CERTIFICATE_VERIFY = 15,
107 TLS_CLIENT_KEY_EXCHANGE = 16,
108 TLS_FINISHED = 20,
109 TLS_CERTIFICATE_URL = 21,
110 TLS_CERTIFICATE_STATUS = 22,
111 TLS_SUPPLEMENTAL_DATA = 23,
112 TLS_KEY_UPDATE = 24,
113 TLS_MESSAGE_HASH = 254,
114 };
115
116 /**
117 * Enum names for tls_handshake_type_t
118 */
119 extern enum_name_t *tls_handshake_type_names;
120
121 /**
122 * Purpose the TLS stack is initiated for.
123 */
124 enum tls_purpose_t {
125 /** authentication in EAP-TLS */
126 TLS_PURPOSE_EAP_TLS,
127 /** outer authentication and protection in EAP-TTLS */
128 TLS_PURPOSE_EAP_TTLS,
129 /** outer authentication and protection in EAP-PEAP */
130 TLS_PURPOSE_EAP_PEAP,
131 /** non-EAP TLS */
132 TLS_PURPOSE_GENERIC,
133 /** non-EAP TLS accepting NULL encryption */
134 TLS_PURPOSE_GENERIC_NULLOK,
135 /** EAP binding for TNC */
136 TLS_PURPOSE_EAP_TNC
137 };
138
139 /**
140 * TLS Handshake extension types.
141 */
142 enum tls_extension_t {
143 /** Server name the client wants to talk to */
144 TLS_EXT_SERVER_NAME = 0,
145 /** request a maximum fragment size */
146 TLS_EXT_MAX_FRAGMENT_LENGTH = 1,
147 /** indicate client certificate URL support */
148 TLS_EXT_CLIENT_CERTIFICATE_URL = 2,
149 /** list of CA the client trusts */
150 TLS_EXT_TRUSTED_CA_KEYS = 3,
151 /** request MAC truncation to 80-bit */
152 TLS_EXT_TRUNCATED_HMAC = 4,
153 /** list of OCSP responders the client trusts */
154 TLS_EXT_STATUS_REQUEST = 5,
155 /** list of supported groups, in legacy tls: elliptic curves */
156 TLS_EXT_SUPPORTED_GROUPS = 10,
157 /** supported point formats */
158 TLS_EXT_EC_POINT_FORMATS = 11,
159 /** list supported signature algorithms */
160 TLS_EXT_SIGNATURE_ALGORITHMS = 13,
161 /** indicate usage of Datagram Transport Layer Security (DTLS) */
162 TLS_EXT_USE_SRTP = 14,
163 /** indicate usage of heartbeat */
164 TLS_EXT_HEARTBEAT = 15,
165 /** indicate usage of application-layer protocol negotiation */
166 TLS_EXT_APPLICATION_LAYER_PROTOCOL_NEGOTIATION = 16,
167 /** exchange raw public key, client side*/
168 TLS_CLIENT_CERTIFICATE_TYPE = 19,
169 /** exchange raw public key, server side*/
170 TLS_SERVER_CERTIFICATE_TYPE = 20,
171 /** use encrypt-then-MAC security mechanism RFC 7366 */
172 TLS_EXT_ENCRYPT_THEN_MAC = 22,
173 /** bind master secret to handshake data RFC 7627 */
174 TLS_EXT_EXTENDED_MASTER_SECRET = 23,
175 /** session resumption without server-side state RFC 5077 */
176 TLS_EXT_SESSION_TICKET = 35,
177 /** negotiate identity of the psk **/
178 TLS_EXT_PRE_SHARED_KEY = 41,
179 /** send data in 0-RTT when psk is used and early data is allowed **/
180 TLS_EXT_EARLY_DATA = 42,
181 /** negotiate supported tls versions **/
182 TLS_EXT_SUPPORTED_VERSIONS = 43,
183 /** identify client **/
184 TLS_EXT_COOKIE = 44,
185 /** psk modes supported by the client **/
186 TLS_EXT_PSK_KEY_EXCHANGE_MODES = 45,
187 /** indicate supported ca's by endpoint **/
188 TLS_EXT_CERTIFICATE_AUTHORITIES = 47,
189 /** provide oid/value pairs to match client's certificate **/
190 TLS_EXT_OID_FILTERS = 48,
191 /** willing to perform post-handshake authentication **/
192 TLS_EXT_POST_HANDSHAKE_AUTH = 49,
193 /** list supported signature algorithms to verify certificates **/
194 TLS_EXT_SIGNATURE_ALGORITHMS_CERT = 50,
195 /** list endpoint's cryptographic parameters **/
196 TLS_EXT_KEY_SHARE = 51,
197 /** cryptographic binding for RFC 5746 renegotiation indication */
198 TLS_EXT_RENEGOTIATION_INFO = 65281,
199 };
200
201 enum tls_name_type_t {
202 TLS_NAME_TYPE_HOST_NAME = 0,
203 };
204
205 /**
206 * Enum names for tls_extension_t
207 */
208 extern enum_name_t *tls_extension_names;
209
210 /**
211 * Magic value (SHA-256 of "HelloRetryRequest") for Random to differentiate
212 * ServerHello from HelloRetryRequest.
213 */
214 extern chunk_t tls_hello_retry_request_magic;
215
216 /**
217 * Magic values for downgrade protection (see RFC 8446, section 4.1.3)
218 */
219 extern chunk_t tls_downgrade_protection_tls11;
220 extern chunk_t tls_downgrade_protection_tls12;
221
222 /**
223 * A bottom-up driven TLS stack, suitable for EAP implementations.
224 */
225 struct tls_t {
226
227 /**
228 * Process one or more TLS records, pass it to upper layers.
229 *
230 * @param buf TLS record data, including headers
231 * @param buflen number of bytes in buf to process
232 * @return
233 * - SUCCESS if TLS negotiation complete
234 * - FAILED if TLS handshake failed
235 * - NEED_MORE if more invocations to process/build needed
236 */
237 status_t (*process)(tls_t *this, void *buf, size_t buflen);
238
239 /**
240 * Query upper layer for one or more TLS records, build fragments.
241 *
242 * The TLS stack automatically fragments the records to the given buffer
243 * size. Fragmentation is indicated by the reclen output parameter and
244 * the return value. For the first fragment of a TLS record, a non-zero
245 * record length is returned in reclen. If more fragments follow, NEED_MORE
246 * is returned. A return value of ALREADY_DONE indicates that the final
247 * fragment has been returned.
248 *
249 * @param buf buffer to write TLS record fragments to
250 * @param buflen size of buffer, receives bytes written
251 * @param msglen receives size of all TLS fragments
252 * @return
253 * - SUCCESS if TLS negotiation complete
254 * - FAILED if TLS handshake failed
255 * - INVALID_STATE if more input data required
256 * - NEED_MORE if more fragments available
257 * - ALREADY_DONE if the last available fragment returned
258 */
259 status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen);
260
261 /**
262 * Check if TLS stack is acting as a server.
263 *
264 * @return TRUE if server, FALSE if peer
265 */
266 bool (*is_server)(tls_t *this);
267
268 /**
269 * Return the server identity.
270 *
271 * @return server identity
272 */
273 identification_t* (*get_server_id)(tls_t *this);
274
275 /**
276 * Set the peer identity.
277 *
278 * @param id peer identity
279 */
280 void (*set_peer_id)(tls_t *this, identification_t *id);
281
282 /**
283 * Return the peer identity.
284 *
285 * @return peer identity
286 */
287 identification_t* (*get_peer_id)(tls_t *this);
288
289 /**
290 * Get the maximum and negotiated TLS version.
291 *
292 * @return max and negotiated TLS version
293 */
294 tls_version_t (*get_version_max)(tls_t *this);
295
296 /**
297 * Get the minimum TLS version.
298 *
299 * @return min TLS version
300 */
301 tls_version_t (*get_version_min)(tls_t *this);
302
303 /**
304 * Set the initial minimum/maximum TLS version, or set both to the same
305 * value once negotiated.
306 *
307 * @param min_version minimum (or negotiated) TLS version
308 * @param max_version maximum (or negotiated) TLS version
309 * @return TRUE if version(s) acceptable
310 */
311 bool (*set_version)(tls_t *this, tls_version_t min_version,
312 tls_version_t max_version);
313
314 /**
315 * Get the purpose of this TLS stack instance.
316 *
317 * @return purpose given during construction
318 */
319 tls_purpose_t (*get_purpose)(tls_t *this);
320
321 /**
322 * Check if TLS negotiation completed successfully.
323 *
324 * @return TRUE if TLS negotiation and authentication complete
325 */
326 bool (*is_complete)(tls_t *this);
327
328 /**
329 * Get the MSK for EAP-TLS.
330 *
331 * @return MSK, internal data
332 */
333 chunk_t (*get_eap_msk)(tls_t *this);
334
335 /**
336 * Get the authentication details after completing the handshake.
337 *
338 * @return authentication details, internal data
339 */
340 auth_cfg_t* (*get_auth)(tls_t *this);
341
342 /**
343 * Destroy a tls_t.
344 */
345 void (*destroy)(tls_t *this);
346 };
347
348 /**
349 * Dummy libtls initialization function needed for integrity test
350 */
351 void libtls_init(void);
352
353 /**
354 * Create a tls instance.
355 *
356 * @param is_server TRUE to act as server, FALSE for client
357 * @param server server identity
358 * @param peer peer identity, NULL for no client authentication
359 * @param purpose purpose this TLS stack instance is used for
360 * @param application higher layer application or NULL if none
361 * @param cache session cache to use, or NULL
362 * @return TLS stack
363 */
364 tls_t *tls_create(bool is_server, identification_t *server,
365 identification_t *peer, tls_purpose_t purpose,
366 tls_application_t *application, tls_cache_t *cache);
367
368 #endif /** TLS_H_ @}*/