]>
Commit | Line | Data |
---|---|---|
f7f63c52 MW |
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 | /** | |
0f82a470 MW |
17 | * @defgroup libtls libtls |
18 | * | |
19 | * @addtogroup libtls | |
20 | * TLS implementation on top of libstrongswan | |
f7f63c52 MW |
21 | * |
22 | * @defgroup tls tls | |
0f82a470 | 23 | * @{ @ingroup libtls |
f7f63c52 MW |
24 | */ |
25 | ||
26 | #ifndef TLS_H_ | |
27 | #define TLS_H_ | |
28 | ||
c3668096 AS |
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 | ||
f7f63c52 MW |
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; | |
96b2fbcc | 38 | typedef enum tls_purpose_t tls_purpose_t; |
dcbbeb2d | 39 | typedef struct tls_t tls_t; |
f7f63c52 MW |
40 | |
41 | #include <library.h> | |
42 | ||
1327839d | 43 | #include "tls_application.h" |
6a5c86b7 | 44 | #include "tls_cache.h" |
1327839d | 45 | |
f7f63c52 MW |
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 | ||
96b2fbcc MW |
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, | |
1bee89d3 AS |
106 | /** outer authentication and protection in EAP-PEAP */ |
107 | TLS_PURPOSE_EAP_PEAP, | |
69e8bb2e | 108 | /** non-EAP TLS */ |
bda7d9d9 | 109 | TLS_PURPOSE_GENERIC, |
ddf52220 MW |
110 | /** non-EAP TLS accepting NULL encryption */ |
111 | TLS_PURPOSE_GENERIC_NULLOK, | |
d2b1d437 AS |
112 | /** EAP binding for TNC */ |
113 | TLS_PURPOSE_EAP_TNC | |
96b2fbcc MW |
114 | }; |
115 | ||
731611c5 MW |
116 | /** |
117 | * TLS Hello extension types. | |
118 | */ | |
119 | enum tls_extension_t { | |
6cf85b35 MW |
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 */ | |
37a59a8f MW |
133 | TLS_EXT_ELLIPTIC_CURVES = 10, |
134 | /** supported point formats */ | |
135 | TLS_EXT_EC_POINT_FORMATS = 11, | |
6cf85b35 | 136 | /** list supported signature algorithms */ |
731611c5 | 137 | TLS_EXT_SIGNATURE_ALGORITHMS = 13, |
a9ee43e9 AS |
138 | /** cryptographic binding for RFC 5746 renegotiation indication */ |
139 | TLS_EXT_RENEGOTIATION_INFO = 65281, | |
731611c5 MW |
140 | }; |
141 | ||
1c21f47a MW |
142 | enum tls_name_type_t { |
143 | TLS_NAME_TYPE_HOST_NAME = 0, | |
144 | }; | |
145 | ||
731611c5 MW |
146 | /** |
147 | * Enum names for tls_extension_t | |
148 | */ | |
149 | extern enum_name_t *tls_extension_names; | |
150 | ||
dcbbeb2d MW |
151 | /** |
152 | * A bottom-up driven TLS stack, suitable for EAP implementations. | |
153 | */ | |
154 | struct tls_t { | |
155 | ||
156 | /** | |
14758000 | 157 | * Process one or more TLS records, pass it to upper layers. |
dcbbeb2d | 158 | * |
ecd98efa MW |
159 | * @param buf TLS record data, including headers |
160 | * @param buflen number of bytes in buf to process | |
dcbbeb2d MW |
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 | */ | |
ecd98efa | 166 | status_t (*process)(tls_t *this, void *buf, size_t buflen); |
dcbbeb2d MW |
167 | |
168 | /** | |
ecd98efa | 169 | * Query upper layer for one or more TLS records, build fragments. |
dcbbeb2d | 170 | * |
ecd98efa MW |
171 | * The TLS stack automatically fragments the records to the given buffer |
172 | * size. Fragmentation is indicated by the reclen ouput 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 | |
dcbbeb2d MW |
181 | * @return |
182 | * - SUCCESS if TLS negotiation complete | |
183 | * - FAILED if TLS handshake failed | |
ecd98efa MW |
184 | * - INVALID_STATE if more input data required |
185 | * - NEED_MORE if more fragments available | |
186 | * - ALREADY_DONE if the last available fragment returned | |
dcbbeb2d | 187 | */ |
ecd98efa | 188 | status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen); |
dcbbeb2d | 189 | |
84543e6e MW |
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 | ||
bd1ee5bd | 197 | /** |
2de481e3 | 198 | * Return the server identity. |
bd1ee5bd | 199 | * |
2de481e3 | 200 | * @return server identity |
bd1ee5bd AS |
201 | */ |
202 | identification_t* (*get_server_id)(tls_t *this); | |
203 | ||
97b1d39d AS |
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 | ||
bd1ee5bd | 211 | /** |
2de481e3 | 212 | * Return the peer identity. |
bd1ee5bd | 213 | * |
2de481e3 | 214 | * @return peer identity |
bd1ee5bd AS |
215 | */ |
216 | identification_t* (*get_peer_id)(tls_t *this); | |
217 | ||
3e962b08 MW |
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 | |
f154e304 | 229 | * @return TRUE if version acceptable |
3e962b08 | 230 | */ |
f154e304 | 231 | bool (*set_version)(tls_t *this, tls_version_t version); |
3e962b08 | 232 | |
96b2fbcc MW |
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 | ||
400df4ca MW |
240 | /** |
241 | * Check if TLS negotiation completed successfully. | |
242 | * | |
84545f6e | 243 | * @return TRUE if TLS negotiation and authentication complete |
400df4ca MW |
244 | */ |
245 | bool (*is_complete)(tls_t *this); | |
246 | ||
51313a39 MW |
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 | ||
dcbbeb2d MW |
254 | /** |
255 | * Destroy a tls_t. | |
256 | */ | |
257 | void (*destroy)(tls_t *this); | |
258 | }; | |
259 | ||
e7cb8f9b AS |
260 | /** |
261 | * Dummy libtls initialization function needed for integrity test | |
262 | */ | |
263 | void libtls_init(void); | |
264 | ||
dcbbeb2d MW |
265 | /** |
266 | * Create a tls instance. | |
267 | * | |
b51ac45c AS |
268 | * @param is_server TRUE to act as server, FALSE for client |
269 | * @param server server identity | |
69e8bb2e | 270 | * @param peer peer identity, NULL for no client authentication |
0433b417 | 271 | * @param purpose purpose this TLS stack instance is used for |
b51ac45c | 272 | * @param application higher layer application or NULL if none |
6a5c86b7 | 273 | * @param cache session cache to use, or NULL |
b51ac45c | 274 | * @return TLS stack |
dcbbeb2d | 275 | */ |
3ddd164e | 276 | tls_t *tls_create(bool is_server, identification_t *server, |
96b2fbcc | 277 | identification_t *peer, tls_purpose_t purpose, |
6a5c86b7 | 278 | tls_application_t *application, tls_cache_t *cache); |
dcbbeb2d | 279 | |
f7f63c52 | 280 | #endif /** TLS_H_ @}*/ |