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