optional certificate-based peer authentication on TLS server side
[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 struct tls_t tls_t;
33
34 #include <library.h>
35
36 #include "tls_application.h"
37
38 /**
39 * TLS/SSL version numbers
40 */
41 enum tls_version_t {
42 SSL_2_0 = 0x0200,
43 SSL_3_0 = 0x0300,
44 TLS_1_0 = 0x0301,
45 TLS_1_1 = 0x0302,
46 TLS_1_2 = 0x0303,
47 };
48
49 /**
50 * Enum names for tls_version_t
51 */
52 extern enum_name_t *tls_version_names;
53
54 /**
55 * TLS higher level content type
56 */
57 enum tls_content_type_t {
58 TLS_CHANGE_CIPHER_SPEC = 20,
59 TLS_ALERT = 21,
60 TLS_HANDSHAKE = 22,
61 TLS_APPLICATION_DATA = 23,
62 };
63
64 /**
65 * Enum names for tls_content_type_t
66 */
67 extern enum_name_t *tls_content_type_names;
68
69 /**
70 * TLS handshake subtype
71 */
72 enum tls_handshake_type_t {
73 TLS_HELLO_REQUEST = 0,
74 TLS_CLIENT_HELLO = 1,
75 TLS_SERVER_HELLO = 2,
76 TLS_CERTIFICATE = 11,
77 TLS_SERVER_KEY_EXCHANGE = 12,
78 TLS_CERTIFICATE_REQUEST = 13,
79 TLS_SERVER_HELLO_DONE = 14,
80 TLS_CERTIFICATE_VERIFY = 15,
81 TLS_CLIENT_KEY_EXCHANGE = 16,
82 TLS_FINISHED = 20,
83 };
84
85 /**
86 * Enum names for tls_handshake_type_t
87 */
88 extern enum_name_t *tls_handshake_type_names;
89
90 /**
91 * A bottom-up driven TLS stack, suitable for EAP implementations.
92 */
93 struct tls_t {
94
95 /**
96 * Process a TLS record, pass it to upper layers.
97 *
98 * @param type type of the TLS record to process
99 * @param data associated TLS record data
100 * @return
101 * - SUCCESS if TLS negotiation complete
102 * - FAILED if TLS handshake failed
103 * - NEED_MORE if more invocations to process/build needed
104 */
105 status_t (*process)(tls_t *this, tls_content_type_t type, chunk_t data);
106
107 /**
108 * Query upper layer for TLS record, build protected record.
109 *
110 * @param type type of the built TLS record
111 * @param data allocated data of the built TLS record
112 * @return
113 * - SUCCESS if TLS negotiation complete
114 * - FAILED if TLS handshake failed
115 * - NEED_MORE if upper layers have more records to send
116 * - INVALID_STATE if more input records required
117 */
118 status_t (*build)(tls_t *this, tls_content_type_t *type, chunk_t *data);
119
120 /**
121 * Check if TLS stack is acting as a server.
122 *
123 * @return TRUE if server, FALSE if peer
124 */
125 bool (*is_server)(tls_t *this);
126
127 /**
128 * Get the negotiated TLS/SSL version.
129 *
130 * @return negotiated TLS version
131 */
132 tls_version_t (*get_version)(tls_t *this);
133
134 /**
135 * Set the negotiated TLS/SSL version.
136 *
137 * @param version negotiated TLS version
138 */
139 void (*set_version)(tls_t *this, tls_version_t version);
140
141 /**
142 * Check if TLS negotiation completed successfully.
143 *
144 * @return TRUE if TLS negotation and authentication complete
145 */
146 bool (*is_complete)(tls_t *this);
147
148 /**
149 * Get the MSK for EAP-TLS.
150 *
151 * @return MSK, internal data
152 */
153 chunk_t (*get_eap_msk)(tls_t *this);
154
155 /**
156 * Destroy a tls_t.
157 */
158 void (*destroy)(tls_t *this);
159 };
160
161 /**
162 * Create a tls instance.
163 *
164 * @param is_server TRUE to act as server, FALSE for client
165 * @param server server identity
166 * @param peer peer identity
167 * @param request_peer_auth TRUE to request certificate-based peer authentication
168 * @param msk_label ASCII string constant used as seed for MSK PRF
169 * @param application higher layer application or NULL if none
170 * @return TLS stack
171 */
172 tls_t *tls_create(bool is_server, identification_t *server,
173 identification_t *peer, bool request_peer_auth,
174 char *msk_label, tls_application_t *application);
175
176 #endif /** TLS_H_ @}*/