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