Annotation of embedaddon/strongswan/src/libtls/tls.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (C) 2010 Martin Willi
3: * Copyright (C) 2010 revosec AG
4: *
5: * This program is free software; you can redistribute it and/or modify it
6: * under the terms of the GNU General Public License as published by the
7: * Free Software Foundation; either version 2 of the License, or (at your
8: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9: *
10: * This program is distributed in the hope that it will be useful, but
11: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13: * for more details.
14: */
15:
16: /**
17: * @defgroup libtls libtls
18: *
19: * @addtogroup libtls
20: * TLS implementation on top of libstrongswan
21: *
22: * @defgroup tls tls
23: * @{ @ingroup libtls
24: */
25:
26: #ifndef TLS_H_
27: #define TLS_H_
28:
29: /**
30: * Maximum size of a TLS fragment
31: * as defined by section 6.2.1. "Fragmentation" of RFC 5246 TLS 1.2
32: */
33: #define TLS_MAX_FRAGMENT_LEN 16384
34:
35: typedef enum tls_version_t tls_version_t;
36: typedef enum tls_content_type_t tls_content_type_t;
37: typedef enum tls_handshake_type_t tls_handshake_type_t;
38: typedef enum tls_purpose_t tls_purpose_t;
39: typedef struct tls_t tls_t;
40:
41: #include <library.h>
42:
43: #include "tls_application.h"
44: #include "tls_cache.h"
45:
46: /**
47: * TLS/SSL version numbers
48: */
49: enum tls_version_t {
50: SSL_2_0 = 0x0200,
51: SSL_3_0 = 0x0300,
52: TLS_1_0 = 0x0301,
53: TLS_1_1 = 0x0302,
54: TLS_1_2 = 0x0303,
55: };
56:
57: /**
58: * Enum names for tls_version_t
59: */
60: extern enum_name_t *tls_version_names;
61:
62: /**
63: * TLS higher level content type
64: */
65: enum tls_content_type_t {
66: TLS_CHANGE_CIPHER_SPEC = 20,
67: TLS_ALERT = 21,
68: TLS_HANDSHAKE = 22,
69: TLS_APPLICATION_DATA = 23,
70: };
71:
72: /**
73: * Enum names for tls_content_type_t
74: */
75: extern enum_name_t *tls_content_type_names;
76:
77: /**
78: * TLS handshake subtype
79: */
80: enum tls_handshake_type_t {
81: TLS_HELLO_REQUEST = 0,
82: TLS_CLIENT_HELLO = 1,
83: TLS_SERVER_HELLO = 2,
84: TLS_CERTIFICATE = 11,
85: TLS_SERVER_KEY_EXCHANGE = 12,
86: TLS_CERTIFICATE_REQUEST = 13,
87: TLS_SERVER_HELLO_DONE = 14,
88: TLS_CERTIFICATE_VERIFY = 15,
89: TLS_CLIENT_KEY_EXCHANGE = 16,
90: TLS_FINISHED = 20,
91: };
92:
93: /**
94: * Enum names for tls_handshake_type_t
95: */
96: extern enum_name_t *tls_handshake_type_names;
97:
98: /**
99: * Purpose the TLS stack is initiated for.
100: */
101: enum tls_purpose_t {
102: /** authentication in EAP-TLS */
103: TLS_PURPOSE_EAP_TLS,
104: /** outer authentication and protection in EAP-TTLS */
105: TLS_PURPOSE_EAP_TTLS,
106: /** outer authentication and protection in EAP-PEAP */
107: TLS_PURPOSE_EAP_PEAP,
108: /** non-EAP TLS */
109: TLS_PURPOSE_GENERIC,
110: /** non-EAP TLS accepting NULL encryption */
111: TLS_PURPOSE_GENERIC_NULLOK,
112: /** EAP binding for TNC */
113: TLS_PURPOSE_EAP_TNC
114: };
115:
116: /**
117: * TLS Hello extension types.
118: */
119: enum tls_extension_t {
120: /** Server name the client wants to talk to */
121: TLS_EXT_SERVER_NAME = 0,
122: /** request a maximum fragment size */
123: TLS_EXT_MAX_FRAGMENT_LENGTH = 1,
124: /** indicate client certificate URL support */
125: TLS_EXT_CLIENT_CERTIFICATE_URL = 2,
126: /** list of CA the client trusts */
127: TLS_EXT_TRUSTED_CA_KEYS = 3,
128: /** request MAC truncation to 80-bit */
129: TLS_EXT_TRUNCATED_HMAC = 4,
130: /** list of OCSP responders the client trusts */
131: TLS_EXT_STATUS_REQUEST = 5,
132: /** list of supported elliptic curves */
133: TLS_EXT_ELLIPTIC_CURVES = 10,
134: /** supported point formats */
135: TLS_EXT_EC_POINT_FORMATS = 11,
136: /** list supported signature algorithms */
137: TLS_EXT_SIGNATURE_ALGORITHMS = 13,
138: /** cryptographic binding for RFC 5746 renegotiation indication */
139: TLS_EXT_RENEGOTIATION_INFO = 65281,
140: };
141:
142: enum tls_name_type_t {
143: TLS_NAME_TYPE_HOST_NAME = 0,
144: };
145:
146: /**
147: * Enum names for tls_extension_t
148: */
149: extern enum_name_t *tls_extension_names;
150:
151: /**
152: * A bottom-up driven TLS stack, suitable for EAP implementations.
153: */
154: struct tls_t {
155:
156: /**
157: * Process one or more TLS records, pass it to upper layers.
158: *
159: * @param buf TLS record data, including headers
160: * @param buflen number of bytes in buf to process
161: * @return
162: * - SUCCESS if TLS negotiation complete
163: * - FAILED if TLS handshake failed
164: * - NEED_MORE if more invocations to process/build needed
165: */
166: status_t (*process)(tls_t *this, void *buf, size_t buflen);
167:
168: /**
169: * Query upper layer for one or more TLS records, build fragments.
170: *
171: * The TLS stack automatically fragments the records to the given buffer
172: * size. Fragmentation is indicated by the reclen output parameter and
173: * the return value. For the first fragment of a TLS record, a non-zero
174: * record length is returned in reclen. If more fragments follow, NEED_MORE
175: * is returned. A return value of ALREADY_DONE indicates that the final
176: * fragment has been returned.
177: *
178: * @param buf buffer to write TLS record fragments to
179: * @param buflen size of buffer, receives bytes written
180: * @param msglen receives size of all TLS fragments
181: * @return
182: * - SUCCESS if TLS negotiation complete
183: * - FAILED if TLS handshake failed
184: * - INVALID_STATE if more input data required
185: * - NEED_MORE if more fragments available
186: * - ALREADY_DONE if the last available fragment returned
187: */
188: status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen);
189:
190: /**
191: * Check if TLS stack is acting as a server.
192: *
193: * @return TRUE if server, FALSE if peer
194: */
195: bool (*is_server)(tls_t *this);
196:
197: /**
198: * Return the server identity.
199: *
200: * @return server identity
201: */
202: identification_t* (*get_server_id)(tls_t *this);
203:
204: /**
205: * Set the peer identity.
206: *
207: * @param id peer identity
208: */
209: void (*set_peer_id)(tls_t *this, identification_t *id);
210:
211: /**
212: * Return the peer identity.
213: *
214: * @return peer identity
215: */
216: identification_t* (*get_peer_id)(tls_t *this);
217:
218: /**
219: * Get the negotiated TLS/SSL version.
220: *
221: * @return negotiated TLS version
222: */
223: tls_version_t (*get_version)(tls_t *this);
224:
225: /**
226: * Set the negotiated TLS/SSL version.
227: *
228: * @param version negotiated TLS version
229: * @return TRUE if version acceptable
230: */
231: bool (*set_version)(tls_t *this, tls_version_t version);
232:
233: /**
234: * Get the purpose of this TLS stack instance.
235: *
236: * @return purpose given during construction
237: */
238: tls_purpose_t (*get_purpose)(tls_t *this);
239:
240: /**
241: * Check if TLS negotiation completed successfully.
242: *
243: * @return TRUE if TLS negotiation and authentication complete
244: */
245: bool (*is_complete)(tls_t *this);
246:
247: /**
248: * Get the MSK for EAP-TLS.
249: *
250: * @return MSK, internal data
251: */
252: chunk_t (*get_eap_msk)(tls_t *this);
253:
254: /**
255: * Get the authentication details after completing the handshake.
256: *
257: * @return authentication details, internal data
258: */
259: auth_cfg_t* (*get_auth)(tls_t *this);
260:
261: /**
262: * Destroy a tls_t.
263: */
264: void (*destroy)(tls_t *this);
265: };
266:
267: /**
268: * Dummy libtls initialization function needed for integrity test
269: */
270: void libtls_init(void);
271:
272: /**
273: * Create a tls instance.
274: *
275: * @param is_server TRUE to act as server, FALSE for client
276: * @param server server identity
277: * @param peer peer identity, NULL for no client authentication
278: * @param purpose purpose this TLS stack instance is used for
279: * @param application higher layer application or NULL if none
280: * @param cache session cache to use, or NULL
281: * @return TLS stack
282: */
283: tls_t *tls_create(bool is_server, identification_t *server,
284: identification_t *peer, tls_purpose_t purpose,
285: tls_application_t *application, tls_cache_t *cache);
286:
287: #endif /** TLS_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>