712a4765c55ce54653c28e0acaee22ef7686a0b3
[strongswan.git] / src / libcharon / sa / child_sa.h
1 /*
2 * Copyright (C) 2006-2008 Tobias Brunner
3 * Copyright (C) 2006-2008 Martin Willi
4 * Copyright (C) 2006 Daniel Roethlisberger
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup child_sa child_sa
20 * @{ @ingroup sa
21 */
22
23 #ifndef CHILD_SA_H_
24 #define CHILD_SA_H_
25
26 typedef enum child_sa_state_t child_sa_state_t;
27 typedef struct child_sa_t child_sa_t;
28
29 #include <library.h>
30 #include <crypto/prf_plus.h>
31 #include <encoding/payloads/proposal_substructure.h>
32 #include <config/proposal.h>
33 #include <config/child_cfg.h>
34
35 /**
36 * States of a CHILD_SA
37 */
38 enum child_sa_state_t {
39
40 /**
41 * Just created, uninstalled CHILD_SA
42 */
43 CHILD_CREATED,
44
45 /**
46 * Installed SPD, but no SAD entries
47 */
48 CHILD_ROUTED,
49
50 /**
51 * Installing an in-use CHILD_SA
52 */
53 CHILD_INSTALLING,
54
55 /**
56 * Installed an in-use CHILD_SA
57 */
58 CHILD_INSTALLED,
59
60 /**
61 * While updating hosts, in update_hosts()
62 */
63 CHILD_UPDATING,
64
65 /**
66 * CHILD_SA which is rekeying
67 */
68 CHILD_REKEYING,
69
70 /**
71 * CHILD_SA in progress of delete
72 */
73 CHILD_DELETING,
74
75 /**
76 * CHILD_SA object gets destroyed
77 */
78 CHILD_DESTROYING,
79 };
80
81 /**
82 * enum strings for child_sa_state_t.
83 */
84 extern enum_name_t *child_sa_state_names;
85
86 /**
87 * Represents an IPsec SAs between two hosts.
88 *
89 * A child_sa_t contains two SAs. SAs for both
90 * directions are managed in one child_sa_t object. Both
91 * SAs and the policies have the same reqid.
92 *
93 * The procedure for child sa setup is as follows:
94 * - A gets SPIs for a all protocols in its proposals via child_sa_t.alloc
95 * - A send the proposals with the allocated SPIs to B
96 * - B selects a suitable proposal
97 * - B allocates an SPI for the selected protocol
98 * - B calls child_sa_t.install for both, the allocated and received SPI
99 * - B sends the proposal with the allocated SPI to A
100 * - A calls child_sa_t.install for both, the allocated and recevied SPI
101 *
102 * Once SAs are set up, policies can be added using add_policies.
103 */
104 struct child_sa_t {
105
106 /**
107 * Get the name of the config this CHILD_SA uses.
108 *
109 * @return name
110 */
111 char* (*get_name) (child_sa_t *this);
112
113 /**
114 * Get the reqid of the CHILD SA.
115 *
116 * Every CHILD_SA has a reqid. The kernel uses this ID to
117 * identify it.
118 *
119 * @return reqid of the CHILD SA
120 */
121 u_int32_t (*get_reqid)(child_sa_t *this);
122
123 /**
124 * Get the config used to set up this child sa.
125 *
126 * @return child_cfg
127 */
128 child_cfg_t* (*get_config) (child_sa_t *this);
129
130 /**
131 * Get the state of the CHILD_SA.
132 *
133 * @return CHILD_SA state
134 */
135 child_sa_state_t (*get_state) (child_sa_t *this);
136
137 /**
138 * Set the state of the CHILD_SA.
139 *
140 * @param state state to set on CHILD_SA
141 */
142 void (*set_state) (child_sa_t *this, child_sa_state_t state);
143
144 /**
145 * Get the SPI of this CHILD_SA.
146 *
147 * Set the boolean parameter inbound to TRUE to
148 * get the SPI for which we receive packets, use
149 * FALSE to get those we use for sending packets.
150 *
151 * @param inbound TRUE to get inbound SPI, FALSE for outbound.
152 * @return SPI of the CHILD SA
153 */
154 u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
155
156 /**
157 * Get the CPI of this CHILD_SA.
158 *
159 * Set the boolean parameter inbound to TRUE to
160 * get the CPI for which we receive packets, use
161 * FALSE to get those we use for sending packets.
162 *
163 * @param inbound TRUE to get inbound CPI, FALSE for outbound.
164 * @return CPI of the CHILD SA
165 */
166 u_int16_t (*get_cpi) (child_sa_t *this, bool inbound);
167
168 /**
169 * Get the protocol which this CHILD_SA uses to protect traffic.
170 *
171 * @return AH | ESP
172 */
173 protocol_id_t (*get_protocol) (child_sa_t *this);
174
175 /**
176 * Set the negotiated protocol to use for this CHILD_SA.
177 *
178 * @param protocol AH | ESP
179 */
180 void (*set_protocol)(child_sa_t *this, protocol_id_t protocol);
181
182 /**
183 * Get the IPsec mode of this CHILD_SA.
184 *
185 * @return TUNNEL | TRANSPORT | BEET
186 */
187 ipsec_mode_t (*get_mode)(child_sa_t *this);
188
189 /**
190 * Set the negotiated IPsec mode to use.
191 *
192 * @param mode TUNNEL | TRANPORT | BEET
193 */
194 void (*set_mode)(child_sa_t *this, ipsec_mode_t mode);
195
196 /**
197 * Get the used IPComp algorithm.
198 *
199 * @return IPComp compression algorithm.
200 */
201 ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);
202
203 /**
204 * Set the IPComp algorithm to use.
205 *
206 * @param ipcomp the IPComp transform to use
207 */
208 void (*set_ipcomp)(child_sa_t *this, ipcomp_transform_t ipcomp);
209
210 /**
211 * Get the action to enforce if the remote peer closes the CHILD_SA.
212 *
213 * @return close action
214 */
215 action_t (*get_close_action)(child_sa_t *this);
216
217 /**
218 * Override the close action specified by the CHILD_SA config.
219 *
220 * @param close action to enforce
221 */
222 void (*set_close_action)(child_sa_t *this, action_t action);
223
224 /**
225 * Get the action to enforce if the peer is considered dead.
226 *
227 * @return dpd action
228 */
229 action_t (*get_dpd_action)(child_sa_t *this);
230
231 /**
232 * Override the DPD action specified by the CHILD_SA config.
233 *
234 * @param close action to enforce
235 */
236 void (*set_dpd_action)(child_sa_t *this, action_t action);
237
238 /**
239 * Get the selected proposal.
240 *
241 * @return selected proposal
242 */
243 proposal_t* (*get_proposal)(child_sa_t *this);
244
245 /**
246 * Set the negotiated proposal.
247 *
248 * @param proposal selected proposal
249 */
250 void (*set_proposal)(child_sa_t *this, proposal_t *proposal);
251
252 /**
253 * Check if this CHILD_SA uses UDP encapsulation.
254 *
255 * @return TRUE if SA encapsulates ESP packets
256 */
257 bool (*has_encap)(child_sa_t *this);
258
259 /**
260 * Get the absolute time when the CHILD_SA expires or gets rekeyed.
261 *
262 * @param hard TRUE for hard lifetime, FALSE for soft (rekey) lifetime
263 * @return absolute time
264 */
265 time_t (*get_lifetime)(child_sa_t *this, bool hard);
266
267 /**
268 * Get last use time and the number of bytes processed.
269 *
270 * @param inbound TRUE for inbound traffic, FALSE for outbound
271 * @param[out] time time of last use in seconds (NULL to ignore)
272 * @param[out] bytes number of processed bytes (NULL to ignore)
273 */
274 void (*get_usestats)(child_sa_t *this, bool inbound, time_t *time,
275 u_int64_t *bytes);
276
277 /**
278 * Get the mark used with this CHILD_SA.
279 *
280 * @param inbound TRUE to get inbound mark, FALSE for outbound
281 * @return mark used with this CHILD_SA
282 */
283 mark_t (*get_mark)(child_sa_t *this, bool inbound);
284
285 /**
286 * Get the traffic selectors list added for one side.
287 *
288 * @param local TRUE for own traffic selectors, FALSE for remote
289 * @return list of traffic selectors
290 */
291 linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local);
292
293 /**
294 * Create an enumerator over installed policies.
295 *
296 * @return enumerator over pairs of traffic selectors.
297 */
298 enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
299
300 /**
301 * Allocate an SPI to include in a proposal.
302 *
303 * @param protocol protocol to allocate SPI for (ESP|AH)
304 * @param spi SPI output pointer
305 * @return SPI, 0 on failure
306 */
307 u_int32_t (*alloc_spi)(child_sa_t *this, protocol_id_t protocol);
308
309 /**
310 * Allocate a CPI to use for IPComp.
311 *
312 * @return CPI, 0 on failure
313 */
314 u_int16_t (*alloc_cpi)(child_sa_t *this);
315
316 /**
317 * Install an IPsec SA for one direction.
318 *
319 * @param encr encryption key, if any
320 * @param integ integrity key
321 * @param spi SPI to use, allocated for inbound
322 * @param cpi CPI to use, allocated for outbound
323 * @param inbound TRUE to install an inbound SA, FALSE for outbound
324 * @param tfcv3 TRUE if peer supports ESPv3 TFC
325 * @param my_ts negotiated local traffic selector list
326 * @param other_ts negotiated remote traffic selector list
327 * @return SUCCESS or FAILED
328 */
329 status_t (*install)(child_sa_t *this, chunk_t encr, chunk_t integ,
330 u_int32_t spi, u_int16_t cpi, bool inbound, bool tfcv3,
331 linked_list_t *my_ts, linked_list_t *other_ts);
332 /**
333 * Install the policies using some traffic selectors.
334 *
335 * Supplied lists of traffic_selector_t's specify the policies
336 * to use for this child sa.
337 *
338 * @param my_ts traffic selectors for local site
339 * @param other_ts traffic selectors for remote site
340 * @return SUCCESS or FAILED
341 */
342 status_t (*add_policies)(child_sa_t *this, linked_list_t *my_ts_list,
343 linked_list_t *other_ts_list);
344 /**
345 * Update hosts and ecapulation mode in the kernel SAs and policies.
346 *
347 * @param me the new local host
348 * @param other the new remote host
349 * @param vip virtual IP, if any
350 * @param TRUE to use UDP encapsulation for NAT traversal
351 * @return SUCCESS or FAILED
352 */
353 status_t (*update)(child_sa_t *this, host_t *me, host_t *other,
354 host_t *vip, bool encap);
355 /**
356 * Destroys a child_sa.
357 */
358 void (*destroy) (child_sa_t *this);
359 };
360
361 /**
362 * Constructor to create a child SA negotiated with IKE.
363 *
364 * @param me own address
365 * @param other remote address
366 * @param config config to use for this CHILD_SA
367 * @param reqid reqid of old CHILD_SA when rekeying, 0 otherwise
368 * @param encap TRUE to enable UDP encapsulation (NAT traversal)
369 * @return child_sa_t object
370 */
371 child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
372 u_int32_t reqid, bool encap);
373
374 #endif /** CHILD_SA_H_ @}*/