implemented clean spi allocation behavior when using multiple proposals
[strongswan.git] / src / charon / sa / ike_sa.h
1 /**
2 * @file ike_sa.h
3 *
4 * @brief Interface of ike_sa_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005 Jan Hutter, Martin Willi
10 * Hochschule fuer Technik Rapperswil
11 *
12 * This program is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License as published by the
14 * Free Software Foundation; either version 2 of the License, or (at your
15 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * for more details.
21 */
22
23 #ifndef IKE_SA_H_
24 #define IKE_SA_H_
25
26 #include <types.h>
27 #include <encoding/message.h>
28 #include <encoding/payloads/proposal_substructure.h>
29 #include <sa/ike_sa_id.h>
30 #include <sa/child_sa.h>
31 #include <sa/states/state.h>
32 #include <config/configuration.h>
33 #include <utils/logger.h>
34 #include <utils/randomizer.h>
35 #include <crypto/prfs/prf.h>
36 #include <crypto/crypters/crypter.h>
37 #include <crypto/signers/signer.h>
38 #include <config/connections/connection.h>
39 #include <config/policies/policy.h>
40 #include <utils/logger.h>
41
42 /**
43 * Nonce size in bytes for nonces sending to other peer.
44 *
45 * @warning Nonce size MUST be between 16 and 256 bytes.
46 *
47 * @ingroup sa
48 */
49 #define NONCE_SIZE 16
50
51
52 typedef struct ike_sa_t ike_sa_t;
53
54 /**
55 * @brief Class ike_sa_t representing an IKE_SA.
56 *
57 * An object of this type is managed by an ike_sa_manager_t object
58 * and represents an IKE_SA. Message processing is split up in different states.
59 * They will handle all related things for the state they represent.
60 *
61 * @b Constructors:
62 * - ike_sa_create()
63 *
64 * @ingroup sa
65 */
66 struct ike_sa_t {
67
68 /**
69 * @brief Processes a incoming IKEv2-Message of type message_t.
70 *
71 * @param this ike_sa_t object object
72 * @param[in] message message_t object to process
73 * @return
74 * - SUCCESS
75 * - FAILED
76 * - DESTROY_ME if this IKE_SA MUST be deleted
77 */
78 status_t (*process_message) (ike_sa_t *this,message_t *message);
79
80 /**
81 * @brief Initiate a new connection with given connection_t object.
82 *
83 * The connection_t object is owned by the IKE_SA after the call, so
84 * do not modify or destroy it.
85 *
86 * @param this calling object
87 * @param connection connection to initiate
88 * @return
89 * - SUCCESS if initialization started
90 * - FAILED if in wrong state
91 * - DESTROY_ME if initialization failed and IKE_SA MUST be deleted
92 */
93 status_t (*initiate_connection) (ike_sa_t *this, connection_t *connection);
94
95 /**
96 * @brief Retransmits a request.
97 *
98 * @param this calling object
99 * @param message_id ID of the request to retransmit
100 * @return
101 * - SUCCESS
102 * - NOT_FOUND if request doesn't have to be retransmited
103 */
104 status_t (*retransmit_request) (ike_sa_t *this, u_int32_t message_id);
105
106 /**
107 * @brief Get the id of the SA.
108 *
109 * Returned ike_sa_id_t object is not getting cloned!
110 *
111 * @param this calling object
112 * @return ike_sa's ike_sa_id_t
113 */
114 ike_sa_id_t* (*get_id) (ike_sa_t *this);
115
116 /**
117 * @brief Get the CHILD_SA with the specified reqid.
118 *
119 * The reqid is a unique ID for a child SA, which is
120 * generated on child SA creation.
121 * Returned child_sa_t object is not cloned!
122 *
123 * @param this calling object
124 * @param reqid reqid of the child SA, as used in the kernel
125 * @return child_sa, or NULL if not found
126 */
127 child_sa_t* (*get_child_sa) (ike_sa_t *this, u_int32_t reqid);
128
129 /**
130 * @brief Close the CHILD SA with the specified reqid.
131 *
132 * Looks for a CHILD SA owned by this IKE_SA, deletes it and
133 * notify's the remote peer about the delete. The associated
134 * states and policies in the kernel get deleted, if they exist.
135 *
136 * @param this calling object
137 * @param reqid reqid of the child SA, as used in the kernel
138 * @return
139 * - NOT_FOUND, if IKE_SA has no such CHILD_SA
140 * - SUCCESS, if deleted and delete message sent
141 */
142 status_t (*delete_child_sa) (ike_sa_t *this, u_int32_t reqid);
143
144 /**
145 * @brief Rekey the CHILD SA with the specified reqid.
146 *
147 * Looks for a CHILD SA owned by this IKE_SA, and start the rekeing.
148 *
149 * @param this calling object
150 * @param spi security parameter index identifying the SA to rekey
151 * @return
152 * - NOT_FOUND, if IKE_SA has no such CHILD_SA
153 * - SUCCESS, if rekeying initiated
154 */
155 status_t (*rekey_child_sa) (ike_sa_t *this, u_int32_t reqid);
156
157 /**
158 * @brief Get local peer address of the IKE_SA.
159 *
160 * @param this calling object
161 * @return local host_t
162 */
163 host_t* (*get_my_host) (ike_sa_t *this);
164
165 /**
166 * @brief Get remote peer address of the IKE_SA.
167 *
168 * @param this calling object
169 * @return remote host_t
170 */
171 host_t* (*get_other_host) (ike_sa_t *this);
172
173 /**
174 * @brief Get own ID of the IKE_SA.
175 *
176 * @param this calling object
177 * @return local identification_t
178 */
179 identification_t* (*get_my_id) (ike_sa_t *this);
180
181 /**
182 * @brief Get remote ID the IKE_SA.
183 *
184 * @param this calling object
185 * @return remote identification_t
186 */
187 identification_t* (*get_other_id) (ike_sa_t *this);
188
189 /**
190 * @brief Get the connection of the IKE_SA.
191 *
192 * The internal used connection specification
193 * can be queried to get some data of an IKE_SA.
194 * The connection is still owned to the IKE_SA
195 * and must not be manipulated.
196 *
197 * @param this calling object
198 * @return connection_t
199 */
200 connection_t* (*get_connection) (ike_sa_t *this);
201
202 /**
203 * @brief Get the state of type of associated state object.
204 *
205 * @param this calling object
206 * @return state of IKE_SA
207 */
208 ike_sa_state_t (*get_state) (ike_sa_t *this);
209
210 /**
211 * @brief Log the status of a the ike sa to a logger.
212 *
213 * The status of the IKE SA and all child SAs is logged.
214 * Supplying NULL as logger uses the internal child_sa logger
215 * to do the logging. The log is only done if the supplied
216 * connection name is NULL or matches the connections name.
217 *
218 * @param this calling object
219 * @param logger logger to use for logging
220 * @param name name of the connection
221 */
222 void (*log_status) (ike_sa_t *this, logger_t *logger, char *name);
223
224 /**
225 * @brief Initiates the deletion of an IKE_SA.
226 *
227 * Sends a delete message to the remote peer and waits for
228 * its response. If the response comes in, or a timeout occurs,
229 * the IKE SA gets deleted.
230 *
231 * @param this calling object
232 * @return
233 * - SUCCESS if deletion is initialized
234 * - INVALID_STATE, if the IKE_SA is not in
235 * an established state and can not be
236 * delete (but destroyed).
237 */
238 status_t (*delete) (ike_sa_t *this);
239
240 /**
241 * @brief Destroys a ike_sa_t object.
242 *
243 * @param this calling object
244 */
245 void (*destroy) (ike_sa_t *this);
246 };
247
248
249 typedef struct protected_ike_sa_t protected_ike_sa_t;
250
251 /**
252 * @brief Protected functions of an ike_sa_t object.
253 *
254 * This members are only accessed out from
255 * the various state_t implementations.
256 *
257 * @ingroup sa
258 */
259 struct protected_ike_sa_t {
260
261 /**
262 * Public interface of an ike_sa_t object.
263 */
264 ike_sa_t public;
265
266 /**
267 * @brief Build an empty IKEv2-Message and fills in default informations.
268 *
269 * Depending on the type of message (request or response), the message id is
270 * either message_id_out or message_id_in.
271 *
272 * Used in state_t Implementation to build an empty IKEv2-Message.
273 *
274 * @param this calling object
275 * @param type exchange type of new message
276 * @param request TRUE, if message has to be a request
277 * @param message new message is stored at this location
278 */
279 void (*build_message) (protected_ike_sa_t *this, exchange_type_t type, bool request, message_t **message);
280
281 /**
282 * @brief Get the internal stored connection_t object.
283 *
284 * @param this calling object
285 * @return pointer to the internal stored connection_t object
286 */
287 connection_t *(*get_connection) (protected_ike_sa_t *this);
288
289 /**
290 * @brief Set the internal connection object.
291 *
292 * @param this calling object
293 * @param connection object of type connection_t
294 */
295 void (*set_connection) (protected_ike_sa_t *this, connection_t *connection);
296
297 /**
298 * @brief Get the internal stored policy object.
299 *
300 * @param this calling object
301 * @return pointer to the internal stored policy_t object
302 */
303 policy_t *(*get_policy) (protected_ike_sa_t *this);
304
305 /**
306 * @brief Set the internal policy_t object.
307 *
308 * @param this calling object
309 * @param policy object of type policy_t
310 */
311 void (*set_policy) (protected_ike_sa_t *this,policy_t *policy);
312
313 /**
314 * @brief Derive all keys and create the transforms for IKE communication.
315 *
316 * Keys are derived using the diffie hellman secret, nonces and internal
317 * stored SPIs.
318 * Already existing objects get destroyed.
319 *
320 * @param this calling object
321 * @param proposal proposal which contains algorithms to use
322 * @param dh diffie hellman object with shared secret
323 * @param nonce_i initiators nonce
324 * @param nonce_r responders nonce
325 */
326 status_t (*build_transforms) (protected_ike_sa_t *this, proposal_t* proposal,
327 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
328
329 /**
330 * @brief Send the next request message.
331 *
332 * Also the first retransmit job is created.
333 *
334 * Last stored requested message gets destroyed. Object gets not cloned!
335 *
336 * @param this calling object
337 * @param message pointer to the message which should be sent
338 * @return
339 * - SUCCESS
340 * - FAILED if message id is not next expected one
341 */
342 status_t (*send_request) (protected_ike_sa_t *this,message_t * message);
343
344 /**
345 * @brief Send the next response message.
346 *
347 * Last stored responded message gets destroyed. Object gets not cloned!
348 *
349 * @param this calling object
350 * @param message pointer to the message which should be sent
351 * return
352 * - SUCCESS
353 * - FAILED if message id is not next expected one
354 */
355 status_t (*send_response) (protected_ike_sa_t *this,message_t * message);
356
357 /**
358 * @brief Send a notify reply message.
359 *
360 * @param this calling object
361 * @param exchange_type type of exchange in which the notify should be wrapped
362 * @param type type of the notify message to send
363 * @param data notification data
364 */
365 void (*send_notify) (protected_ike_sa_t *this, exchange_type_t exchange_type, notify_message_type_t type, chunk_t data);
366
367 /**
368 * @brief Get the internal stored randomizer_t object.
369 *
370 * @param this calling object
371 * @return pointer to the internal randomizer_t object
372 */
373 randomizer_t *(*get_randomizer) (protected_ike_sa_t *this);
374
375 /**
376 * @brief Set the new state_t object of the IKE_SA object.
377 *
378 * The old state_t object gets not destroyed. It's the callers duty to
379 * make sure old state is destroyed (Normally the old state is the caller).
380 *
381 * @param this calling object
382 * @param state pointer to the new state_t object
383 */
384 void (*set_new_state) (protected_ike_sa_t *this,state_t *state);
385
386 /**
387 * @brief Set the last replied message id.
388 *
389 * @param this calling object
390 * @param message_id message id
391 */
392 void (*set_last_replied_message_id) (protected_ike_sa_t *this,u_int32_t message_id);
393
394 /**
395 * @brief Get the internal stored initiator crypter_t object.
396 *
397 * @param this calling object
398 * @return pointer to crypter_t object
399 */
400 crypter_t *(*get_crypter_initiator) (protected_ike_sa_t *this);
401
402 /**
403 * @brief Get the internal stored initiator signer_t object.
404 *
405 * @param this calling object
406 * @return pointer to signer_t object
407 */
408 signer_t *(*get_signer_initiator) (protected_ike_sa_t *this);
409
410 /**
411 * @brief Get the internal stored responder crypter_t object.
412 *
413 * @param this calling object
414 * @return pointer to crypter_t object
415 */
416 crypter_t *(*get_crypter_responder) (protected_ike_sa_t *this);
417
418 /**
419 * @brief Get the internal stored responder signer object.
420 *
421 * @param this calling object
422 * @return pointer to signer_t object
423 */
424 signer_t *(*get_signer_responder) (protected_ike_sa_t *this);
425
426 /**
427 * @brief Get the multi purpose prf.
428 *
429 * @param this calling object
430 * @return pointer to prf_t object
431 */
432 prf_t *(*get_prf) (protected_ike_sa_t *this);
433
434 /**
435 * @brief Get the prf-object, which is used to derive keys for child SAs.
436 *
437 * @param this calling object
438 * @return pointer to prf_t object
439 */
440 prf_t *(*get_child_prf) (protected_ike_sa_t *this);
441
442 /**
443 * @brief Get the prf used for authentication of initiator.
444 *
445 * @param this calling object
446 * @return pointer to prf_t object
447 */
448 prf_t *(*get_prf_auth_i) (protected_ike_sa_t *this);
449
450 /**
451 * @brief Get the prf used for authentication of responder.
452 *
453 * @param this calling object
454 * @return pointer to prf_t object
455 */
456 prf_t *(*get_prf_auth_r) (protected_ike_sa_t *this);
457
458 /**
459 * @brief Associates a child SA to this IKE SA
460 *
461 * @param this calling object
462 * @param child_sa child_sa to add
463 */
464 void (*add_child_sa) (protected_ike_sa_t *this, child_sa_t *child_sa);
465
466 /**
467 * @brief Destroys a CHILD_SA upon request from the other peer.
468 *
469 * @param this calling object
470 * @param spi inbound spi of the CHILD_SA to destroy
471 * @return outbound spi of the destroyed CHILD_SA
472 */
473 u_int32_t (*destroy_child_sa) (protected_ike_sa_t *this, u_int32_t spi);
474
475 /**
476 * @brief Get a CHILD_SA upon request from the other peer.
477 *
478 * @param this calling object
479 * @param spi spi of the CHILD_SA
480 * @return child_sa, or NULL if none found
481 */
482 child_sa_t* (*get_child_sa) (protected_ike_sa_t *this, u_int32_t spi);
483
484 /**
485 * @brief Get the last responded message.
486 *
487 * @param this calling object
488 * @return
489 * - last received as message_t object
490 * - NULL if no last request available
491 */
492 message_t *(*get_last_responded_message) (protected_ike_sa_t *this);
493
494 /**
495 * @brief Get the last requested message.
496 *
497 * @param this calling object
498 * @return
499 * - last sent as message_t object
500 * - NULL if no last request available
501 */
502 message_t *(*get_last_requested_message) (protected_ike_sa_t *this);
503
504 /**
505 * @brief Resets message counters and does destroy stored received and sent messages.
506 *
507 * @param this calling object
508 */
509 void (*reset_message_buffers) (protected_ike_sa_t *this);
510 };
511
512
513 /**
514 * @brief Creates an ike_sa_t object with a specific ID.
515 *
516 * @warning the Content of internal ike_sa_id_t object can change over time
517 * e.g. when a IKE_SA_INIT has been finished.
518 *
519 * @param[in] ike_sa_id ike_sa_id_t object to associate with new IKE_SA.
520 * The object is internal getting cloned
521 * and so has to be destroyed by the caller.
522 * @return ike_sa_t object
523 *
524 * @ingroup sa
525 */
526 ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id);
527
528 #endif /*IKE_SA_H_*/