child-sa: Remove state to track installation of half the SA again
[strongswan.git] / src / libcharon / sa / child_sa.h
1 /*
2 * Copyright (C) 2006-2017 Tobias Brunner
3 * Copyright (C) 2006-2008 Martin Willi
4 * Copyright (C) 2006 Daniel Roethlisberger
5 * HSR 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 enum child_sa_outbound_state_t child_sa_outbound_state_t;
28 typedef struct child_sa_t child_sa_t;
29
30 #include <library.h>
31 #include <crypto/prf_plus.h>
32 #include <encoding/payloads/proposal_substructure.h>
33 #include <config/proposal.h>
34 #include <config/child_cfg.h>
35
36 /**
37 * States of a CHILD_SA
38 */
39 enum child_sa_state_t {
40
41 /**
42 * Just created, uninstalled CHILD_SA
43 */
44 CHILD_CREATED,
45
46 /**
47 * Installed SPD, but no SAD entries
48 */
49 CHILD_ROUTED,
50
51 /**
52 * Installing an in-use CHILD_SA
53 */
54 CHILD_INSTALLING,
55
56 /**
57 * Installed both SAs of a CHILD_SA
58 */
59 CHILD_INSTALLED,
60
61 /**
62 * While updating hosts, in update_hosts()
63 */
64 CHILD_UPDATING,
65
66 /**
67 * CHILD_SA which is rekeying
68 */
69 CHILD_REKEYING,
70
71 /**
72 * CHILD_SA that was rekeyed, but stays installed
73 */
74 CHILD_REKEYED,
75
76 /**
77 * CHILD_SA negotiation failed, but gets retried
78 */
79 CHILD_RETRYING,
80
81 /**
82 * CHILD_SA in progress of delete
83 */
84 CHILD_DELETING,
85
86 /**
87 * CHILD_SA object gets destroyed
88 */
89 CHILD_DESTROYING,
90 };
91
92 /**
93 * enum strings for child_sa_state_t.
94 */
95 extern enum_name_t *child_sa_state_names;
96
97 /**
98 * States of the outbound SA of a CHILD_SA
99 */
100 enum child_sa_outbound_state_t {
101
102 /**
103 * Outbound SA is not installed
104 */
105 CHILD_OUTBOUND_NONE,
106
107 /**
108 * Data for the outbound SA has been registered, but not installed yet
109 */
110 CHILD_OUTBOUND_REGISTERED,
111
112 /**
113 * The outbound SA is currently installed
114 */
115 CHILD_OUTBOUND_INSTALLED,
116 };
117
118 /**
119 * enum strings for child_sa_outbound_state_t.
120 */
121 extern enum_name_t *child_sa_outbound_state_names;
122
123 /**
124 * Represents an IPsec SAs between two hosts.
125 *
126 * A child_sa_t contains two SAs. SAs for both
127 * directions are managed in one child_sa_t object. Both
128 * SAs and the policies have the same reqid.
129 *
130 * The procedure for child sa setup is as follows:
131 * - A gets SPIs for a all protocols in its proposals via child_sa_t.alloc
132 * - A send the proposals with the allocated SPIs to B
133 * - B selects a suitable proposal
134 * - B allocates an SPI for the selected protocol
135 * - B calls child_sa_t.install for both, the allocated and received SPI
136 * - B sends the proposal with the allocated SPI to A
137 * - A calls child_sa_t.install for both, the allocated and recevied SPI
138 *
139 * Once SAs are set up, policies can be added using add_policies.
140 */
141 struct child_sa_t {
142
143 /**
144 * Get the name of the config this CHILD_SA uses.
145 *
146 * @return name
147 */
148 char* (*get_name) (child_sa_t *this);
149
150 /**
151 * Get the reqid of the CHILD SA.
152 *
153 * Every CHILD_SA has a reqid. The kernel uses this ID to
154 * identify it.
155 *
156 * @return reqid of the CHILD SA
157 */
158 uint32_t (*get_reqid)(child_sa_t *this);
159
160 /**
161 * Get the unique numerical identifier for this CHILD_SA.
162 *
163 * While the same reqid might be shared between multiple SAs, the unique_id
164 * is truly unique for all CHILD_SA instances.
165 *
166 * @return unique CHILD_SA identifier
167 */
168 uint32_t (*get_unique_id)(child_sa_t *this);
169
170 /**
171 * Get the config used to set up this child sa.
172 *
173 * @return child_cfg
174 */
175 child_cfg_t* (*get_config) (child_sa_t *this);
176
177 /**
178 * Get the state of the CHILD_SA.
179 *
180 * @return CHILD_SA state
181 */
182 child_sa_state_t (*get_state)(child_sa_t *this);
183
184 /**
185 * Get the state of the outbound SA.
186 *
187 * @return outbound SA state
188 */
189 child_sa_outbound_state_t (*get_outbound_state)(child_sa_t *this);
190
191 /**
192 * Set the state of the CHILD_SA.
193 *
194 * @param state state to set on CHILD_SA
195 */
196 void (*set_state) (child_sa_t *this, child_sa_state_t state);
197
198 /**
199 * Get the SPI of this CHILD_SA.
200 *
201 * Set the boolean parameter inbound to TRUE to
202 * get the SPI for which we receive packets, use
203 * FALSE to get those we use for sending packets.
204 *
205 * @param inbound TRUE to get inbound SPI, FALSE for outbound.
206 * @return SPI of the CHILD SA
207 */
208 uint32_t (*get_spi) (child_sa_t *this, bool inbound);
209
210 /**
211 * Get the CPI of this CHILD_SA.
212 *
213 * Set the boolean parameter inbound to TRUE to
214 * get the CPI for which we receive packets, use
215 * FALSE to get those we use for sending packets.
216 *
217 * @param inbound TRUE to get inbound CPI, FALSE for outbound.
218 * @return CPI of the CHILD SA
219 */
220 uint16_t (*get_cpi) (child_sa_t *this, bool inbound);
221
222 /**
223 * Get the protocol which this CHILD_SA uses to protect traffic.
224 *
225 * @return AH | ESP
226 */
227 protocol_id_t (*get_protocol) (child_sa_t *this);
228
229 /**
230 * Set the negotiated protocol to use for this CHILD_SA.
231 *
232 * @param protocol AH | ESP
233 */
234 void (*set_protocol)(child_sa_t *this, protocol_id_t protocol);
235
236 /**
237 * Get the IPsec mode of this CHILD_SA.
238 *
239 * @return TUNNEL | TRANSPORT | BEET
240 */
241 ipsec_mode_t (*get_mode)(child_sa_t *this);
242
243 /**
244 * Set the negotiated IPsec mode to use.
245 *
246 * @param mode TUNNEL | TRANPORT | BEET
247 */
248 void (*set_mode)(child_sa_t *this, ipsec_mode_t mode);
249
250 /**
251 * Get the used IPComp algorithm.
252 *
253 * @return IPComp compression algorithm.
254 */
255 ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);
256
257 /**
258 * Set the IPComp algorithm to use.
259 *
260 * @param ipcomp the IPComp transform to use
261 */
262 void (*set_ipcomp)(child_sa_t *this, ipcomp_transform_t ipcomp);
263
264 /**
265 * Get the action to enforce if the remote peer closes the CHILD_SA.
266 *
267 * @return close action
268 */
269 action_t (*get_close_action)(child_sa_t *this);
270
271 /**
272 * Override the close action specified by the CHILD_SA config.
273 *
274 * @param close action to enforce
275 */
276 void (*set_close_action)(child_sa_t *this, action_t action);
277
278 /**
279 * Get the action to enforce if the peer is considered dead.
280 *
281 * @return dpd action
282 */
283 action_t (*get_dpd_action)(child_sa_t *this);
284
285 /**
286 * Override the DPD action specified by the CHILD_SA config.
287 *
288 * @param dpd action to enforce
289 */
290 void (*set_dpd_action)(child_sa_t *this, action_t action);
291
292 /**
293 * Get the selected proposal.
294 *
295 * @return selected proposal
296 */
297 proposal_t* (*get_proposal)(child_sa_t *this);
298
299 /**
300 * Set the negotiated proposal.
301 *
302 * @param proposal selected proposal
303 */
304 void (*set_proposal)(child_sa_t *this, proposal_t *proposal);
305
306 /**
307 * Check if this CHILD_SA uses UDP encapsulation.
308 *
309 * @return TRUE if SA encapsulates ESP packets
310 */
311 bool (*has_encap)(child_sa_t *this);
312
313 /**
314 * Get the absolute time when the CHILD_SA expires or gets rekeyed.
315 *
316 * @param hard TRUE for hard lifetime, FALSE for soft (rekey) lifetime
317 * @return absolute time
318 */
319 time_t (*get_lifetime)(child_sa_t *this, bool hard);
320
321 /**
322 * Get the absolute time when this SA has been installed.
323 *
324 * @return monotonic absolute install time
325 */
326 time_t (*get_installtime)(child_sa_t *this);
327
328 /**
329 * Get last use time and the number of bytes processed.
330 *
331 * @param inbound TRUE for inbound traffic, FALSE for outbound
332 * @param[out] time time of last use in seconds (NULL to ignore)
333 * @param[out] bytes number of processed bytes (NULL to ignore)
334 * @param[out] packets number of processed packets (NULL to ignore)
335 */
336 void (*get_usestats)(child_sa_t *this, bool inbound, time_t *time,
337 uint64_t *bytes, uint64_t *packets);
338
339 /**
340 * Get the mark used with this CHILD_SA.
341 *
342 * @param inbound TRUE to get inbound mark, FALSE for outbound
343 * @return mark used with this CHILD_SA
344 */
345 mark_t (*get_mark)(child_sa_t *this, bool inbound);
346
347 /**
348 * Create an enumerator over traffic selectors of one side.
349 *
350 * @param local TRUE for own traffic selectors, FALSE for remote.
351 * @return enumerator over traffic_selector_t*
352 */
353 enumerator_t* (*create_ts_enumerator)(child_sa_t *this, bool local);
354
355 /**
356 * Create an enumerator over installed policies.
357 *
358 * The enumerated traffic selectors is a full mesh of compatible local
359 * and remote traffic selectors.
360 *
361 * @return enumerator over a pair of traffic_selector_t*
362 */
363 enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
364
365 /**
366 * Allocate an SPI to include in a proposal.
367 *
368 * @param protocol protocol to allocate SPI for (ESP|AH)
369 * @param spi SPI output pointer
370 * @return SPI, 0 on failure
371 */
372 uint32_t (*alloc_spi)(child_sa_t *this, protocol_id_t protocol);
373
374 /**
375 * Allocate a CPI to use for IPComp.
376 *
377 * @return CPI, 0 on failure
378 */
379 uint16_t (*alloc_cpi)(child_sa_t *this);
380
381 /**
382 * Install an IPsec SA for one direction.
383 *
384 * set_policies() should be called before calling this.
385 *
386 * @param encr encryption key, if any
387 * @param integ integrity key
388 * @param spi SPI to use, allocated for inbound
389 * @param cpi CPI to use, allocated for outbound
390 * @param initiator TRUE if initiator of exchange resulting in this SA
391 * @param inbound TRUE to install an inbound SA, FALSE for outbound
392 * @param tfcv3 TRUE if peer supports ESPv3 TFC
393 * @return SUCCESS or FAILED
394 */
395 status_t (*install)(child_sa_t *this, chunk_t encr, chunk_t integ,
396 uint32_t spi, uint16_t cpi,
397 bool initiator, bool inbound, bool tfcv3);
398
399 /**
400 * Register data for the installation of an outbound SA as responder during
401 * a rekeying.
402 *
403 * The SA is not installed until install_outbound() is called.
404 *
405 * @param encr encryption key, if any (cloned)
406 * @param integ integrity key (cloned)
407 * @param spi SPI to use, allocated for inbound
408 * @param cpi CPI to use, allocated for outbound
409 * @param tfcv3 TRUE if peer supports ESPv3 TFC
410 */
411 void (*register_outbound)(child_sa_t *this, chunk_t encr, chunk_t integ,
412 uint32_t spi, uint16_t cpi, bool tfcv3);
413
414 /**
415 * Install the outbound SA and the outbound policies as responder during a
416 * rekeying.
417 *
418 * @return SUCCESS or FAILED
419 */
420 status_t (*install_outbound)(child_sa_t *this);
421
422 /**
423 * Remove the outbound SA and the outbound policies after a rekeying.
424 */
425 void (*remove_outbound)(child_sa_t *this);
426
427 /**
428 * Configure the policies using some traffic selectors.
429 *
430 * Supplied lists of traffic_selector_t's specify the policies
431 * to use for this child sa.
432 *
433 * Install the policies by calling install_policies().
434 *
435 * This should be called before calling install() so the traffic selectors
436 * may be passed to the kernel interface when installing the SAs.
437 *
438 * @param my_ts traffic selectors for local site (cloned)
439 * @param other_ts traffic selectors for remote site (cloned)
440 */
441 void (*set_policies)(child_sa_t *this, linked_list_t *my_ts_list,
442 linked_list_t *other_ts_list);
443
444 /**
445 * Install the configured policies.
446 *
447 * If register_outbound() was called previously this only installs the
448 * inbound and forward policies, the outbound policies are installed when
449 * install_outbound() is called.
450 *
451 * @return SUCCESS or FAILED
452 */
453 status_t (*install_policies)(child_sa_t *this);
454
455 /**
456 * Set the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
457 * a rekeying.
458 *
459 * @param spi outbound SPI of the CHILD_SA that replaced this CHILD_SA
460 */
461 void (*set_rekey_spi)(child_sa_t *this, uint32_t spi);
462
463 /**
464 * Get the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
465 * a rekeying.
466 *
467 * @return outbound SPI of the CHILD_SA that replaced this CHILD_SA
468 */
469 uint32_t (*get_rekey_spi)(child_sa_t *this);
470
471 /**
472 * Update hosts and ecapulation mode in the kernel SAs and policies.
473 *
474 * @param me the new local host
475 * @param other the new remote host
476 * @param vips list of local virtual IPs
477 * @param encap TRUE to use UDP encapsulation for NAT traversal
478 * @return SUCCESS or FAILED
479 */
480 status_t (*update)(child_sa_t *this, host_t *me, host_t *other,
481 linked_list_t *vips, bool encap);
482 /**
483 * Destroys a child_sa.
484 */
485 void (*destroy) (child_sa_t *this);
486 };
487
488 /**
489 * Constructor to create a child SA negotiated with IKE.
490 *
491 * @param me own address
492 * @param other remote address
493 * @param config config to use for this CHILD_SA
494 * @param reqid reqid of old CHILD_SA when rekeying, 0 otherwise
495 * @param encap TRUE to enable UDP encapsulation (NAT traversal)
496 * @param mark_in explicit inbound mark value to use, 0 for config
497 * @param mark_out explicit outbound mark value to use, 0 for config
498 * @return child_sa_t object
499 */
500 child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
501 uint32_t reqid, bool encap,
502 u_int mark_in, u_int mark_out);
503
504 #endif /** CHILD_SA_H_ @}*/