Some typos fixed.
[strongswan.git] / src / libtls / tls.h
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 typedef enum tls_version_t tls_version_t;
30 typedef enum tls_content_type_t tls_content_type_t;
31 typedef enum tls_handshake_type_t tls_handshake_type_t;
32 typedef enum tls_purpose_t tls_purpose_t;
33 typedef struct tls_t tls_t;
34
35 #include <library.h>
36
37 #include "tls_application.h"
38
39 /**
40 * TLS/SSL version numbers
41 */
42 enum tls_version_t {
43 SSL_2_0 = 0x0200,
44 SSL_3_0 = 0x0300,
45 TLS_1_0 = 0x0301,
46 TLS_1_1 = 0x0302,
47 TLS_1_2 = 0x0303,
48 };
49
50 /**
51 * Enum names for tls_version_t
52 */
53 extern enum_name_t *tls_version_names;
54
55 /**
56 * TLS higher level content type
57 */
58 enum tls_content_type_t {
59 TLS_CHANGE_CIPHER_SPEC = 20,
60 TLS_ALERT = 21,
61 TLS_HANDSHAKE = 22,
62 TLS_APPLICATION_DATA = 23,
63 };
64
65 /**
66 * Enum names for tls_content_type_t
67 */
68 extern enum_name_t *tls_content_type_names;
69
70 /**
71 * TLS handshake subtype
72 */
73 enum tls_handshake_type_t {
74 TLS_HELLO_REQUEST = 0,
75 TLS_CLIENT_HELLO = 1,
76 TLS_SERVER_HELLO = 2,
77 TLS_CERTIFICATE = 11,
78 TLS_SERVER_KEY_EXCHANGE = 12,
79 TLS_CERTIFICATE_REQUEST = 13,
80 TLS_SERVER_HELLO_DONE = 14,
81 TLS_CERTIFICATE_VERIFY = 15,
82 TLS_CLIENT_KEY_EXCHANGE = 16,
83 TLS_FINISHED = 20,
84 };
85
86 /**
87 * Enum names for tls_handshake_type_t
88 */
89 extern enum_name_t *tls_handshake_type_names;
90
91 /**
92 * Purpose the TLS stack is initiated for.
93 */
94 enum tls_purpose_t {
95 /** authentication in EAP-TLS */
96 TLS_PURPOSE_EAP_TLS,
97 /** outer authentication and protection in EAP-TTLS */
98 TLS_PURPOSE_EAP_TTLS,
99 /** non-EAP TLS */
100 TLS_PURPOSE_GENERIC,
101 /** EAP binding for TNC */
102 TLS_PURPOSE_EAP_TNC
103 };
104
105 /**
106 * TLS Hello extension types.
107 */
108 enum tls_extension_t {
109 /** Server name the client wants to talk to */
110 TLS_EXT_SERVER_NAME = 0,
111 /** request a maximum fragment size */
112 TLS_EXT_MAX_FRAGMENT_LENGTH = 1,
113 /** indicate client certificate URL support */
114 TLS_EXT_CLIENT_CERTIFICATE_URL = 2,
115 /** list of CA the client trusts */
116 TLS_EXT_TRUSTED_CA_KEYS = 3,
117 /** request MAC truncation to 80-bit */
118 TLS_EXT_TRUNCATED_HMAC = 4,
119 /** list of OCSP responders the client trusts */
120 TLS_EXT_STATUS_REQUEST = 5,
121 /** list of supported elliptic curves */
122 TLS_EXT_ELLIPTIC_CURVES = 10,
123 /** supported point formats */
124 TLS_EXT_EC_POINT_FORMATS = 11,
125 /** list supported signature algorithms */
126 TLS_EXT_SIGNATURE_ALGORITHMS = 13,
127 };
128
129 /**
130 * Enum names for tls_extension_t
131 */
132 extern enum_name_t *tls_extension_names;
133
134 /**
135 * A bottom-up driven TLS stack, suitable for EAP implementations.
136 */
137 struct tls_t {
138
139 /**
140 * Process one or more TLS records, pass it to upper layers.
141 *
142 * @param buf TLS record data, including headers
143 * @param buflen number of bytes in buf to process
144 * @return
145 * - SUCCESS if TLS negotiation complete
146 * - FAILED if TLS handshake failed
147 * - NEED_MORE if more invocations to process/build needed
148 */
149 status_t (*process)(tls_t *this, void *buf, size_t buflen);
150
151 /**
152 * Query upper layer for one or more TLS records, build fragments.
153 *
154 * The TLS stack automatically fragments the records to the given buffer
155 * size. Fragmentation is indicated by the reclen ouput parameter and
156 * the return value. For the first fragment of a TLS record, a non-zero
157 * record length is returned in reclen. If more fragments follow, NEED_MORE
158 * is returned. A return value of ALREADY_DONE indicates that the final
159 * fragment has been returned.
160 *
161 * @param buf buffer to write TLS record fragments to
162 * @param buflen size of buffer, receives bytes written
163 * @param msglen receives size of all TLS fragments
164 * @return
165 * - SUCCESS if TLS negotiation complete
166 * - FAILED if TLS handshake failed
167 * - INVALID_STATE if more input data required
168 * - NEED_MORE if more fragments available
169 * - ALREADY_DONE if the last available fragment returned
170 */
171 status_t (*build)(tls_t *this, void *buf, size_t *buflen, size_t *msglen);
172
173 /**
174 * Check if TLS stack is acting as a server.
175 *
176 * @return TRUE if server, FALSE if peer
177 */
178 bool (*is_server)(tls_t *this);
179
180 /**
181 * Get the negotiated TLS/SSL version.
182 *
183 * @return negotiated TLS version
184 */
185 tls_version_t (*get_version)(tls_t *this);
186
187 /**
188 * Set the negotiated TLS/SSL version.
189 *
190 * @param version negotiated TLS version
191 * @return TRUE if version acceptable
192 */
193 bool (*set_version)(tls_t *this, tls_version_t version);
194
195 /**
196 * Get the purpose of this TLS stack instance.
197 *
198 * @return purpose given during construction
199 */
200 tls_purpose_t (*get_purpose)(tls_t *this);
201
202 /**
203 * Check if TLS negotiation completed successfully.
204 *
205 * @return TRUE if TLS negotiation and authentication complete
206 */
207 bool (*is_complete)(tls_t *this);
208
209 /**
210 * Get the MSK for EAP-TLS.
211 *
212 * @return MSK, internal data
213 */
214 chunk_t (*get_eap_msk)(tls_t *this);
215
216 /**
217 * Destroy a tls_t.
218 */
219 void (*destroy)(tls_t *this);
220 };
221
222 /**
223 * Create a tls instance.
224 *
225 * @param is_server TRUE to act as server, FALSE for client
226 * @param server server identity
227 * @param peer peer identity, NULL for no client authentication
228 * @param purpose purpose this TLS stack instance is used for
229 * @param application higher layer application or NULL if none
230 * @return TLS stack
231 */
232 tls_t *tls_create(bool is_server, identification_t *server,
233 identification_t *peer, tls_purpose_t purpose,
234 tls_application_t *application);
235
236 #endif /** TLS_H_ @}*/