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