f90c2e99c31345f32adc74f4d692435a6613bf55
[strongswan.git] / src / charon / config / connections / connection.h
1 /**
2 * @file connection.h
3 *
4 * @brief Interface of connection_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef CONNECTION_H_
25 #define CONNECTION_H_
26
27 typedef enum cert_policy_t cert_policy_t;
28 typedef struct connection_t connection_t;
29
30 #include <library.h>
31 #include <utils/host.h>
32 #include <utils/linked_list.h>
33 #include <utils/identification.h>
34 #include <config/proposal.h>
35 #include <crypto/diffie_hellman.h>
36
37
38 /**
39 * Certificate sending policy. This is also used for certificate
40 * requests when using this definition for the other peer. If
41 * it is CERT_NEVER_SEND, a certreq is omitted, otherwise its
42 * included.
43 *
44 * @ingroup config
45 *
46 * @warning These definitions must be the same as in pluto/starter,
47 * as they are sent over the stroke socket.
48 */
49 enum cert_policy_t {
50 /** always send certificates, even when not requested */
51 CERT_ALWAYS_SEND = 0,
52 /** send certificate upon cert request */
53 CERT_SEND_IF_ASKED = 1,
54 /** never send a certificate, even when requested */
55 CERT_NEVER_SEND = 2,
56 };
57
58 /**
59 * enum strings for cert_policy_t
60 *
61 * @ingroup config
62 */
63 extern enum_name_t *cert_policy_names;
64
65 /**
66 * @brief A connection_t defines the rules to set up an IKE_SA.
67 *
68 * @b Constructors:
69 * - connection_create()
70 *
71 * @ingroup config
72 */
73 struct connection_t {
74
75 /**
76 * @brief Get my address as host_t object.
77 *
78 * Object is NOT getting cloned.
79 *
80 * @param this calling object
81 * @return host information as host_t object
82 */
83 host_t *(*get_my_host) (connection_t *this);
84
85 /**
86 * @brief Get others address as host_t object.
87 *
88 * Object is NOT getting cloned.
89 *
90 * @param this calling object
91 * @return host information as host_t object
92 */
93 host_t *(*get_other_host) (connection_t *this);
94
95 /**
96 * @brief Returns a list of all supported proposals.
97 *
98 * Returned list and its proposals must be destroyed after usage.
99 *
100 * @param this calling object
101 * @return list containing all the proposals
102 */
103 linked_list_t *(*get_proposals) (connection_t *this);
104
105 /**
106 * @brief Adds a proposal to the list.
107 *
108 * The first added proposal has the highest priority, the last
109 * added the lowest.
110 *
111 * @param this calling object
112 * @param proposal proposal to add
113 */
114 void (*add_proposal) (connection_t *this, proposal_t *proposal);
115
116 /**
117 * @brief Select a proposed from suggested proposals.
118 *
119 * Returned proposal must be destroyed after usage.
120 *
121 * @param this calling object
122 * @param proposals list of proposals to select from
123 * @return selected proposal, or NULL if none matches.
124 */
125 proposal_t *(*select_proposal) (connection_t *this, linked_list_t *proposals);
126
127 /**
128 * @brief Get the DPD check interval.
129 *
130 * @param this calling object
131 * @return dpd_delay in seconds
132 */
133 u_int32_t (*get_dpd_delay) (connection_t *this);
134
135 /**
136 * @brief Should a full reauthentication be done instead of rekeying?
137 *
138 * @param this calling object
139 * @return TRUE to use full reauthentication
140 */
141 bool (*get_reauth) (connection_t *this);
142
143 /**
144 * @brief Get the max number of retransmission sequences.
145 *
146 * After this number of sequences, a not responding peer is considered
147 * dead.
148 *
149 * @param this calling object
150 * @return max number of retransmission sequences
151 */
152 u_int32_t (*get_retrans_seq) (connection_t *this);
153
154 /**
155 * @brief Get the connection name.
156 *
157 * Name must not be freed, since it points to
158 * internal data.
159 *
160 * @param this calling object
161 * @return name of the connection
162 */
163 char* (*get_name) (connection_t *this);
164
165 /**
166 * @brief Check if the connection is marked as an IKEv2 connection.
167 *
168 * Since all connections (IKEv1+2) are loaded, but charon handles
169 * only those marked with IKEv2, this flag can tell us if we must
170 * ignore a connection on initiaton. Then pluto will do it for us.
171 *
172 * @param this calling object
173 * @return - TRUE, if this is an IKEv2 connection
174 */
175 bool (*is_ikev2) (connection_t *this);
176
177 /**
178 * @brief Should be sent a certificate request for this connection?
179 *
180 * A certificate request contains serials of our trusted CA certificates.
181 * This flag says if such a request is sent on connection setup to
182 * the peer. It should be omitted when CERT_SEND_NEVER, sended otherwise.
183 *
184 * @param this calling object
185 * @return certificate request sending policy
186 */
187 cert_policy_t (*get_certreq_policy) (connection_t *this);
188
189 /**
190 * @brief Should be sent a certificate for this connection?
191 *
192 * Return the policy used to send the certificate.
193 *
194 * @param this calling object
195 * @return certificate sending policy
196 */
197 cert_policy_t (*get_cert_policy) (connection_t *this);
198
199 /**
200 * @brief Get the DH group to use for connection initialization.
201 *
202 * @param this calling object
203 * @return dh group to use for initialization
204 */
205 diffie_hellman_group_t (*get_dh_group) (connection_t *this);
206
207 /**
208 * @brief Check if a suggested dh group is acceptable.
209 *
210 * If we guess a wrong DH group for IKE_SA_INIT, the other
211 * peer will send us a offer. But is this acceptable for us?
212 *
213 * @param this calling object
214 * @return TRUE if group acceptable
215 */
216 bool (*check_dh_group) (connection_t *this, diffie_hellman_group_t dh_group);
217
218 /**
219 * @brief Get the lifetime of a connection, before IKE_SA rekeying starts.
220 *
221 * A call to this function automatically adds a jitter to
222 * avoid simultanous rekeying.
223 *
224 * @param this calling object
225 * @return lifetime in seconds
226 */
227 u_int32_t (*get_soft_lifetime) (connection_t *this);
228
229 /**
230 * @brief Get the lifetime of a connection, before IKE_SA gets deleted.
231 *
232 * @param this calling object
233 * @return lifetime in seconds
234 */
235 u_int32_t (*get_hard_lifetime) (connection_t *this);
236
237 /**
238 * @brief Get a new reference to this connection.
239 *
240 * Get a new reference to this connection by increasing
241 * it's internal reference counter.
242 * Do not call get_ref or any other function until you
243 * already have a reference. Otherwise the object may get
244 * destroyed while calling get_ref(),
245 *
246 * @param this calling object
247 */
248 void (*get_ref) (connection_t *this);
249
250 /**
251 * @brief Destroys a connection_t object.
252 *
253 * Decrements the internal reference counter and
254 * destroys the connection when it reaches zero.
255 *
256 * @param this calling object
257 */
258 void (*destroy) (connection_t *this);
259 };
260
261 /**
262 * @brief Creates a connection_t object.
263 *
264 * Supplied hosts become owned by connection, so
265 * do not modify or destroy them after a call to
266 * connection_create(). Name gets cloned internally.
267 * The retrasmit sequence number says how fast we give up when the peer
268 * does not respond. A high value may bridge-over temporary connection
269 * problems, a small value can detect dead peers faster.
270 *
271 * @param name connection identifier
272 * @param ikev2 TRUE if this is an IKEv2 connection
273 * @param cert_policy certificate send policy
274 * @param cert_req_policy certificate request send policy
275 * @param my_host host_t representing local address
276 * @param other_host host_t representing remote address
277 * @param dpd_delay interval of DPD liveness checks
278 * @param reauth use full reauthentication instead of rekeying
279 * @param retrans_sequences number of retransmit sequences to use
280 * @param hard_lifetime lifetime before deleting an IKE_SA
281 * @param soft_lifetime lifetime before rekeying an IKE_SA
282 * @param jitter range of randomization time
283 * @return connection_t object.
284 *
285 * @ingroup config
286 */
287 connection_t * connection_create(char *name, bool ikev2,
288 cert_policy_t cert_pol, cert_policy_t req_pol,
289 host_t *my_host, host_t *other_host,
290 u_int32_t dpd_delay, bool reauth,
291 u_int32_t retrans_sequences,
292 u_int32_t hard_lifetime, u_int32_t soft_lifetime,
293 u_int32_t jitter);
294
295 #endif /* CONNECTION_H_ */