add priority management for kernel policy
[strongswan.git] / src / charon / config / policies / policy.h
1 /**
2 * @file policy.h
3 *
4 * @brief Interface of policy_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef POLICY_H_
25 #define POLICY_H_
26
27 #include <types.h>
28 #include <utils/identification.h>
29 #include <config/traffic_selector.h>
30 #include <config/proposal.h>
31 #include <encoding/payloads/auth_payload.h>
32
33
34 typedef enum dpd_action_t dpd_action_t;
35
36 /**
37 * @brief Actions to take when a peer does not respond (dead peer detected).
38 *
39 * These values are the same as in pluto/starter, so do not modify them!
40 *
41 * @ingroup config
42 */
43 enum dpd_action_t {
44 /** remove CHILD_SA without replacement */
45 DPD_CLEAR = 1,
46 /** route the CHILD_SA to resetup when needed */
47 DPD_ROUTE = 2,
48 /** restart CHILD_SA in a new IKE_SA, immediately */
49 DPD_RESTART = 3,
50 };
51
52 /**
53 * String mappings for dpd_action_t
54 */
55 extern mapping_t dpd_action_m[];
56
57
58 typedef struct policy_t policy_t;
59
60 /**
61 * @brief A policy_t defines the policies to apply to CHILD_SAs.
62 *
63 * The given two IDs identify a policy. These rules define how
64 * child SAs may be set up and which traffic may be IPsec'ed.
65 *
66 * @b Constructors:
67 * - policy_create()
68 *
69 * @ingroup config
70 */
71 struct policy_t {
72
73 /**
74 * @brief Get the name of the policy.
75 *
76 * Returned object is not getting cloned.
77 *
78 * @param this calling object
79 * @return policy's name
80 */
81 char *(*get_name) (policy_t *this);
82
83 /**
84 * @brief Get own id to use for identification.
85 *
86 * Returned object is not getting cloned.
87 *
88 * @param this calling object
89 * @return own id
90 */
91 identification_t *(*get_my_id) (policy_t *this);
92
93 /**
94 * @brief Get id of communication partner.
95 *
96 * Returned object is not getting cloned.
97 *
98 * @param this calling object
99 * @return other id
100 */
101 identification_t *(*get_other_id) (policy_t *this);
102
103 /**
104 * @brief Get configured traffic selectors for our site.
105 *
106 * Returns a list with all traffic selectors for the local
107 * site. List and items must be destroyed after usage.
108 *
109 * @param this calling object
110 * @return list with traffic selectors
111 */
112 linked_list_t *(*get_my_traffic_selectors) (policy_t *this, host_t *me);
113
114 /**
115 * @brief Get configured traffic selectors for others site.
116 *
117 * Returns a list with all traffic selectors for the remote
118 * site. List and items must be destroyed after usage.
119 *
120 * @param this calling object
121 * @return list with traffic selectors
122 */
123 linked_list_t *(*get_other_traffic_selectors) (policy_t *this, host_t* other);
124
125 /**
126 * @brief Select traffic selectors from a supplied list for local site.
127 *
128 * Resulted list and traffic selectors must be destroyed after usage.
129 * As the traffic selectors may contain a wildcard address (0.0.0.0) for
130 * addresses we don't know in previous, an address may be supplied to
131 * replace these 0.0.0.0 addresses on-the-fly.
132 *
133 * @param this calling object
134 * @param supplied linked list with traffic selectors
135 * @param me host address used by us
136 * @return list containing the selected traffic selectors
137 */
138 linked_list_t *(*select_my_traffic_selectors) (policy_t *this,
139 linked_list_t *supplied,
140 host_t *me);
141
142 /**
143 * @brief Select traffic selectors from a supplied list for remote site.
144 *
145 * Resulted list and traffic selectors must be destroyed after usage.
146 * As the traffic selectors may contain a wildcard address (0.0.0.0) for
147 * addresses we don't know in previous, an address may be supplied to
148 * replace these 0.0.0.0 addresses on-the-fly.
149 *
150 * @param this calling object
151 * @param supplied linked list with traffic selectors
152 * @return list containing the selected traffic selectors
153 */
154 linked_list_t *(*select_other_traffic_selectors) (policy_t *this,
155 linked_list_t *supplied,
156 host_t *other);
157
158 /**
159 * @brief Get the list of internally stored proposals.
160 *
161 * policy_t does store proposals for AH/ESP, IKE proposals are in
162 * the connection_t.
163 * Resulting list and all of its proposals must be freed after usage.
164 *
165 * @param this calling object
166 * @return lists with proposals
167 */
168 linked_list_t *(*get_proposals) (policy_t *this);
169
170 /**
171 * @brief Select a proposal from a supplied list.
172 *
173 * Returned propsal is newly created and must be destroyed after usage.
174 *
175 * @param this calling object
176 * @param proposals list from from wich proposals are selected
177 * @return selected proposal, or NULL if nothing matches
178 */
179 proposal_t *(*select_proposal) (policy_t *this, linked_list_t *proposals);
180
181 /**
182 * @brief Add a traffic selector to the list for local site.
183 *
184 * After add, traffic selector is owned by policy.
185 *
186 * @param this calling object
187 * @param traffic_selector traffic_selector to add
188 */
189 void (*add_my_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector);
190
191 /**
192 * @brief Add a traffic selector to the list for remote site.
193 *
194 * After add, traffic selector is owned by policy.
195 *
196 * @param this calling object
197 * @param traffic_selector traffic_selector to add
198 */
199 void (*add_other_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector);
200
201 /**
202 * @brief Add a proposal to the list.
203 *
204 * The proposals are stored by priority, first added
205 * is the most prefered.
206 * After add, proposal is owned by policy.
207 *
208 * @param this calling object
209 * @param proposal proposal to add
210 */
211 void (*add_proposal) (policy_t *this, proposal_t *proposal);
212
213 /**
214 * @brief Add certification authorities.
215 *
216 * @param this calling object
217 * @param my_ca issuer of my certificate
218 * @param other_ca required issuer of the peer's certificate
219 */
220 void (*add_authorities) (policy_t *this, identification_t *my_ca, identification_t *other_ca);
221
222 /**
223 * @brief Get updown script
224 *
225 * @param this calling object
226 * @return path to updown script
227 */
228 char* (*get_updown) (policy_t *this);
229
230 /**
231 * @brief What should be done with a CHILD_SA, when other peer does not respond.
232 *
233 * @param this calling object
234 * @return dpd action
235 */
236 dpd_action_t (*get_dpd_action) (policy_t *this);
237
238 /**
239 * @brief Get the lifetime of a policy, before rekeying starts.
240 *
241 * A call to this function automatically adds a jitter to
242 * avoid simultanous rekeying.
243 *
244 * @param this policy
245 * @return lifetime in seconds
246 */
247 u_int32_t (*get_soft_lifetime) (policy_t *this);
248
249 /**
250 * @brief Get the lifetime of a policy, before SA gets deleted.
251 *
252 * @param this policy
253 * @return lifetime in seconds
254 */
255 u_int32_t (*get_hard_lifetime) (policy_t *this);
256
257 /**
258 * @brief Get a new reference.
259 *
260 * Get a new reference to this policy by increasing
261 * it's internal reference counter.
262 * Do not call get_ref or any other function until you
263 * already have a reference. Otherwise the object may get
264 * destroyed while calling get_ref(),
265 *
266 * @param this calling object
267 */
268 void (*get_ref) (policy_t *this);
269
270 /**
271 * @brief Destroys the policy object.
272 *
273 * Decrements the internal reference counter and
274 * destroys the policy when it reaches zero.
275 *
276 * @param this calling object
277 */
278 void (*destroy) (policy_t *this);
279 };
280
281 /**
282 * @brief Create a configuration object for IKE_AUTH and later.
283 *
284 * name-string gets cloned, ID's not.
285 * Lifetimes are in seconds. To prevent to peers to start rekeying at the
286 * same time, a jitter may be specified. Rekeying of an SA starts at
287 * (soft_lifetime - random(0, jitter)). After a successful rekeying,
288 * the hard_lifetime limit counter is reset. You should specify
289 * hard_lifetime > soft_lifetime > jitter.
290 * After a call to create, a reference is obtained (refcount = 1).
291 *
292 * @param name name of the policy
293 * @param my_id identification_t for ourselves
294 * @param other_id identification_t for the remote guy
295 * @param hard_lifetime lifetime before deleting an SA
296 * @param soft_lifetime lifetime before rekeying an SA
297 * @param jitter range of randomization time
298 * @param updown updown script to execute on up/down event
299 * @param dpd_action what to to with a CHILD_SA when other peer does not respond
300 * @return policy_t object
301 *
302 * @ingroup config
303 */
304 policy_t *policy_create(char *name,
305 identification_t *my_id, identification_t *other_id,
306 u_int32_t hard_lifetime, u_int32_t soft_lifetime,
307 u_int32_t jitter, char *updown, dpd_action_t dpd_action);
308
309 #endif /* POLICY_H_ */