summaryrefslogtreecommitdiff
path: root/src/charon/kernel/kernel_interface.h
blob: 256c207978faba9eaa449b4b41b9518d693102a7 (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
/**
 * @file kernel_interface.h
 *
 * @brief Interface of kernel_interface_t.
 *
 */

/*
 * Copyright (C) 2006 Tobias Brunner, Daniel Roethlisberger
 * Copyright (C) 2005-2006 Martin Willi
 * Copyright (C) 2005 Jan Hutter
 * 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.
 */

#ifndef KERNEL_INTERFACE_H_
#define KERNEL_INTERFACE_H_

typedef enum policy_dir_t policy_dir_t;
typedef struct kernel_interface_t kernel_interface_t;

#include <utils/host.h>
#include <crypto/prf_plus.h>
#include <encoding/payloads/proposal_substructure.h>


/**
 * Direction of a policy. These are equal to those
 * defined in xfrm.h, but we want to stay implementation
 * neutral here.
 *
 * @ingroup kernel
 */
enum policy_dir_t {
	/** Policy for inbound traffic */
	POLICY_IN = 0,
	/** Policy for outbound traffic */
	POLICY_OUT = 1,
	/** Policy for forwarded traffic */
	POLICY_FWD = 2,
};

/**
 * @brief Interface to the kernel.
 * 
 * The kernel interface handles the communication with the kernel
 * for SA and policy management. It allows setup of these, and provides 
 * further the handling of kernel events.
 * Policy information are cached in the interface. This is necessary to do
 * reference counting. The Linux kernel does not allow the same policy
 * installed twice, but we need this as CHILD_SA exist multiple times
 * when rekeying. Thats why we do reference counting of policies.
 *
 * @b Constructors:
 *  - kernel_interface_create()
 *
 * @ingroup kernel
 */
struct kernel_interface_t {

	/**
	 * @brief Get a SPI from the kernel.
	 *
	 * @warning get_spi() implicitely creates an SA with
	 * the allocated SPI, therefore the replace flag
	 * in add_sa() must be set when installing this SA.
	 * 
	 * @param this		calling object
	 * @param src		source address of SA
	 * @param dst		destination address of SA
	 * @param protocol	protocol for SA (ESP/AH)
	 * @param reqid		unique ID for this SA
	 * @param[out] spi	allocated spi
	 * @return
	 * 					- SUCCESS
	 * 					- FAILED if kernel comm failed
	 */
	status_t (*get_spi)(kernel_interface_t *this, host_t *src, host_t *dst, 
						protocol_id_t protocol, u_int32_t reqid, u_int32_t *spi);
	
	/**
	 * @brief Add an SA to the SAD.
	 * 
	 * add_sa() may update an already allocated
	 * SPI (via get_spi). In this case, the replace
	 * flag must be set.
	 * This function does install a single SA for a
	 * single protocol in one direction. The kernel-interface
	 * gets the keys itself from the PRF, as we don't know
	 * his algorithms and key sizes.
	 * 
	 * @param this			calling object
	 * @param src			source address for this SA
	 * @param dst			destination address for this SA
	 * @param spi			SPI allocated by us or remote peer
	 * @param protocol		protocol for this SA (ESP/AH)
	 * @param reqid			unique ID for this SA
	 * @param expire_soft	lifetime in seconds before rekeying
	 * @param expire_hard	lieftime in seconds before delete
	 * @param enc_alg		Algorithm to use for encryption (ESP only)
	 * @param int_alg		Algorithm to use for integrity protection
	 * @param prf_plus		PRF to derive keys from
	 * @param mode			mode of the SA (tunnel, transport)
	 * @param encap			enable UDP encapsulation for NAT traversal
	 * @param replace		Should an already installed SA be updated?
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*add_sa) (kernel_interface_t *this,
						host_t *src, host_t *dst, u_int32_t spi,
						protocol_id_t protocol, u_int32_t reqid,
						u_int64_t expire_soft, u_int64_t expire_hard,
						algorithm_t *enc_alg, algorithm_t *int_alg,
						prf_plus_t *prf_plus, mode_t mode, bool encap,
						bool update);
	
	/**
	 * @brief Update the hosts on an installed SA.
	 *
	 * We cannot directly update the destination address as the kernel
	 * requires the spi, the protocol AND the destination address (and family)
	 * to identify SAs. Therefore if the destination address changed we
	 * create a new SA and delete the old one.
	 *
	 * @param this			calling object
	 * @param spi			SPI of the SA
	 * @param protocol		protocol for this SA (ESP/AH)
	 * @param src			current source address
	 * @param dst			current destination address
	 * @param new_src		new source address
	 * @param new_dst		new destination address
	 * @param encap			use UDP encapsulation
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*update_sa)(kernel_interface_t *this,
						  u_int32_t spi, protocol_id_t protocol,
						  host_t *src, host_t *dst, 
						  host_t *new_src, host_t *new_dst, bool encap);
	
	/**
	 * @brief Query the use time of an SA.
	 *
	 * The use time of an SA is not the time of the last usage, but 
	 * the time of the first usage of the SA.
	 * 
	 * @param this			calling object
	 * @param dst			destination address for this SA
	 * @param spi			SPI allocated by us or remote peer
	 * @param protocol		protocol for this SA (ESP/AH)
	 * @param[out] use_time	the time of this SA's last use
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*query_sa) (kernel_interface_t *this, host_t *dst, u_int32_t spi, 
						  protocol_id_t protocol, u_int32_t *use_time);
	
	/**
	 * @brief Delete a previusly installed SA from the SAD.
	 * 
	 * @param this			calling object
	 * @param dst			destination address for this SA
	 * @param spi			SPI allocated by us or remote peer
	 * @param protocol		protocol for this SA (ESP/AH)
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*del_sa) (kernel_interface_t *this, host_t *dst, u_int32_t spi,
						protocol_id_t protocol);
	
	/**
	 * @brief Add a policy to the SPD.
	 * 
	 * A policy is always associated to an SA. Traffic which matches a
	 * policy is handled by the SA with the same reqid.
	 * 
	 * @param this			calling object
	 * @param src			source address of SA
	 * @param dst			dest address of SA
	 * @param src_ts		traffic selector to match traffic source
	 * @param dst_ts		traffic selector to match traffic dest
	 * @param direction		direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
	 * @param protocol		protocol to use to protect traffic (AH/ESP)
	 * @param reqid			uniqe ID of an SA to use to enforce policy
	 * @param high_prio		if TRUE, uses a higher priority than any with FALSE
	 * @param mode			mode of SA (tunnel, transport)
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*add_policy) (kernel_interface_t *this,
							host_t *src, host_t *dst,
							traffic_selector_t *src_ts,
							traffic_selector_t *dst_ts,
							policy_dir_t direction, protocol_id_t protocol,
							u_int32_t reqid, bool high_prio, mode_t mode);
	
	/**
	 * @brief Query the use time of a policy.
	 *
	 * The use time of a policy is the time the policy was used
	 * for the last time.
	 * 
	 * @param this			calling object
	 * @param src_ts		traffic selector to match traffic source
	 * @param dst_ts		traffic selector to match traffic dest
	 * @param direction		direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
	 * @param[out] use_time	the time of this SA's last use
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*query_policy) (kernel_interface_t *this,
							  traffic_selector_t *src_ts, 
							  traffic_selector_t *dst_ts,
							  policy_dir_t direction, u_int32_t *use_time);
	
	/**
	 * @brief Remove a policy from the SPD.
	 *
	 * The kernel interface implements reference counting for policies.
	 * If the same policy is installed multiple times (in the case of rekeying),
	 * the reference counter is increased. del_policy() decreases the ref counter
	 * and removes the policy only when no more references are available.
	 *
	 * @param this			calling object
	 * @param src_ts		traffic selector to match traffic source
	 * @param dst_ts		traffic selector to match traffic dest
	 * @param direction		direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*del_policy) (kernel_interface_t *this,
							traffic_selector_t *src_ts, 
							traffic_selector_t *dst_ts,
							policy_dir_t direction);
	
	/**
	 * @brief Get our outgoing source address for a destination.
	 *
	 * Does a route lookup to get the source address used to reach dest.
	 * The returned host is allocated and must be destroyed.
	 *
	 * @param this			calling object
	 * @param dest			target destination address
	 * @return				outgoing source address, NULL if unreachable
	 */
	host_t* (*get_source_addr)(kernel_interface_t *this, host_t *dest);
	
	/**
	 * @brief Get the interface name of a local address.
	 *
	 * @param this			calling object
	 * @param host			address to get interface name from
	 * @return 				allocated interface name, or NULL if not found
	 */
	char* (*get_interface) (kernel_interface_t *this, host_t *host);
	
	/**
	 * @brief Creates an iterator over all local addresses.
	 *
	 * This function blocks an internal cached address list until the
	 * iterator gets destroyed.
	 * These hosts are read-only, do not modify or free.
	 *
	 * @param this			calling object
	 * @return 				iterator over host_t's
	 */
	iterator_t *(*create_address_iterator) (kernel_interface_t *this);
	
	/**
	 * @brief Add a virtual IP to an interface.
	 *
	 * Virtual IPs are attached to an interface. If an IP is added multiple
	 * times, the IP is refcounted and not removed until del_ip() was called
	 * as many times as add_ip().
	 * The virtual IP is attached to the interface where the iface_ip is found.
	 *
	 * @param this			calling object
	 * @param virtual_ip	virtual ip address to assign
	 * @param iface_ip		IP of an interface to attach virtual IP
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*add_ip) (kernel_interface_t *this, host_t *virtual_ip,
						host_t *iface_ip);
	
	/**
	 * @brief Remove a virtual IP from an interface.
	 *
	 * The kernel interface uses refcounting, see add_ip().
	 *
	 * @param this			calling object
	 * @param virtual_ip	virtual ip address to assign
	 * @return
	 * 						- SUCCESS
	 * 						- FAILED if kernel comm failed
	 */
	status_t (*del_ip) (kernel_interface_t *this, host_t *virtual_ip);
	
	/**
	 * @brief Destroys a kernel_interface object.
	 *
	 * @param kernel_interface_t 	calling object
	 */
	void (*destroy) (kernel_interface_t *kernel_interface);
};

/**
 * @brief Creates an object of type kernel_interface_t.
 * 
 * @ingroup kernel
 */
kernel_interface_t *kernel_interface_create(void);

#endif /*KERNEL_INTERFACE_H_*/