Annotation of embedaddon/strongswan/src/libtls/tls.h, revision 1.1.1.2
1.1 misho 1: /*
1.1.1.2 ! misho 2: * Copyright (C) 2021 Tobias Brunner
! 3: * Copyright (C) 2020-2021 Pascal Knecht
! 4: * HSR Hochschule fuer Technik Rapperswil
! 5: *
1.1 misho 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;
1.1.1.2 ! misho 43: typedef enum tls_flag_t tls_flag_t;
1.1 misho 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 {
1.1.1.2 ! misho 55: TLS_UNSPEC = 0,
1.1 misho 56: SSL_2_0 = 0x0200,
57: SSL_3_0 = 0x0300,
58: TLS_1_0 = 0x0301,
1.1.1.2 ! misho 59: TLS_SUPPORTED_MIN = TLS_1_0,
1.1 misho 60: TLS_1_1 = 0x0302,
61: TLS_1_2 = 0x0303,
1.1.1.2 ! misho 62: TLS_1_3 = 0x0304,
! 63: TLS_SUPPORTED_MAX = TLS_1_3,
1.1 misho 64: };
65:
66: /**
67: * Enum names for tls_version_t
68: */
69: extern enum_name_t *tls_version_names;
70:
71: /**
1.1.1.2 ! misho 72: * Simple, numeric enum names for tls_version_t (only supported versions)
! 73: */
! 74: extern enum_name_t *tls_numeric_version_names;
! 75:
! 76: /**
1.1 misho 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,
1.1.1.2 ! misho 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,
1.1 misho 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,
1.1.1.2 ! misho 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,
1.1 misho 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: /**
1.1.1.2 ! misho 139: * TLS Handshake extension types.
1.1 misho 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,
1.1.1.2 ! misho 154: /** list of supported groups, in legacy tls: elliptic curves */
! 155: TLS_EXT_SUPPORTED_GROUPS = 10,
1.1 misho 156: /** supported point formats */
157: TLS_EXT_EC_POINT_FORMATS = 11,
158: /** list supported signature algorithms */
159: TLS_EXT_SIGNATURE_ALGORITHMS = 13,
1.1.1.2 ! misho 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,
1.1 misho 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: /**
1.1.1.2 ! misho 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: /**
1.1 misho 215: * Enum names for tls_extension_t
216: */
217: extern enum_name_t *tls_extension_names;
218:
219: /**
1.1.1.2 ! misho 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: /**
1.1 misho 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: /**
1.1.1.2 ! misho 299: * Get the maximum and negotiated TLS version.
1.1 misho 300: *
1.1.1.2 ! misho 301: * @return max and negotiated TLS version
1.1 misho 302: */
1.1.1.2 ! misho 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);
1.1 misho 311:
312: /**
1.1.1.2 ! misho 313: * Set the initial minimum/maximum TLS version, or set both to the same
! 314: * value once negotiated.
1.1 misho 315: *
1.1.1.2 ! misho 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
1.1 misho 319: */
1.1.1.2 ! misho 320: bool (*set_version)(tls_t *this, tls_version_t min_version,
! 321: tls_version_t max_version);
1.1 misho 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: /**
1.1.1.2 ! misho 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: /**
1.1 misho 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
1.1.1.2 ! misho 378: * @param flags flags that control the behavior of the TLS stack
1.1 misho 379: * @return TLS stack
380: */
381: tls_t *tls_create(bool is_server, identification_t *server,
382: identification_t *peer, tls_purpose_t purpose,
1.1.1.2 ! misho 383: tls_application_t *application, tls_cache_t *cache,
! 384: tls_flag_t flags);
1.1 misho 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