summaryrefslogtreecommitdiff
path: root/src/libcharon/sa/child_sa.h
blob: 49175ca010b9ce6e5a2dbccc502950715dd1e68a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
/*
 * Copyright (C) 2006-2017 Tobias Brunner
 * Copyright (C) 2006-2008 Martin Willi
 * Copyright (C) 2006 Daniel Roethlisberger
 * HSR Hochschule fuer Technik Rapperswil
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 */

/**
 * @defgroup child_sa child_sa
 * @{ @ingroup sa
 */

#ifndef CHILD_SA_H_
#define CHILD_SA_H_

typedef enum child_sa_state_t child_sa_state_t;
typedef enum child_sa_outbound_state_t child_sa_outbound_state_t;
typedef struct child_sa_t child_sa_t;

#include <library.h>
#include <crypto/prf_plus.h>
#include <encoding/payloads/proposal_substructure.h>
#include <crypto/proposal/proposal.h>
#include <config/child_cfg.h>

/**
 * States of a CHILD_SA
 */
enum child_sa_state_t {

	/**
	 * Just created, uninstalled CHILD_SA
	 */
	CHILD_CREATED,

	/**
	 * Installed SPD, but no SAD entries
	 */
	CHILD_ROUTED,

	/**
	 * Installing an in-use CHILD_SA
	 */
	CHILD_INSTALLING,

	/**
	 * Installed both SAs of a CHILD_SA
	 */
	CHILD_INSTALLED,

	/**
	 * While updating hosts, in update_hosts()
	 */
	CHILD_UPDATING,

	/**
	 * CHILD_SA which is rekeying
	 */
	CHILD_REKEYING,

	/**
	 * CHILD_SA that was rekeyed, but stays installed
	 */
	CHILD_REKEYED,

	/**
	 * CHILD_SA negotiation failed, but gets retried
	 */
	CHILD_RETRYING,

	/**
	 * CHILD_SA in progress of delete
	 */
	CHILD_DELETING,

	/**
	 * CHILD_SA object gets destroyed
	 */
	CHILD_DESTROYING,
};

/**
 * enum strings for child_sa_state_t.
 */
extern enum_name_t *child_sa_state_names;

/**
 * States of the outbound SA of a CHILD_SA
 */
enum child_sa_outbound_state_t {

	/**
	 * Outbound SA is not installed
	 */
	CHILD_OUTBOUND_NONE = 0,

	/**
	 * Data for the outbound SA has been registered during a rekeying (not set
	 * once the SA and policies are both installed)
	 */
	CHILD_OUTBOUND_REGISTERED = (1<<0),

	/**
	 * The outbound SA has been installed
	 */
	CHILD_OUTBOUND_SA = (1<<1),

	/**
	 * The outbound policies have been installed
	 */
	CHILD_OUTBOUND_POLICIES = (1<<2),

	/**
	 * The outbound SA and policies are both installed
	 */
	CHILD_OUTBOUND_INSTALLED = (CHILD_OUTBOUND_SA|CHILD_OUTBOUND_POLICIES),
};

/**
 * enum strings for child_sa_outbound_state_t.
 */
extern enum_name_t *child_sa_outbound_state_names;

/**
 * Represents an IPsec SAs between two hosts.
 *
 * A child_sa_t contains two SAs. SAs for both
 * directions are managed in one child_sa_t object. Both
 * SAs and the policies have the same reqid.
 *
 * The procedure for child sa setup is as follows:
 * - A gets SPIs for a all protocols in its proposals via child_sa_t.alloc
 * - A send the proposals with the allocated SPIs to B
 * - B selects a suitable proposal
 * - B allocates an SPI for the selected protocol
 * - B calls child_sa_t.install for both, the allocated and received SPI
 * - B sends the proposal with the allocated SPI to A
 * - A calls child_sa_t.install for both, the allocated and received SPI
 *
 * Once SAs are set up, policies can be added using add_policies.
 */
struct child_sa_t {

	/**
	 * Get the name of the config this CHILD_SA uses.
	 *
	 * @return			name
	 */
	char* (*get_name) (child_sa_t *this);

	/**
	 * Get the reqid of the CHILD SA.
	 *
	 * Every CHILD_SA has a reqid. The kernel uses this ID to
	 * identify it.
	 *
	 * @return 			reqid of the CHILD SA
	 */
	uint32_t (*get_reqid)(child_sa_t *this);

	/**
	 * Get the unique numerical identifier for this CHILD_SA.
	 *
	 * While the same reqid might be shared between multiple SAs, the unique_id
	 * is truly unique for all CHILD_SA instances.
	 *
	 * @return			unique CHILD_SA identifier
	 */
	uint32_t (*get_unique_id)(child_sa_t *this);

	/**
	 * Get the config used to set up this child sa.
	 *
	 * @return			child_cfg
	 */
	child_cfg_t* (*get_config) (child_sa_t *this);

	/**
	 * Get the state of the CHILD_SA.
	 *
	 * @return 			CHILD_SA state
	 */
	child_sa_state_t (*get_state)(child_sa_t *this);

	/**
	 * Get the state of the outbound SA.
	 *
	 * @return 			outbound SA state
	 */
	child_sa_outbound_state_t (*get_outbound_state)(child_sa_t *this);

	/**
	 * Set the state of the CHILD_SA.
	 *
	 * @param state		state to set on CHILD_SA
	 */
	void (*set_state) (child_sa_t *this, child_sa_state_t state);

	/**
	 * Get the SPI of this CHILD_SA.
	 *
	 * Set the boolean parameter inbound to TRUE to
	 * get the SPI for which we receive packets, use
	 * FALSE to get those we use for sending packets.
	 *
	 * @param inbound	TRUE to get inbound SPI, FALSE for outbound.
	 * @return 			SPI of the CHILD SA
	 */
	uint32_t (*get_spi) (child_sa_t *this, bool inbound);

	/**
	 * Get the CPI of this CHILD_SA.
	 *
	 * Set the boolean parameter inbound to TRUE to
	 * get the CPI for which we receive packets, use
	 * FALSE to get those we use for sending packets.
	 *
	 * @param inbound	TRUE to get inbound CPI, FALSE for outbound.
	 * @return 			CPI of the CHILD SA
	 */
	uint16_t (*get_cpi) (child_sa_t *this, bool inbound);

	/**
	 * Get the protocol which this CHILD_SA uses to protect traffic.
	 *
	 * @return 			AH | ESP
	 */
	protocol_id_t (*get_protocol) (child_sa_t *this);

	/**
	 * Set the negotiated protocol to use for this CHILD_SA.
	 *
	 * @param protocol	AH | ESP
	 */
	void (*set_protocol)(child_sa_t *this, protocol_id_t protocol);

	/**
	 * Get the IPsec mode of this CHILD_SA.
	 *
	 * @return			TUNNEL | TRANSPORT | BEET
	 */
	ipsec_mode_t (*get_mode)(child_sa_t *this);

	/**
	 * Set the negotiated IPsec mode to use.
	 *
	 * @param mode		TUNNEL | TRANSPORT | BEET
	 */
	void (*set_mode)(child_sa_t *this, ipsec_mode_t mode);

	/**
	 * Get the used IPComp algorithm.
	 *
	 * @return			IPComp compression algorithm.
	 */
	ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);

	/**
	 * Set the IPComp algorithm to use.
	 *
	 * @param ipcomp	the IPComp transform to use
	 */
	void (*set_ipcomp)(child_sa_t *this, ipcomp_transform_t ipcomp);

	/**
	 * Get the action to enforce if the remote peer closes the CHILD_SA.
	 *
	 * @return			close action
	 */
	action_t (*get_close_action)(child_sa_t *this);

	/**
	 * Override the close action specified by the CHILD_SA config.
	 *
	 * @param			close action to enforce
	 */
	void (*set_close_action)(child_sa_t *this, action_t action);

	/**
	 * Get the action to enforce if the peer is considered dead.
	 *
	 * @return			dpd action
	 */
	action_t (*get_dpd_action)(child_sa_t *this);

	/**
	 * Override the DPD action specified by the CHILD_SA config.
	 *
	 * @param			dpd action to enforce
	 */
	void (*set_dpd_action)(child_sa_t *this, action_t action);

	/**
	 * Get the selected proposal.
	 *
	 * @return			selected proposal
	 */
	proposal_t* (*get_proposal)(child_sa_t *this);

	/**
	 * Set the negotiated proposal.
	 *
	 * @param proposal	selected proposal
	 */
	void (*set_proposal)(child_sa_t *this, proposal_t *proposal);

	/**
	 * Check if this CHILD_SA uses UDP encapsulation.
	 *
	 * @return			TRUE if SA encapsulates ESP packets
	 */
	bool (*has_encap)(child_sa_t *this);

	/**
	 * Get the absolute time when the CHILD_SA expires or gets rekeyed.
	 *
	 * @param hard		TRUE for hard lifetime, FALSE for soft (rekey) lifetime
	 * @return			absolute time
	 */
	time_t (*get_lifetime)(child_sa_t *this, bool hard);

	/**
	 * Get the absolute time when this SA has been installed.
	 *
	 * @return			monotonic absolute install time
	 */
	time_t (*get_installtime)(child_sa_t *this);

	/**
	 * Get last use time and the number of bytes processed.
	 *
	 * @param inbound		TRUE for inbound traffic, FALSE for outbound
	 * @param[out] time		time of last use in seconds (NULL to ignore)
	 * @param[out] bytes	number of processed bytes (NULL to ignore)
	 * @param[out] packets	number of processed packets (NULL to ignore)
	 */
	void (*get_usestats)(child_sa_t *this, bool inbound, time_t *time,
						 uint64_t *bytes, uint64_t *packets);

	/**
	 * Get the mark used with this CHILD_SA.
	 *
	 * @param inbound		TRUE to get inbound mark, FALSE for outbound
	 * @return				mark used with this CHILD_SA
	 */
	mark_t (*get_mark)(child_sa_t *this, bool inbound);

	/**
	 * Create an enumerator over traffic selectors of one side.
	 *
	 * @param local		TRUE for own traffic selectors, FALSE for remote.
	 * @return			enumerator over traffic_selector_t*
	 */
	enumerator_t* (*create_ts_enumerator)(child_sa_t *this, bool local);

	/**
	 * Create an enumerator over installed policies.
	 *
	 * The enumerated traffic selectors is a full mesh of compatible local
	 * and remote traffic selectors.
	 *
	 * @return			enumerator over a pair of traffic_selector_t*
	 */
	enumerator_t* (*create_policy_enumerator)(child_sa_t *this);

	/**
	 * Allocate an SPI to include in a proposal.
	 *
	 * @param protocol	protocol to allocate SPI for (ESP|AH)
	 * @param spi		SPI output pointer
	 * @return			SPI, 0 on failure
	 */
	uint32_t (*alloc_spi)(child_sa_t *this, protocol_id_t protocol);

	/**
	 * Allocate a CPI to use for IPComp.
	 *
	 * @return			CPI, 0 on failure
	 */
	uint16_t (*alloc_cpi)(child_sa_t *this);

	/**
	 * Install an IPsec SA for one direction.
	 *
	 * set_policies() should be called before calling this.
	 *
	 * @param encr		encryption key, if any
	 * @param integ		integrity key
	 * @param spi		SPI to use, allocated for inbound
	 * @param cpi		CPI to use, allocated for outbound
	 * @param initiator	TRUE if initiator of exchange resulting in this SA
	 * @param inbound	TRUE to install an inbound SA, FALSE for outbound
	 * @param tfcv3		TRUE if peer supports ESPv3 TFC
	 * @return			SUCCESS or FAILED
	 */
	status_t (*install)(child_sa_t *this, chunk_t encr, chunk_t integ,
						uint32_t spi, uint16_t cpi,
						bool initiator, bool inbound, bool tfcv3);

	/**
	 * Register data for the installation of an outbound SA as responder during
	 * a rekeying.
	 *
	 * If the kernel is able to handle SPIs on policies the SA is installed
	 * immediately, if not it won't be installed until install_outbound() is
	 * called.
	 *
	 * @param encr		encryption key, if any (cloned)
	 * @param integ		integrity key (cloned)
	 * @param spi		SPI to use, allocated for inbound
	 * @param cpi		CPI to use, allocated for outbound
	 * @param tfcv3		TRUE if peer supports ESPv3 TFC
	 * @return			SUCCESS or FAILED
	 */
	status_t (*register_outbound)(child_sa_t *this, chunk_t encr, chunk_t integ,
								  uint32_t spi, uint16_t cpi, bool tfcv3);

	/**
	 * Install the outbound policies and, if not already done, the outbound SA
	 * as responder during a rekeying.
	 *
	 * @return			SUCCESS or FAILED
	 */
	status_t (*install_outbound)(child_sa_t *this);

	/**
	 * Remove the outbound SA and the outbound policies after a rekeying.
	 */
	void (*remove_outbound)(child_sa_t *this);

	/**
	 * Configure the policies using some traffic selectors.
	 *
	 * Supplied lists of traffic_selector_t's specify the policies
	 * to use for this child sa.
	 *
	 * Install the policies by calling install_policies().
	 *
	 * This should be called before calling install() so the traffic selectors
	 * may be passed to the kernel interface when installing the SAs.
	 *
	 * @param my_ts		traffic selectors for local site (cloned)
	 * @param other_ts	traffic selectors for remote site (cloned)
	 */
	void (*set_policies)(child_sa_t *this, linked_list_t *my_ts_list,
						 linked_list_t *other_ts_list);

	/**
	 * Install the configured policies.
	 *
	 * If register_outbound() was called previously this only installs the
	 * inbound and forward policies, the outbound policies are installed when
	 * install_outbound() is called.
	 *
	 * @return			SUCCESS or FAILED
	 */
	status_t (*install_policies)(child_sa_t *this);

	/**
	 * Set the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
	 * a rekeying.
	 *
	 * @param spi		outbound SPI of the CHILD_SA that replaced this CHILD_SA
	 */
	void (*set_rekey_spi)(child_sa_t *this, uint32_t spi);

	/**
	 * Get the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
	 * a rekeying.
	 *
	 * @return			outbound SPI of the CHILD_SA that replaced this CHILD_SA
	 */
	uint32_t (*get_rekey_spi)(child_sa_t *this);

	/**
	 * Update hosts and ecapulation mode in the kernel SAs and policies.
	 *
	 * @param me		the new local host
	 * @param other		the new remote host
	 * @param vips		list of local virtual IPs
	 * @param encap		TRUE to use UDP encapsulation for NAT traversal
	 * @return			SUCCESS or FAILED
	 */
	status_t (*update)(child_sa_t *this, host_t *me, host_t *other,
					   linked_list_t *vips, bool encap);
	/**
	 * Destroys a child_sa.
	 */
	void (*destroy) (child_sa_t *this);
};

/**
 * Constructor to create a child SA negotiated with IKE.
 *
 * @param me				own address
 * @param other				remote address
 * @param config			config to use for this CHILD_SA
 * @param reqid				reqid of old CHILD_SA when rekeying, 0 otherwise
 * @param encap				TRUE to enable UDP encapsulation (NAT traversal)
 * @param mark_in			explicit inbound mark value to use, 0 for config
 * @param mark_out			explicit outbound mark value to use, 0 for config
 * @return					child_sa_t object
 */
child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
							 uint32_t reqid, bool encap,
							 u_int mark_in, u_int mark_out);

#endif /** CHILD_SA_H_ @}*/