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