ikev2: Add possibility to delay initiation of a queued task
[strongswan.git] / src / libcharon / sa / task_manager.h
1 /*
2 * Copyright (C) 2013-2016 Tobias Brunner
3 * Copyright (C) 2006 Martin Willi
4 * HSR Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup task_manager task_manager
19 * @{ @ingroup sa
20 */
21
22 #ifndef TASK_MANAGER_H_
23 #define TASK_MANAGER_H_
24
25 typedef struct task_manager_t task_manager_t;
26 typedef enum task_queue_t task_queue_t;
27
28 #include <limits.h>
29
30 #include <library.h>
31 #include <encoding/message.h>
32 #include <sa/ike_sa.h>
33 #include <sa/task.h>
34
35 /**
36 * First retransmit timeout in seconds.
37 */
38 #define RETRANSMIT_TIMEOUT 4.0
39
40 /**
41 * Base which is raised to the power of the retransmission try.
42 */
43 #define RETRANSMIT_BASE 1.8
44
45 /**
46 * Number of retransmits done before giving up.
47 */
48 #define RETRANSMIT_TRIES 5
49
50 /**
51 * Interval for mobike routability checks in ms.
52 */
53 #define ROUTEABILITY_CHECK_INTERVAL 2500
54
55 /**
56 * Number of routability checks before giving up
57 */
58 #define ROUTEABILITY_CHECK_TRIES 10
59
60 /**
61 * Type of task queues the task manager uses to handle tasks
62 */
63 enum task_queue_t {
64 /** tasks currently active, initiated by us */
65 TASK_QUEUE_ACTIVE,
66 /** passive tasks initiated by the remote peer */
67 TASK_QUEUE_PASSIVE,
68 /** tasks queued for initiated, but not yet activated */
69 TASK_QUEUE_QUEUED,
70 };
71
72 /**
73 * The task manager, juggles task and handles message exchanges.
74 *
75 * On incoming requests, the task manager creates new tasks on demand and
76 * juggles the request through all available tasks. Each task inspects the
77 * request and adds payloads as necessary to the response.
78 * On outgoing requests, the task manager delivers the request through the tasks
79 * to build it, the response gets processed by each task to complete.
80 * The task manager has an internal Queue to store task which should get
81 * completed.
82 * For the initial IKE_SA setup, several tasks are queued: One for the
83 * unauthenticated IKE_SA setup, one for authentication, one for CHILD_SA setup
84 * and maybe one for virtual IP assignement.
85 * The task manager is also responsible for retransmission. It uses a backoff
86 * algorithm. The timeout is calculated using
87 * RETRANSMIT_TIMEOUT * (RETRANSMIT_BASE ** try).
88 * When try reaches RETRANSMIT_TRIES, retransmission is given up.
89 *
90 * Using an initial TIMEOUT of 4s, a BASE of 1.8, and 5 TRIES gives us:
91 * @verbatim
92 | relative | absolute
93 ---------------------------------------------------------
94 4s * (1.8 ** 0) = 4s 4s
95 4s * (1.8 ** 1) = 7s 11s
96 4s * (1.8 ** 2) = 13s 24s
97 4s * (1.8 ** 3) = 23s 47s
98 4s * (1.8 ** 4) = 42s 89s
99 4s * (1.8 ** 5) = 76s 165s
100
101 @endverbatim
102 * The peer is considered dead after 2min 45s when no reply comes in.
103 */
104 struct task_manager_t {
105
106 /**
107 * Process an incoming message.
108 *
109 * @param message message to add payloads to
110 * @return
111 * - DESTROY_ME if IKE_SA must be closed
112 * - SUCCESS otherwise
113 */
114 status_t (*process_message) (task_manager_t *this, message_t *message);
115
116 /**
117 * Initiate an exchange with the currently queued tasks.
118 */
119 status_t (*initiate) (task_manager_t *this);
120
121 /**
122 * Queue a task in the manager.
123 *
124 * @param task task to queue
125 */
126 void (*queue_task)(task_manager_t *this, task_t *task);
127
128 /**
129 * Queue a task in the manager, but delay its initiation for at least the
130 * given number of seconds.
131 *
132 * @param task task to queue
133 * @param delay minimum delay in s before initiating the task
134 */
135 void (*queue_task_delayed)(task_manager_t *this, task_t *task,
136 uint32_t delay);
137
138 /**
139 * Queue IKE_SA establishing tasks.
140 */
141 void (*queue_ike)(task_manager_t *this);
142
143 /**
144 * Queue IKE_SA rekey tasks.
145 */
146 void (*queue_ike_rekey)(task_manager_t *this);
147
148 /**
149 * Queue IKE_SA reauth tasks.
150 */
151 void (*queue_ike_reauth)(task_manager_t *this);
152
153 /**
154 * Queue MOBIKE task
155 *
156 * @param roam TRUE to switch to new address
157 * @param address TRUE to include address list update
158 */
159 void (*queue_mobike)(task_manager_t *this, bool roam, bool address);
160
161 /**
162 * Queue IKE_SA delete tasks.
163 */
164 void (*queue_ike_delete)(task_manager_t *this);
165
166 /**
167 * Queue CHILD_SA establishing tasks.
168 *
169 * @param cfg CHILD_SA config to establish
170 * @param reqid reqid to use for CHILD_SA
171 * @param tsi initiator traffic selector, if packet-triggered
172 * @param tsr responder traffic selector, if packet-triggered
173 */
174 void (*queue_child)(task_manager_t *this, child_cfg_t *cfg, uint32_t reqid,
175 traffic_selector_t *tsi, traffic_selector_t *tsr);
176
177 /**
178 * Queue CHILD_SA rekeying tasks.
179 *
180 * @param protocol CHILD_SA protocol, AH|ESP
181 * @param spi CHILD_SA SPI to rekey
182 */
183 void (*queue_child_rekey)(task_manager_t *this, protocol_id_t protocol,
184 uint32_t spi);
185
186 /**
187 * Queue CHILD_SA delete tasks.
188 *
189 * @param protocol CHILD_SA protocol, AH|ESP
190 * @param spi CHILD_SA SPI to rekey
191 * @param expired TRUE if SA already expired
192 */
193 void (*queue_child_delete)(task_manager_t *this, protocol_id_t protocol,
194 uint32_t spi, bool expired);
195
196 /**
197 * Queue liveness checking tasks.
198 */
199 void (*queue_dpd)(task_manager_t *this);
200
201 /**
202 * Retransmit a request if it hasn't been acknowledged yet.
203 *
204 * A return value of INVALID_STATE means that the message was already
205 * acknowledged and has not to be retransmitted. A return value of SUCCESS
206 * means retransmission was required and the message has been resent.
207 *
208 * @param message_id ID of the message to retransmit
209 * @return
210 * - INVALID_STATE if retransmission not required
211 * - SUCCESS if retransmission sent
212 */
213 status_t (*retransmit) (task_manager_t *this, uint32_t message_id);
214
215 /**
216 * Migrate all queued tasks from other to this.
217 *
218 * To rekey or reestablish an IKE_SA completely, all queued or active
219 * tasks should get migrated to the new IKE_SA.
220 *
221 * @param other manager which gives away its tasks
222 */
223 void (*adopt_tasks) (task_manager_t *this, task_manager_t *other);
224
225 /**
226 * Migrate all active or queued CHILD_SA-creating tasks from other to this.
227 *
228 * @param other manager which gives away its tasks
229 */
230 void (*adopt_child_tasks) (task_manager_t *this, task_manager_t *other);
231
232 /**
233 * Increment a message ID counter, in- or outbound.
234 *
235 * If a message is processed outside of the manager, this call increments
236 * the message ID counters of the task manager.
237 *
238 * @param inititate TRUE to increment the initiating ID
239 */
240 void (*incr_mid)(task_manager_t *this, bool initiate);
241
242 /**
243 * Reset message ID counters of the task manager.
244 *
245 * The IKEv2 protocol requires to restart exchanges with message IDs
246 * reset to zero (INVALID_KE_PAYLOAD, COOKIES, ...). The reset() method
247 * resets the message IDs and resets all active tasks using the migrate()
248 * method.
249 * Use a value of UINT_MAX to keep the current message ID.
250 * For IKEv1, the arguments do not set the message ID, but the DPD sequence
251 * number counters.
252 *
253 * @param initiate message ID / DPD seq to initiate exchanges (send)
254 * @param respond message ID / DPD seq to respond to exchanges (expect)
255 */
256 void (*reset) (task_manager_t *this, uint32_t initiate, uint32_t respond);
257
258 /**
259 * Check if we are currently waiting for a reply.
260 *
261 * @return TRUE if we are waiting, FALSE otherwise
262 */
263 bool (*busy) (task_manager_t *this);
264
265 /**
266 * Create an enumerator over tasks in a specific queue.
267 *
268 * @param queue queue to create an enumerator over
269 * @return enumerator over task_t
270 */
271 enumerator_t* (*create_task_enumerator)(task_manager_t *this,
272 task_queue_t queue);
273
274 /**
275 * Flush all tasks, regardless of the queue.
276 */
277 void (*flush)(task_manager_t *this);
278
279 /**
280 * Flush a queue, cancelling all tasks.
281 *
282 * @param queue queue to flush
283 */
284 void (*flush_queue)(task_manager_t *this, task_queue_t queue);
285
286 /**
287 * Destroy the task_manager_t.
288 */
289 void (*destroy) (task_manager_t *this);
290 };
291
292 /**
293 * Create a task manager instance for the correct IKE version.
294 *
295 * @param ike_sa IKE_SA to create a task manager for
296 * @return task manager implementation for IKE version
297 */
298 task_manager_t *task_manager_create(ike_sa_t *ike_sa);
299
300 #endif /** TASK_MANAGER_H_ @}*/