applied new changes from NATT team
[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) 2006 Tobias Brunner, Daniel Roethlisberger
10 * Copyright (C) 2005 Jan Hutter, Martin Willi
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 IKE_SA_H_
25 #define IKE_SA_H_
26
27 #include <types.h>
28 #include <encoding/message.h>
29 #include <encoding/payloads/proposal_substructure.h>
30 #include <sa/ike_sa_id.h>
31 #include <sa/child_sa.h>
32 #include <sa/states/state.h>
33 #include <config/configuration.h>
34 #include <utils/logger.h>
35 #include <utils/randomizer.h>
36 #include <crypto/prfs/prf.h>
37 #include <crypto/crypters/crypter.h>
38 #include <crypto/signers/signer.h>
39 #include <config/connections/connection.h>
40 #include <config/policies/policy.h>
41 #include <utils/logger.h>
42
43 /**
44 * Nonce size in bytes for nonces sending to other peer.
45 *
46 * @warning Nonce size MUST be between 16 and 256 bytes.
47 *
48 * @ingroup sa
49 */
50 #define NONCE_SIZE 16
51
52
53 typedef struct ike_sa_t ike_sa_t;
54
55 /**
56 * @brief Class ike_sa_t representing an IKE_SA.
57 *
58 * An object of this type is managed by an ike_sa_manager_t object
59 * and represents an IKE_SA. Message processing is split up in different states.
60 * They will handle all related things for the state they represent.
61 *
62 * @b Constructors:
63 * - ike_sa_create()
64 *
65 * @ingroup sa
66 */
67 struct ike_sa_t {
68
69 /**
70 * @brief Processes a incoming IKEv2-Message of type message_t.
71 *
72 * @param this ike_sa_t object object
73 * @param[in] message message_t object to process
74 * @return
75 * - SUCCESS
76 * - FAILED
77 * - DESTROY_ME if this IKE_SA MUST be deleted
78 */
79 status_t (*process_message) (ike_sa_t *this,message_t *message);
80
81 /**
82 * @brief Initiate a new connection with given connection_t object.
83 *
84 * The connection_t object is owned by the IKE_SA after the call, so
85 * do not modify or destroy it.
86 *
87 * @param this calling object
88 * @param connection connection to initiate
89 * @return
90 * - SUCCESS if initialization started
91 * - FAILED if in wrong state
92 * - DESTROY_ME if initialization failed and IKE_SA MUST be deleted
93 */
94 status_t (*initiate_connection) (ike_sa_t *this, connection_t *connection);
95
96 /**
97 * @brief Checks whether retransmission is possible.
98 *
99 * @param this calling object
100 * @param message_id ID of the request to retransmit
101 * @return
102 * - TRUE if retransmit is possible
103 * - FALSE if not
104 */
105 bool (*retransmit_possible) (ike_sa_t *this, u_int32_t message_id);
106
107 /**
108 * @brief Retransmits a request.
109 *
110 * @param this calling object
111 * @param message_id ID of the request to retransmit
112 * @return
113 * - SUCCESS
114 * - NOT_FOUND if request doesn't have to be retransmited
115 */
116 status_t (*retransmit_request) (ike_sa_t *this, u_int32_t message_id);
117
118 /**
119 * @brief Get the id of the SA.
120 *
121 * Returned ike_sa_id_t object is not getting cloned!
122 *
123 * @param this calling object
124 * @return ike_sa's ike_sa_id_t
125 */
126 ike_sa_id_t* (*get_id) (ike_sa_t *this);
127
128 /**
129 * @brief Get the CHILD_SA with the specified reqid.
130 *
131 * The reqid is a unique ID for a child SA, which is
132 * generated on child SA creation.
133 * Returned child_sa_t object is not cloned!
134 *
135 * @param this calling object
136 * @param reqid reqid of the child SA, as used in the kernel
137 * @return child_sa, or NULL if not found
138 */
139 child_sa_t* (*get_child_sa) (ike_sa_t *this, u_int32_t reqid);
140
141 /**
142 * @brief Close the CHILD SA with the specified reqid.
143 *
144 * Looks for a CHILD SA owned by this IKE_SA, deletes it and
145 * notify's the remote peer about the delete. The associated
146 * states and policies in the kernel get deleted, if they exist.
147 *
148 * @param this calling object
149 * @param reqid reqid of the child SA, as used in the kernel
150 * @return
151 * - NOT_FOUND, if IKE_SA has no such CHILD_SA
152 * - SUCCESS, if deleted and delete message sent
153 */
154 status_t (*delete_child_sa) (ike_sa_t *this, u_int32_t reqid);
155
156 /**
157 * @brief Rekey the CHILD SA with the specified reqid.
158 *
159 * Looks for a CHILD SA owned by this IKE_SA, and start the rekeing.
160 *
161 * @param this calling object
162 * @param spi security parameter index identifying the SA to rekey
163 * @return
164 * - NOT_FOUND, if IKE_SA has no such CHILD_SA
165 * - SUCCESS, if rekeying initiated
166 */
167 status_t (*rekey_child_sa) (ike_sa_t *this, u_int32_t reqid);
168
169 /**
170 * @brief Get local peer address of the IKE_SA.
171 *
172 * @param this calling object
173 * @return local host_t
174 */
175 host_t* (*get_my_host) (ike_sa_t *this);
176
177 /**
178 * @brief Get remote peer address of the IKE_SA.
179 *
180 * @param this calling object
181 * @return remote host_t
182 */
183 host_t* (*get_other_host) (ike_sa_t *this);
184
185 /**
186 * @brief Get own ID of the IKE_SA.
187 *
188 * @param this calling object
189 * @return local identification_t
190 */
191 identification_t* (*get_my_id) (ike_sa_t *this);
192
193 /**
194 * @brief Get remote ID the IKE_SA.
195 *
196 * @param this calling object
197 * @return remote identification_t
198 */
199 identification_t* (*get_other_id) (ike_sa_t *this);
200
201 /**
202 * @brief Get the connection of the IKE_SA.
203 *
204 * The internal used connection specification
205 * can be queried to get some data of an IKE_SA.
206 * The connection is still owned to the IKE_SA
207 * and must not be manipulated.
208 *
209 * @param this calling object
210 * @return connection_t
211 */
212 connection_t* (*get_connection) (ike_sa_t *this);
213
214 /**
215 * @brief Query NAT detection status for local host.
216 *
217 * @param this calling object
218 * @return TRUE if this host is behind NAT
219 */
220 bool (*is_my_host_behind_nat) (ike_sa_t *this);
221
222 /**
223 * @brief Query NAT detection status for remote host.
224 *
225 * @param this calling object
226 * @return TRUE if other host is behind NAT
227 */
228 bool (*is_other_host_behind_nat) (ike_sa_t *this);
229
230 /**
231 * @brief Query NAT detection status for any host.
232 *
233 * @param this calling object
234 * @return TRUE if this or other host is behind NAT
235 */
236 bool (*is_any_host_behind_nat) (ike_sa_t *this);
237
238 /**
239 * @brief Query timeval of last inbound IKE or ESP traffic.
240 *
241 * @param this calling object
242 * @return time when the last traffic was seen
243 */
244 struct timeval (*get_last_traffic_in_tv) (ike_sa_t *this);
245
246 /**
247 * @brief Query timeval of last outbound IKE or ESP traffic.
248 *
249 * @param this calling object
250 * @return time when the last traffic was seen
251 */
252 struct timeval (*get_last_traffic_out_tv) (ike_sa_t *this);
253
254 /**
255 * @brief Get the state of type of associated state object.
256 *
257 * @param this calling object
258 * @return state of IKE_SA
259 */
260 ike_sa_state_t (*get_state) (ike_sa_t *this);
261
262 /**
263 * @brief Sends a DPD request to the peer.
264 *
265 * @param this calling object
266 */
267 status_t (*send_dpd_request) (ike_sa_t *this);
268
269 /**
270 * @brief Log the status of a the ike sa to a logger.
271 *
272 * The status of the IKE SA and all child SAs is logged.
273 * Supplying NULL as logger uses the internal child_sa logger
274 * to do the logging. The log is only done if the supplied
275 * connection name is NULL or matches the connections name.
276 *
277 * @param this calling object
278 * @param logger logger to use for logging
279 * @param name name of the connection
280 */
281 void (*log_status) (ike_sa_t *this, logger_t *logger, char *name);
282
283 /**
284 * @brief Initiates the deletion of an IKE_SA.
285 *
286 * Sends a delete message to the remote peer and waits for
287 * its response. If the response comes in, or a timeout occurs,
288 * the IKE SA gets deleted.
289 *
290 * @param this calling object
291 * @return
292 * - SUCCESS if deletion is initialized
293 * - INVALID_STATE, if the IKE_SA is not in
294 * an established state and can not be
295 * delete (but destroyed).
296 */
297 status_t (*delete) (ike_sa_t *this);
298
299 /**
300 * @brief Destroys a ike_sa_t object.
301 *
302 * @param this calling object
303 */
304 void (*destroy) (ike_sa_t *this);
305 };
306
307
308 typedef struct protected_ike_sa_t protected_ike_sa_t;
309
310 /**
311 * @brief Protected functions of an ike_sa_t object.
312 *
313 * This members are only accessed out from
314 * the various state_t implementations.
315 *
316 * @ingroup sa
317 */
318 struct protected_ike_sa_t {
319
320 /**
321 * Public interface of an ike_sa_t object.
322 */
323 ike_sa_t public;
324
325 /**
326 * @brief Build an empty IKEv2-Message and fills in default informations.
327 *
328 * Depending on the type of message (request or response), the message id is
329 * either message_id_out or message_id_in.
330 *
331 * Used in state_t Implementation to build an empty IKEv2-Message.
332 *
333 * @param this calling object
334 * @param type exchange type of new message
335 * @param request TRUE, if message has to be a request
336 * @param message new message is stored at this location
337 */
338 void (*build_message) (protected_ike_sa_t *this, exchange_type_t type, bool request, message_t **message);
339
340 /**
341 * @brief Get the internal stored connection_t object.
342 *
343 * @param this calling object
344 * @return pointer to the internal stored connection_t object
345 */
346 connection_t *(*get_connection) (protected_ike_sa_t *this);
347
348 /**
349 * @brief Set the internal connection object.
350 *
351 * @param this calling object
352 * @param connection object of type connection_t
353 */
354 void (*set_connection) (protected_ike_sa_t *this, connection_t *connection);
355
356 /**
357 * @brief Get the internal stored policy object.
358 *
359 * @param this calling object
360 * @return pointer to the internal stored policy_t object
361 */
362 policy_t *(*get_policy) (protected_ike_sa_t *this);
363
364 /**
365 * @brief Set the internal policy_t object.
366 *
367 * @param this calling object
368 * @param policy object of type policy_t
369 */
370 void (*set_policy) (protected_ike_sa_t *this,policy_t *policy);
371
372 /**
373 * @brief Derive all keys and create the transforms for IKE communication.
374 *
375 * Keys are derived using the diffie hellman secret, nonces and internal
376 * stored SPIs.
377 * Already existing objects get destroyed.
378 *
379 * @param this calling object
380 * @param proposal proposal which contains algorithms to use
381 * @param dh diffie hellman object with shared secret
382 * @param nonce_i initiators nonce
383 * @param nonce_r responders nonce
384 */
385 status_t (*build_transforms) (protected_ike_sa_t *this, proposal_t* proposal,
386 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
387
388 /**
389 * @brief Send the next request message.
390 *
391 * Also the first retransmit job is created.
392 *
393 * Last stored requested message gets destroyed. Object gets not cloned!
394 *
395 * @param this calling object
396 * @param message pointer to the message which should be sent
397 * @return
398 * - SUCCESS
399 * - FAILED if message id is not next expected one
400 */
401 status_t (*send_request) (protected_ike_sa_t *this,message_t * message);
402
403 /**
404 * @brief Send the next response message.
405 *
406 * Last stored responded message gets destroyed. Object gets not cloned!
407 *
408 * @param this calling object
409 * @param message pointer to the message which should be sent
410 * return
411 * - SUCCESS
412 * - FAILED if message id is not next expected one
413 */
414 status_t (*send_response) (protected_ike_sa_t *this,message_t * message);
415
416 /**
417 * @brief Send a notify reply message.
418 *
419 * @param this calling object
420 * @param exchange_type type of exchange in which the notify should be wrapped
421 * @param type type of the notify message to send
422 * @param data notification data
423 */
424 void (*send_notify) (protected_ike_sa_t *this, exchange_type_t exchange_type, notify_message_type_t type, chunk_t data);
425
426 /**
427 * @brief Get the internal stored randomizer_t object.
428 *
429 * @param this calling object
430 * @return pointer to the internal randomizer_t object
431 */
432 randomizer_t *(*get_randomizer) (protected_ike_sa_t *this);
433
434 /**
435 * @brief Set the new state_t object of the IKE_SA object.
436 *
437 * The old state_t object gets not destroyed. It's the callers duty to
438 * make sure old state is destroyed (Normally the old state is the caller).
439 *
440 * @param this calling object
441 * @param state pointer to the new state_t object
442 */
443 void (*set_new_state) (protected_ike_sa_t *this,state_t *state);
444
445 /**
446 * @brief Set the last replied message id.
447 *
448 * @param this calling object
449 * @param message_id message id
450 */
451 void (*set_last_replied_message_id) (protected_ike_sa_t *this,u_int32_t message_id);
452
453 /**
454 * @brief Get the internal stored initiator crypter_t object.
455 *
456 * @param this calling object
457 * @return pointer to crypter_t object
458 */
459 crypter_t *(*get_crypter_initiator) (protected_ike_sa_t *this);
460
461 /**
462 * @brief Get the internal stored initiator signer_t object.
463 *
464 * @param this calling object
465 * @return pointer to signer_t object
466 */
467 signer_t *(*get_signer_initiator) (protected_ike_sa_t *this);
468
469 /**
470 * @brief Get the internal stored responder crypter_t object.
471 *
472 * @param this calling object
473 * @return pointer to crypter_t object
474 */
475 crypter_t *(*get_crypter_responder) (protected_ike_sa_t *this);
476
477 /**
478 * @brief Get the internal stored responder signer object.
479 *
480 * @param this calling object
481 * @return pointer to signer_t object
482 */
483 signer_t *(*get_signer_responder) (protected_ike_sa_t *this);
484
485 /**
486 * @brief Get the multi purpose prf.
487 *
488 * @param this calling object
489 * @return pointer to prf_t object
490 */
491 prf_t *(*get_prf) (protected_ike_sa_t *this);
492
493 /**
494 * @brief Get the prf-object, which is used to derive keys for child SAs.
495 *
496 * @param this calling object
497 * @return pointer to prf_t object
498 */
499 prf_t *(*get_child_prf) (protected_ike_sa_t *this);
500
501 /**
502 * @brief Get the prf used for authentication of initiator.
503 *
504 * @param this calling object
505 * @return pointer to prf_t object
506 */
507 prf_t *(*get_prf_auth_i) (protected_ike_sa_t *this);
508
509 /**
510 * @brief Get the prf used for authentication of responder.
511 *
512 * @param this calling object
513 * @return pointer to prf_t object
514 */
515 prf_t *(*get_prf_auth_r) (protected_ike_sa_t *this);
516
517 /**
518 * @brief Associates a child SA to this IKE SA
519 *
520 * @param this calling object
521 * @param child_sa child_sa to add
522 */
523 void (*add_child_sa) (protected_ike_sa_t *this, child_sa_t *child_sa);
524
525 /**
526 * @brief Destroys a CHILD_SA upon request from the other peer.
527 *
528 * @param this calling object
529 * @param spi inbound spi of the CHILD_SA to destroy
530 * @return outbound spi of the destroyed CHILD_SA
531 */
532 u_int32_t (*destroy_child_sa) (protected_ike_sa_t *this, u_int32_t spi);
533
534 /**
535 * @brief Get a CHILD_SA upon request from the other peer.
536 *
537 * @param this calling object
538 * @param spi spi of the CHILD_SA
539 * @return child_sa, or NULL if none found
540 */
541 child_sa_t* (*get_child_sa) (protected_ike_sa_t *this, u_int32_t spi);
542
543 /**
544 * @brief Get the last responded message.
545 *
546 * @param this calling object
547 * @return
548 * - last received as message_t object
549 * - NULL if no last request available
550 */
551 message_t *(*get_last_responded_message) (protected_ike_sa_t *this);
552
553 /**
554 * @brief Get the last requested message.
555 *
556 * @param this calling object
557 * @return
558 * - last sent as message_t object
559 * - NULL if no last request available
560 */
561 message_t *(*get_last_requested_message) (protected_ike_sa_t *this);
562
563 /**
564 * @brief Resets message counters and does destroy stored received and sent messages.
565 *
566 * @param this calling object
567 */
568 void (*reset_message_buffers) (protected_ike_sa_t *this);
569
570 /**
571 * @brief Set NAT detection status for local host.
572 *
573 * @param this calling object
574 * @param nat if TRUE, local host is behing NAT
575 */
576 void (*set_my_host_behind_nat) (protected_ike_sa_t *this, bool nat);
577
578 /**
579 * @brief Set NAT detection status for remote host.
580 *
581 * @param this calling object
582 * @param nat if TRUE, remote host is behing NAT
583 */
584 void (*set_other_host_behind_nat) (protected_ike_sa_t *this, bool nat);
585
586 /**
587 * @brief Generate NAT-D payload hash.
588 *
589 * @param this calling object
590 * @param spi_i IKE SPI of initiator
591 * @param spi_r IKE SPI of responder
592 * @param host address and port of the host/interface
593 * @return chunk containing calculated NAT-D hash
594 */
595 chunk_t (*generate_natd_hash) (protected_ike_sa_t *this, u_int64_t spi_i, u_int64_t spi_r, host_t *host);
596
597 /**
598 * @brief Dynamically update hosts on the associated connection.
599 *
600 * Warning: me and other host are cloned.
601 *
602 * @param this calling object
603 * @param me local address and port
604 * @param other remote address and port
605 */
606 status_t (*update_connection_hosts) (protected_ike_sa_t *this, host_t *me, host_t *other);
607
608 /**
609 * @brief Return the message id of the last DPD message
610 *
611 * @param this calling object
612 * @return the messages id
613 */
614 u_int32_t (*get_last_dpd_message_id) (protected_ike_sa_t *this);
615 };
616
617
618 /**
619 * @brief Creates an ike_sa_t object with a specific ID.
620 *
621 * @warning the Content of internal ike_sa_id_t object can change over time
622 * e.g. when a IKE_SA_INIT has been finished.
623 *
624 * @param[in] ike_sa_id ike_sa_id_t object to associate with new IKE_SA.
625 * The object is internal getting cloned
626 * and so has to be destroyed by the caller.
627 * @return ike_sa_t object
628 *
629 * @ingroup sa
630 */
631 ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id);
632
633 #endif /*IKE_SA_H_*/