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