1: /*
2: * Copyright (C) 2006-2020 Tobias Brunner
3: * Copyright (C) 2006 Daniel Roethlisberger
4: * Copyright (C) 2005-2009 Martin Willi
5: * Copyright (C) 2005 Jan Hutter
6: * HSR Hochschule fuer Technik Rapperswil
7: *
8: * This program is free software; you can redistribute it and/or modify it
9: * under the terms of the GNU General Public License as published by the
10: * Free Software Foundation; either version 2 of the License, or (at your
11: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12: *
13: * This program is distributed in the hope that it will be useful, but
14: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16: * for more details.
17: */
18:
19: /**
20: * @defgroup ike_sa ike_sa
21: * @{ @ingroup sa
22: */
23:
24: #ifndef IKE_SA_H_
25: #define IKE_SA_H_
26:
27: typedef enum ike_extension_t ike_extension_t;
28: typedef enum ike_condition_t ike_condition_t;
29: typedef enum ike_sa_state_t ike_sa_state_t;
30: typedef enum statistic_t statistic_t;
31: typedef enum update_hosts_flag_t update_hosts_flag_t;
32: typedef struct ike_sa_t ike_sa_t;
33:
34: #include <library.h>
35: #include <attributes/attribute_handler.h>
36: #include <encoding/message.h>
37: #include <encoding/payloads/proposal_substructure.h>
38: #include <encoding/payloads/configuration_attribute.h>
39: #include <sa/ike_sa_id.h>
40: #include <sa/child_sa.h>
41: #include <sa/task.h>
42: #include <sa/task_manager.h>
43: #include <sa/keymat.h>
44: #include <config/peer_cfg.h>
45: #include <config/ike_cfg.h>
46: #include <credentials/auth_cfg.h>
47: #include <networking/packet.h>
48:
49: /**
50: * Timeout in seconds after that a half open IKE_SA gets deleted.
51: */
52: #define HALF_OPEN_IKE_SA_TIMEOUT 30
53:
54: /**
55: * Interval to send keepalives when NATed, in seconds.
56: */
57: #define KEEPALIVE_INTERVAL 20
58:
59: /**
60: * After which time rekeying should be retried if it failed, in seconds.
61: */
62: #define RETRY_INTERVAL 15
63:
64: /**
65: * Jitter to subtract from RETRY_INTERVAL to randomize rekey retry.
66: */
67: #define RETRY_JITTER 10
68:
69: /**
70: * Number of redirects allowed within REDIRECT_LOOP_DETECT_PERIOD.
71: */
72: #define MAX_REDIRECTS 5
73:
74: /**
75: * Time period in seconds in which at most MAX_REDIRECTS are allowed.
76: */
77: #define REDIRECT_LOOP_DETECT_PERIOD 300
78:
79: /**
80: * Extensions (or optional features) the peer supports
81: */
82: enum ike_extension_t {
83:
84: /**
85: * peer supports NAT traversal as specified in RFC4306 or RFC3947
86: * including some RFC3947 drafts
87: */
88: EXT_NATT = (1<<0),
89:
90: /**
91: * peer supports MOBIKE (RFC4555)
92: */
93: EXT_MOBIKE = (1<<1),
94:
95: /**
96: * peer supports HTTP cert lookups as specified in RFC4306
97: */
98: EXT_HASH_AND_URL = (1<<2),
99:
100: /**
101: * peer supports multiple authentication exchanges, RFC4739
102: */
103: EXT_MULTIPLE_AUTH = (1<<3),
104:
105: /**
106: * peer uses strongSwan, accept private use extensions
107: */
108: EXT_STRONGSWAN = (1<<4),
109:
110: /**
111: * peer supports EAP-only authentication, draft-eronen-ipsec-ikev2-eap-auth
112: */
113: EXT_EAP_ONLY_AUTHENTICATION = (1<<5),
114:
115: /**
116: * peer is probably a Windows RAS client
117: */
118: EXT_MS_WINDOWS = (1<<6),
119:
120: /**
121: * peer supports XAuth authentication, draft-ietf-ipsec-isakmp-xauth-06
122: */
123: EXT_XAUTH = (1<<7),
124:
125: /**
126: * peer supports DPD detection, RFC 3706 (or IKEv2)
127: */
128: EXT_DPD = (1<<8),
129:
130: /**
131: * peer supports Cisco Unity configuration attributes
132: */
133: EXT_CISCO_UNITY = (1<<9),
134:
135: /**
136: * peer supports NAT traversal as specified in
137: * draft-ietf-ipsec-nat-t-ike-02 .. -03
138: */
139: EXT_NATT_DRAFT_02_03 = (1<<10),
140:
141: /**
142: * peer supports proprietary IKEv1 or standardized IKEv2 fragmentation
143: */
144: EXT_IKE_FRAGMENTATION = (1<<11),
145:
146: /**
147: * Signature Authentication, RFC 7427
148: */
149: EXT_SIGNATURE_AUTH = (1<<12),
150:
151: /**
152: * IKEv2 Redirect Mechanism, RFC 5685
153: */
154: EXT_IKE_REDIRECTION = (1<<13),
155:
156: /**
157: * IKEv2 Message ID sync, RFC 6311
158: */
159: EXT_IKE_MESSAGE_ID_SYNC = (1<<14),
160:
161: /**
162: * Postquantum Preshared Keys, draft-ietf-ipsecme-qr-ikev2
163: */
164: EXT_PPK = (1<<15),
165:
166: /**
167: * Responder accepts childless IKE_SAs, RFC 6023
168: */
169: EXT_IKE_CHILDLESS = (1<<16),
170: };
171:
172: /**
173: * Conditions of an IKE_SA, change during its lifetime
174: */
175: enum ike_condition_t {
176:
177: /**
178: * Connection is natted (or faked) somewhere
179: */
180: COND_NAT_ANY = (1<<0),
181:
182: /**
183: * we are behind NAT
184: */
185: COND_NAT_HERE = (1<<1),
186:
187: /**
188: * other is behind NAT
189: */
190: COND_NAT_THERE = (1<<2),
191:
192: /**
193: * Faking NAT to enforce UDP encapsulation
194: */
195: COND_NAT_FAKE = (1<<3),
196:
197: /**
198: * peer has been authenticated using EAP at least once
199: */
200: COND_EAP_AUTHENTICATED = (1<<4),
201:
202: /**
203: * received a certificate request from the peer
204: */
205: COND_CERTREQ_SEEN = (1<<5),
206:
207: /**
208: * Local peer is the "original" IKE initiator. Unaffected from rekeying.
209: */
210: COND_ORIGINAL_INITIATOR = (1<<6),
211:
212: /**
213: * IKE_SA is stale, the peer is currently unreachable (MOBIKE)
214: */
215: COND_STALE = (1<<7),
216:
217: /**
218: * Initial contact received
219: */
220: COND_INIT_CONTACT_SEEN = (1<<8),
221:
222: /**
223: * Peer has been authenticated using XAuth
224: */
225: COND_XAUTH_AUTHENTICATED = (1<<9),
226:
227: /**
228: * This IKE_SA is currently being reauthenticated
229: */
230: COND_REAUTHENTICATING = (1<<10),
231:
232: /**
233: * This IKE_SA has been redirected
234: */
235: COND_REDIRECTED = (1<<11),
236:
237: /**
238: * Online certificate revocation checking is suspended for this IKE_SA
239: */
240: COND_ONLINE_VALIDATION_SUSPENDED = (1<<12),
241:
242: /**
243: * A Postquantum Preshared Key was used when this IKE_SA was created
244: */
245: COND_PPK = (1<<13),
246: };
247:
248: /**
249: * Timing information and statistics to query from an SA
250: */
251: enum statistic_t {
252: /** Timestamp of SA establishment */
253: STAT_ESTABLISHED = 0,
254: /** Timestamp of scheduled rekeying */
255: STAT_REKEY,
256: /** Timestamp of scheduled reauthentication */
257: STAT_REAUTH,
258: /** Timestamp of scheduled delete */
259: STAT_DELETE,
260: /** Timestamp of last inbound IKE packet */
261: STAT_INBOUND,
262: /** Timestamp of last outbound IKE packet */
263: STAT_OUTBOUND,
264:
265: STAT_MAX
266: };
267:
268: /**
269: * Flags used when updating addresses
270: */
271: enum update_hosts_flag_t {
272: /** Force updating the local address (otherwise not updated if an address
273: * is already set). */
274: UPDATE_HOSTS_FORCE_LOCAL = (1<<0),
275: /** Force updating the remote address (otherwise only updated if peer is
276: * behind a NAT). */
277: UPDATE_HOSTS_FORCE_REMOTE = (1<<1),
278: /** Force updating both addresses. */
279: UPDATE_HOSTS_FORCE_ADDRS = UPDATE_HOSTS_FORCE_LOCAL|UPDATE_HOSTS_FORCE_REMOTE,
280: /** Force updating the CHILD_SAs even if no addresses changed, useful if
281: * NAT state may have changed. */
282: UPDATE_HOSTS_FORCE_CHILDREN = (1<<2),
283: /** Force updating everything. */
284: UPDATE_HOSTS_FORCE_ALL = UPDATE_HOSTS_FORCE_ADDRS|UPDATE_HOSTS_FORCE_CHILDREN,
285: };
286:
287: /**
288: * State of an IKE_SA.
289: *
290: * An IKE_SA passes various states in its lifetime. A newly created
291: * SA is in the state CREATED.
292: * @verbatim
293: +----------------+
294: ¦ SA_CREATED ¦
295: +----------------+
296: ¦
297: on initiate()---> ¦ <----- on IKE_SA_INIT received
298: V
299: +----------------+
300: ¦ SA_CONNECTING ¦
301: +----------------+
302: ¦
303: ¦ <----- on IKE_AUTH successfully completed
304: V
305: +----------------+
306: ¦ SA_ESTABLISHED ¦-------------------------+ <-- on rekeying
307: +----------------+ ¦
308: ¦ V
309: on delete()---> ¦ <----- on IKE_SA +-------------+
310: ¦ delete request ¦ SA_REKEYING ¦
311: ¦ received +-------------+
312: V ¦
313: +----------------+ ¦
314: ¦ SA_DELETING ¦<------------------------+ <-- after rekeying
315: +----------------+
316: ¦
317: ¦ <----- after delete() acknowledged
318: ¦
319: \V/
320: X
321: / \
322: @endverbatim
323: */
324: enum ike_sa_state_t {
325:
326: /**
327: * IKE_SA just got created, but is not initiating nor responding yet.
328: */
329: IKE_CREATED,
330:
331: /**
332: * IKE_SA gets initiated actively or passively
333: */
334: IKE_CONNECTING,
335:
336: /**
337: * IKE_SA is fully established
338: */
339: IKE_ESTABLISHED,
340:
341: /**
342: * IKE_SA is managed externally and does not process messages
343: */
344: IKE_PASSIVE,
345:
346: /**
347: * IKE_SA rekeying in progress
348: */
349: IKE_REKEYING,
350:
351: /**
352: * IKE_SA has been rekeyed (or is redundant)
353: */
354: IKE_REKEYED,
355:
356: /**
357: * IKE_SA is in progress of deletion
358: */
359: IKE_DELETING,
360:
361: /**
362: * IKE_SA object gets destroyed
363: */
364: IKE_DESTROYING,
365: };
366:
367: /**
368: * enum names for ike_sa_state_t.
369: */
370: extern enum_name_t *ike_sa_state_names;
371:
372: /**
373: * Class ike_sa_t representing an IKE_SA.
374: *
375: * An IKE_SA contains crypto information related to a connection
376: * with a peer. It contains multiple IPsec CHILD_SA, for which
377: * it is responsible. All traffic is handled by an IKE_SA, using
378: * the task manager and its tasks.
379: */
380: struct ike_sa_t {
381:
382: /**
383: * Get the id of the SA.
384: *
385: * Returned ike_sa_id_t object is not getting cloned!
386: *
387: * @return ike_sa's ike_sa_id_t
388: */
389: ike_sa_id_t* (*get_id) (ike_sa_t *this);
390:
391: /**
392: * Gets the IKE version of the SA
393: */
394: ike_version_t (*get_version)(ike_sa_t *this);
395:
396: /**
397: * Get the numerical ID uniquely defining this IKE_SA.
398: *
399: * @return unique ID
400: */
401: uint32_t (*get_unique_id) (ike_sa_t *this);
402:
403: /**
404: * Get the state of the IKE_SA.
405: *
406: * @return state of the IKE_SA
407: */
408: ike_sa_state_t (*get_state) (ike_sa_t *this);
409:
410: /**
411: * Set the state of the IKE_SA.
412: *
413: * @param state state to set for the IKE_SA
414: */
415: void (*set_state) (ike_sa_t *this, ike_sa_state_t state);
416:
417: /**
418: * Get the name of the connection this IKE_SA uses.
419: *
420: * @return name
421: */
422: char* (*get_name) (ike_sa_t *this);
423:
424: /**
425: * Get statistic values from the IKE_SA.
426: *
427: * @param kind kind of requested value
428: * @return value as integer
429: */
430: uint32_t (*get_statistic)(ike_sa_t *this, statistic_t kind);
431:
432: /**
433: * Set statistic value of the IKE_SA.
434: *
435: * @param kind kind of value to update
436: * @param value value as integer
437: */
438: void (*set_statistic)(ike_sa_t *this, statistic_t kind, uint32_t value);
439:
440: /**
441: * Get the own host address.
442: *
443: * @return host address
444: */
445: host_t* (*get_my_host) (ike_sa_t *this);
446:
447: /**
448: * Set the own host address.
449: *
450: * @param me host address
451: */
452: void (*set_my_host) (ike_sa_t *this, host_t *me);
453:
454: /**
455: * Get the other peers host address.
456: *
457: * @return host address
458: */
459: host_t* (*get_other_host) (ike_sa_t *this);
460:
461: /**
462: * Set the others host address.
463: *
464: * @param other host address
465: */
466: void (*set_other_host) (ike_sa_t *this, host_t *other);
467:
468: /**
469: * Float to port 4500 (e.g. if a NAT is detected).
470: *
471: * The port of either endpoint is changed only if it is currently
472: * set to the default value of 500.
473: */
474: void (*float_ports)(ike_sa_t *this);
475:
476: /**
477: * Update the IKE_SAs host and CHILD_SAs.
478: *
479: * Hosts may be NULL to use current host.
480: *
481: * @param me new local host address, or NULL
482: * @param other new remote host address, or NULL
483: * @param flags flags to force certain updates
484: */
485: void (*update_hosts)(ike_sa_t *this, host_t *me, host_t *other,
486: update_hosts_flag_t flags);
487:
488: /**
489: * Get the own identification.
490: *
491: * @return identification
492: */
493: identification_t* (*get_my_id) (ike_sa_t *this);
494:
495: /**
496: * Set the own identification.
497: *
498: * @param me identification
499: */
500: void (*set_my_id) (ike_sa_t *this, identification_t *me);
501:
502: /**
503: * Get the other peer's identification.
504: *
505: * @return identification
506: */
507: identification_t* (*get_other_id) (ike_sa_t *this);
508:
509: /**
510: * Get the others peer identity, but prefer an EAP-Identity.
511: *
512: * @return EAP or IKEv2 identity
513: */
514: identification_t* (*get_other_eap_id)(ike_sa_t *this);
515:
516: /**
517: * Set the other peer's identification.
518: *
519: * @param other identification
520: */
521: void (*set_other_id) (ike_sa_t *this, identification_t *other);
522:
523: /**
524: * Get the config used to setup this IKE_SA.
525: *
526: * @return ike_config
527: */
528: ike_cfg_t* (*get_ike_cfg) (ike_sa_t *this);
529:
530: /**
531: * Set the config to setup this IKE_SA.
532: *
533: * @param config ike_config to use
534: */
535: void (*set_ike_cfg) (ike_sa_t *this, ike_cfg_t* config);
536:
537: /**
538: * Get the peer config used by this IKE_SA.
539: *
540: * @return peer_config
541: */
542: peer_cfg_t* (*get_peer_cfg) (ike_sa_t *this);
543:
544: /**
545: * Set the peer config to use with this IKE_SA.
546: *
547: * @param config peer_config to use
548: */
549: void (*set_peer_cfg) (ike_sa_t *this, peer_cfg_t *config);
550:
551: /**
552: * Get the authentication config with rules of the current auth round.
553: *
554: * @param local TRUE for local rules, FALSE for remote constraints
555: * @return current cfg
556: */
557: auth_cfg_t* (*get_auth_cfg)(ike_sa_t *this, bool local);
558:
559: /**
560: * Insert a completed authentication round.
561: *
562: * @param local TRUE for own rules, FALSE for others constraints
563: * @param cfg auth config to append
564: */
565: void (*add_auth_cfg)(ike_sa_t *this, bool local, auth_cfg_t *cfg);
566:
567: /**
568: * Create an enumerator over added authentication rounds.
569: *
570: * @param local TRUE for own rules, FALSE for others constraints
571: * @return enumerator over auth_cfg_t
572: */
573: enumerator_t* (*create_auth_cfg_enumerator)(ike_sa_t *this, bool local);
574:
575: /**
576: * Verify the trustchains (validity, revocation) in completed public key
577: * auth rounds.
578: *
579: * @return TRUE if certificates were valid, FALSE otherwise
580: */
581: bool (*verify_peer_certificate)(ike_sa_t *this);
582:
583: /**
584: * Get the selected proposal of this IKE_SA.
585: *
586: * @return selected proposal
587: */
588: proposal_t* (*get_proposal)(ike_sa_t *this);
589:
590: /**
591: * Set the proposal selected for this IKE_SA.
592: *
593: * @param selected proposal
594: */
595: void (*set_proposal)(ike_sa_t *this, proposal_t *proposal);
596:
597: /**
598: * Set the message ID of the IKE_SA.
599: *
600: * The IKE_SA stores two message IDs, one for initiating exchanges (send)
601: * and one to respond to exchanges (expect).
602: *
603: * @param initiate TRUE to set message ID for initiating
604: * @param mid message id to set
605: */
606: void (*set_message_id)(ike_sa_t *this, bool initiate, uint32_t mid);
607:
608: /**
609: * Get the message ID of the IKE_SA.
610: *
611: * The IKE_SA stores two message IDs, one for initiating exchanges (send)
612: * and one to respond to exchanges (expect).
613: *
614: * @param initiate TRUE to get message ID for initiating
615: * @return current message
616: */
617: uint32_t (*get_message_id)(ike_sa_t *this, bool initiate);
618:
619: /**
620: * Add an additional address for the peer.
621: *
622: * In MOBIKE, a peer may transmit additional addresses where it is
623: * reachable. These are stored in the IKE_SA.
624: * The own list of addresses is not stored, they are queried from
625: * the kernel when required.
626: *
627: * @param host host to add to list
628: */
629: void (*add_peer_address)(ike_sa_t *this, host_t *host);
630:
631: /**
632: * Create an enumerator over all known addresses of the peer.
633: *
634: * @return enumerator over addresses
635: */
636: enumerator_t* (*create_peer_address_enumerator)(ike_sa_t *this);
637:
638: /**
639: * Remove all known addresses of the peer.
640: */
641: void (*clear_peer_addresses)(ike_sa_t *this);
642:
643: /**
644: * Check if mappings have changed on a NAT for our source address.
645: *
646: * @param hash received DESTINATION_IP hash
647: * @return TRUE if mappings have changed
648: */
649: bool (*has_mapping_changed)(ike_sa_t *this, chunk_t hash);
650:
651: /**
652: * Enable an extension the peer supports.
653: *
654: * If support for an IKE extension is detected, this method is called
655: * to enable that extension and behave accordingly.
656: *
657: * @param extension extension to enable
658: */
659: void (*enable_extension)(ike_sa_t *this, ike_extension_t extension);
660:
661: /**
662: * Check if the peer supports an extension.
663: *
664: * @param extension extension to check for support
665: * @return TRUE if peer supports it, FALSE otherwise
666: */
667: bool (*supports_extension)(ike_sa_t *this, ike_extension_t extension);
668:
669: /**
670: * Enable/disable a condition flag for this IKE_SA.
671: *
672: * @param condition condition to enable/disable
673: * @param enable TRUE to enable condition, FALSE to disable
674: */
675: void (*set_condition) (ike_sa_t *this, ike_condition_t condition, bool enable);
676:
677: /**
678: * Check if a condition flag is set.
679: *
680: * @param condition condition to check
681: * @return TRUE if condition flag set, FALSE otherwise
682: */
683: bool (*has_condition) (ike_sa_t *this, ike_condition_t condition);
684:
685: #ifdef ME
686: /**
687: * Activate mediation server functionality for this IKE_SA.
688: */
689: void (*act_as_mediation_server) (ike_sa_t *this);
690:
691: /**
692: * Get the server reflexive host.
693: *
694: * @return server reflexive host
695: */
696: host_t* (*get_server_reflexive_host) (ike_sa_t *this);
697:
698: /**
699: * Set the server reflexive host.
700: *
701: * @param host server reflexive host
702: */
703: void (*set_server_reflexive_host) (ike_sa_t *this, host_t *host);
704:
705: /**
706: * Get the connect ID.
707: *
708: * @return connect ID
709: */
710: chunk_t (*get_connect_id) (ike_sa_t *this);
711:
712: /**
713: * Initiate the mediation of a mediated connection (i.e. initiate a
714: * ME_CONNECT exchange to a mediation server).
715: *
716: * @param mediated_cfg peer_cfg of the mediated connection
717: * @return
718: * - SUCCESS if initialization started
719: * - DESTROY_ME if initialization failed
720: */
721: status_t (*initiate_mediation) (ike_sa_t *this, peer_cfg_t *mediated_cfg);
722:
723: /**
724: * Initiate the mediated connection
725: *
726: * @param me local endpoint (gets cloned)
727: * @param other remote endpoint (gets cloned)
728: * @param connect_id connect ID (gets cloned)
729: * @return
730: * - SUCCESS if initialization started
731: * - DESTROY_ME if initialization failed
732: */
733: status_t (*initiate_mediated) (ike_sa_t *this, host_t *me, host_t *other,
734: chunk_t connect_id);
735:
736: /**
737: * Relay data from one peer to another (i.e. initiate a ME_CONNECT exchange
738: * to a peer).
739: *
740: * Data is cloned.
741: *
742: * @param requester ID of the requesting peer
743: * @param connect_id data of the ME_CONNECTID payload
744: * @param connect_key data of the ME_CONNECTKEY payload
745: * @param endpoints endpoints
746: * @param response TRUE if this is a response
747: * @return
748: * - SUCCESS if relay started
749: * - DESTROY_ME if relay failed
750: */
751: status_t (*relay) (ike_sa_t *this, identification_t *requester,
752: chunk_t connect_id, chunk_t connect_key,
753: linked_list_t *endpoints, bool response);
754:
755: /**
756: * Send a callback to a peer.
757: *
758: * Data is cloned.
759: *
760: * @param peer_id ID of the other peer
761: * @return
762: * - SUCCESS if response started
763: * - DESTROY_ME if response failed
764: */
765: status_t (*callback) (ike_sa_t *this, identification_t *peer_id);
766:
767: /**
768: * Respond to a ME_CONNECT request.
769: *
770: * Data is cloned.
771: *
772: * @param peer_id ID of the other peer
773: * @param connect_id the connect ID supplied by the initiator
774: * @return
775: * - SUCCESS if response started
776: * - DESTROY_ME if response failed
777: */
778: status_t (*respond) (ike_sa_t *this, identification_t *peer_id,
779: chunk_t connect_id);
780: #endif /* ME */
781:
782: /**
783: * Initiate a new connection.
784: *
785: * The configs are owned by the IKE_SA after the call. If the initiate
786: * is triggered by a packet, traffic selectors of the packet can be added
787: * to the CHILD_SA.
788: *
789: * @param child_cfg child config to create CHILD from
790: * @param reqid reqid to use for CHILD_SA, 0 assign uniquely
791: * @param tsi source of triggering packet
792: * @param tsr destination of triggering packet.
793: * @return
794: * - SUCCESS if initialization started
795: * - DESTROY_ME if initialization failed
796: */
797: status_t (*initiate) (ike_sa_t *this, child_cfg_t *child_cfg,
798: uint32_t reqid, traffic_selector_t *tsi,
799: traffic_selector_t *tsr);
800:
801: /**
802: * Retry initiation of this IKE_SA after it got deferred previously.
803: *
804: * @return
805: * - SUCCESS if initiation deferred or started
806: * - DESTROY_ME if initiation failed
807: */
808: status_t (*retry_initiate) (ike_sa_t *this);
809:
810: /**
811: * Initiates the deletion of an IKE_SA.
812: *
813: * Sends a delete message to the remote peer and waits for
814: * its response. If the response comes in, or a timeout occurs,
815: * the IKE SA gets destroyed, unless force is TRUE then the IKE_SA is
816: * destroyed immediately without waiting for a response.
817: *
818: * @param force whether to immediately destroy the IKE_SA afterwards
819: * without waiting for a response
820: * @return
821: * - SUCCESS if deletion is initialized
822: * - DESTROY_ME, if destroying is forced, or the IKE_SA
823: * is not in an established state and can not be
824: * deleted (but destroyed)
825: */
826: status_t (*delete) (ike_sa_t *this, bool force);
827:
828: /**
829: * Update IKE_SAs after network interfaces have changed.
830: *
831: * Whenever the network interface configuration changes, the kernel
832: * interface calls roam() on each IKE_SA. The IKE_SA then checks if
833: * the new network config requires changes, and handles appropriate.
834: * If MOBIKE is supported, addresses are updated; If not, the tunnel is
835: * restarted.
836: *
837: * @param address TRUE if address list changed, FALSE otherwise
838: * @return SUCCESS, FAILED, DESTROY_ME
839: */
840: status_t (*roam)(ike_sa_t *this, bool address);
841:
842: /**
843: * Processes an incoming IKE message.
844: *
845: * Message processing may fail. If a critical failure occurs,
846: * process_message() return DESTROY_ME. Then the caller must
847: * destroy the IKE_SA immediately, as it is unusable.
848: *
849: * @param message message to process
850: * @return
851: * - SUCCESS
852: * - FAILED
853: * - DESTROY_ME if this IKE_SA MUST be deleted
854: */
855: status_t (*process_message)(ike_sa_t *this, message_t *message);
856:
857: /**
858: * Generate an IKE message to send it to the peer.
859: *
860: * This method generates all payloads in the message and encrypts/signs
861: * the packet.
862: *
863: * @param message message to generate
864: * @param packet generated output packet
865: * @return
866: * - SUCCESS
867: * - FAILED
868: * - DESTROY_ME if this IKE_SA MUST be deleted
869: */
870: status_t (*generate_message)(ike_sa_t *this, message_t *message,
871: packet_t **packet);
872:
873: /**
874: * Generate an IKE message to send it to the peer. If enabled and supported
875: * it will be fragmented.
876: *
877: * This method generates all payloads in the message and encrypts/signs
878: * the packet/fragments.
879: *
880: * @param message message to generate
881: * @param packets enumerator of generated packet_t* (are not destroyed
882: * with the enumerator)
883: * @return
884: * - SUCCESS
885: * - FAILED
886: * - DESTROY_ME if this IKE_SA MUST be deleted
887: */
888: status_t (*generate_message_fragmented)(ike_sa_t *this, message_t *message,
889: enumerator_t **packets);
890:
891: /**
892: * Retransmits a request.
893: *
894: * @param message_id ID of the request to retransmit
895: * @return
896: * - SUCCESS if retransmit was sent
897: * - INVALID_STATE if no retransmit required
898: * - DESTROY_ME if this IKE_SA MUST be deleted
899: */
900: status_t (*retransmit)(ike_sa_t *this, uint32_t message_id);
901:
902: /**
903: * Sends a DPD request to the peer.
904: *
905: * To check if a peer is still alive, periodic
906: * empty INFORMATIONAL messages are sent if no
907: * other traffic was received.
908: *
909: * @return
910: * - SUCCESS
911: * - DESTROY_ME, if peer did not respond
912: */
913: status_t (*send_dpd) (ike_sa_t *this);
914:
915: /**
916: * Sends a keep alive packet.
917: *
918: * To refresh NAT tables in a NAT router between the peers, periodic empty
919: * UDP packets are sent if no other traffic was sent.
920: *
921: * @param scheduled if this is a scheduled keepalive
922: */
923: void (*send_keepalive) (ike_sa_t *this, bool scheduled);
924:
925: /**
926: * Redirect an active IKE_SA.
927: *
928: * @param gateway gateway ID (IP or FQDN) of the target
929: * @return state, including DESTROY_ME, if this IKE_SA MUST be
930: * destroyed
931: */
932: status_t (*redirect)(ike_sa_t *this, identification_t *gateway);
933:
934: /**
935: * Handle a redirect request.
936: *
937: * The behavior is different depending on the state of the IKE_SA.
938: *
939: * @param gateway gateway ID (IP or FQDN) of the target
940: * @return FALSE if redirect not possible, TRUE otherwise
941: */
942: bool (*handle_redirect)(ike_sa_t *this, identification_t *gateway);
943:
944: /**
945: * Get the address of the gateway that redirected us.
946: *
947: * @return original gateway address
948: */
949: host_t *(*get_redirected_from)(ike_sa_t *this);
950:
951: /**
952: * Get the keying material of this IKE_SA.
953: *
954: * @return per IKE_SA keymat instance
955: */
956: keymat_t* (*get_keymat)(ike_sa_t *this);
957:
958: /**
959: * Associates a child SA to this IKE SA
960: *
961: * @param child_sa child_sa to add
962: */
963: void (*add_child_sa) (ike_sa_t *this, child_sa_t *child_sa);
964:
965: /**
966: * Get a CHILD_SA identified by protocol and SPI.
967: *
968: * @param protocol protocol of the SA
969: * @param spi SPI of the CHILD_SA
970: * @param inbound TRUE if SPI is inbound, FALSE if outbound
971: * @return child_sa, or NULL if none found
972: */
973: child_sa_t* (*get_child_sa) (ike_sa_t *this, protocol_id_t protocol,
974: uint32_t spi, bool inbound);
975:
976: /**
977: * Get the number of CHILD_SAs.
978: *
979: * @return number of CHILD_SAs
980: */
981: int (*get_child_count) (ike_sa_t *this);
982:
983: /**
984: * Create an enumerator over all CHILD_SAs.
985: *
986: * @return enumerator
987: */
988: enumerator_t* (*create_child_sa_enumerator) (ike_sa_t *this);
989:
990: /**
991: * Remove the CHILD_SA the given enumerator points to from this IKE_SA.
992: *
993: * @param enumerator enumerator pointing to CHILD_SA
994: */
995: void (*remove_child_sa) (ike_sa_t *this, enumerator_t *enumerator);
996:
997: /**
998: * Rekey the CHILD SA with the specified reqid.
999: *
1000: * Looks for a CHILD SA owned by this IKE_SA, and start the rekeing.
1001: *
1002: * @param protocol protocol of the SA
1003: * @param spi inbound SPI of the CHILD_SA
1004: * @return
1005: * - NOT_FOUND, if IKE_SA has no such CHILD_SA
1006: * - SUCCESS, if rekeying initiated
1007: */
1008: status_t (*rekey_child_sa) (ike_sa_t *this, protocol_id_t protocol, uint32_t spi);
1009:
1010: /**
1011: * Close the CHILD SA with the specified protocol/SPI.
1012: *
1013: * Looks for a CHILD SA owned by this IKE_SA, deletes it and
1014: * notify's the remote peer about the delete. The associated
1015: * states and policies in the kernel get deleted, if they exist.
1016: *
1017: * @param protocol protocol of the SA
1018: * @param spi inbound SPI of the CHILD_SA
1019: * @param expired TRUE if CHILD_SA is expired
1020: * @return
1021: * - NOT_FOUND, if IKE_SA has no such CHILD_SA
1022: * - SUCCESS, if delete message sent
1023: */
1024: status_t (*delete_child_sa)(ike_sa_t *this, protocol_id_t protocol,
1025: uint32_t spi, bool expired);
1026:
1027: /**
1028: * Destroy a CHILD SA with the specified protocol/SPI.
1029: *
1030: * Looks for a CHILD SA owned by this IKE_SA and destroys it.
1031: *
1032: * @param protocol protocol of the SA
1033: * @param spi inbound SPI of the CHILD_SA
1034: * @return
1035: * - NOT_FOUND, if IKE_SA has no such CHILD_SA
1036: * - SUCCESS
1037: */
1038: status_t (*destroy_child_sa) (ike_sa_t *this, protocol_id_t protocol, uint32_t spi);
1039:
1040: /**
1041: * Rekey the IKE_SA.
1042: *
1043: * Sets up a new IKE_SA, moves all CHILD_SAs to it and deletes this IKE_SA.
1044: *
1045: * @return - SUCCESS, if IKE_SA rekeying initiated
1046: */
1047: status_t (*rekey) (ike_sa_t *this);
1048:
1049: /**
1050: * Reauthenticate the IKE_SA.
1051: *
1052: * Triggers a new IKE_SA that replaces this one. IKEv1 implicitly inherits
1053: * all Quick Modes, while IKEv2 recreates all active and queued CHILD_SAs
1054: * in the new IKE_SA.
1055: *
1056: * @return DESTROY_ME to destroy the IKE_SA
1057: */
1058: status_t (*reauth) (ike_sa_t *this);
1059:
1060: /**
1061: * Reestablish the IKE_SA.
1062: *
1063: * Reestablish an IKE_SA after it has been closed.
1064: *
1065: * @return DESTROY_ME to destroy the IKE_SA
1066: */
1067: status_t (*reestablish) (ike_sa_t *this);
1068:
1069: /**
1070: * Set the lifetime limit received/to send in a AUTH_LIFETIME notify.
1071: *
1072: * If the IKE_SA is already ESTABLISHED, an INFORMATIONAL is sent with
1073: * an AUTH_LIFETIME notify. The call never fails on unestablished SAs.
1074: *
1075: * @param lifetime lifetime in seconds
1076: * @return DESTROY_ME to destroy the IKE_SA
1077: */
1078: status_t (*set_auth_lifetime)(ike_sa_t *this, uint32_t lifetime);
1079:
1080: /**
1081: * Add a virtual IP to use for this IKE_SA and its children.
1082: *
1083: * The virtual IP is assigned per IKE_SA, not per CHILD_SA. It has the same
1084: * lifetime as the IKE_SA.
1085: *
1086: * @param local TRUE to set local address, FALSE for remote
1087: * @param ip IP to set as virtual IP
1088: */
1089: void (*add_virtual_ip) (ike_sa_t *this, bool local, host_t *ip);
1090:
1091: /**
1092: * Clear all virtual IPs stored on this IKE_SA.
1093: *
1094: * @param local TRUE to clear local addresses, FALSE for remote
1095: */
1096: void (*clear_virtual_ips) (ike_sa_t *this, bool local);
1097:
1098: /**
1099: * Get interface ID to use as default for children of this IKE_SA.
1100: *
1101: * @param inbound TRUE for inbound interface ID
1102: * @return interface ID
1103: */
1104: uint32_t (*get_if_id)(ike_sa_t *this, bool inbound);
1105:
1106: /**
1107: * Create an enumerator over virtual IPs.
1108: *
1109: * @param local TRUE to get local virtual IP, FALSE for remote
1110: * @return enumerator over host_t*
1111: */
1112: enumerator_t* (*create_virtual_ip_enumerator) (ike_sa_t *this, bool local);
1113:
1114: /**
1115: * Register a configuration attribute to the IKE_SA.
1116: *
1117: * If an IRAS sends a configuration attribute it is installed and
1118: * registered at the IKE_SA. Attributes are inherit()ed and get released
1119: * when the IKE_SA is closed.
1120: *
1121: * Unhandled attributes are passed as well, but with a NULL handler. They
1122: * do not get released.
1123: *
1124: * @param handler handler installed the attribute, use for release()
1125: * @param type configuration attribute type
1126: * @param data associated attribute data
1127: */
1128: void (*add_configuration_attribute)(ike_sa_t *this,
1129: attribute_handler_t *handler,
1130: configuration_attribute_type_t type, chunk_t data);
1131:
1132: /**
1133: * Create an enumerator over received configuration attributes.
1134: *
1135: * The resulting enumerator is over the configuration_attribute_type_t type,
1136: * a value chunk_t followed by a bool flag. The boolean flag indicates if
1137: * the attribute has been handled by an attribute handler.
1138: *
1139: * @return enumerator over type, value and the "handled" flag.
1140: */
1141: enumerator_t* (*create_attribute_enumerator)(ike_sa_t *this);
1142:
1143: /**
1144: * Set local and remote host addresses to be used for IKE.
1145: *
1146: * These addresses are communicated via the KMADDRESS field of a MIGRATE
1147: * message sent via the NETLINK or PF _KEY kernel socket interface.
1148: *
1149: * @param local local kmaddress
1150: * @param remote remote kmaddress
1151: */
1152: void (*set_kmaddress) (ike_sa_t *this, host_t *local, host_t *remote);
1153:
1154: /**
1155: * Create enumerator over a task queue of this IKE_SA.
1156: *
1157: * @param queue type to enumerate
1158: * @return enumerator over task_t
1159: */
1160: enumerator_t* (*create_task_enumerator)(ike_sa_t *this, task_queue_t queue);
1161:
1162: /**
1163: * Remove the task the given enumerator points to.
1164: *
1165: * @note This should be used with caution, in particular, for tasks in the
1166: * active and passive queues.
1167: *
1168: * @param enumerator enumerator created with the method above
1169: */
1170: void (*remove_task)(ike_sa_t *this, enumerator_t *enumerator);
1171:
1172: /**
1173: * Flush a task queue, cancelling all tasks in it.
1174: *
1175: * @param queue queue type to flush
1176: */
1177: void (*flush_queue)(ike_sa_t *this, task_queue_t queue);
1178:
1179: /**
1180: * Queue a task for initiation to the task manager.
1181: *
1182: * @param task task to queue
1183: */
1184: void (*queue_task)(ike_sa_t *this, task_t *task);
1185:
1186: /**
1187: * Queue a task in the manager, but delay its initiation for at least the
1188: * given number of seconds.
1189: *
1190: * @param task task to queue
1191: * @param delay minimum delay in s before initiating the task
1192: */
1193: void (*queue_task_delayed)(ike_sa_t *this, task_t *task, uint32_t delay);
1194:
1195: /**
1196: * Adopt child creating tasks from the given IKE_SA.
1197: *
1198: * @param other other IKE_SA to adopt tasks from
1199: */
1200: void (*adopt_child_tasks)(ike_sa_t *this, ike_sa_t *other);
1201:
1202: /**
1203: * Inherit required attributes to new SA before rekeying.
1204: *
1205: * Some properties of the SA must be applied before starting IKE_SA
1206: * rekeying, such as the configuration or support extensions.
1207: *
1208: * @param other other IKE_SA to inherit from
1209: */
1210: void (*inherit_pre)(ike_sa_t *this, ike_sa_t *other);
1211:
1212: /**
1213: * Inherit all attributes of other to this after rekeying.
1214: *
1215: * When rekeying is completed, all CHILD_SAs, the virtual IP and all
1216: * outstanding tasks are moved from other to this.
1217: *
1218: * @param other other IKE SA to inherit from
1219: */
1220: void (*inherit_post) (ike_sa_t *this, ike_sa_t *other);
1221:
1222: /**
1223: * Reset the IKE_SA, usable when initiating fails.
1224: *
1225: * @param new_spi TRUE to allocate a new initiator SPI
1226: */
1227: void (*reset) (ike_sa_t *this, bool new_spi);
1228:
1229: /**
1230: * Destroys a ike_sa_t object.
1231: */
1232: void (*destroy) (ike_sa_t *this);
1233: };
1234:
1235: /**
1236: * Creates an ike_sa_t object with a specific ID and IKE version.
1237: *
1238: * @param ike_sa_id ike_sa_id_t to associate with new IKE_SA/ISAKMP_SA
1239: * @param initiator TRUE to create this IKE_SA as initiator
1240: * @param version IKE version of this SA
1241: * @return ike_sa_t object
1242: */
1243: ike_sa_t *ike_sa_create(ike_sa_id_t *ike_sa_id, bool initiator,
1244: ike_version_t version);
1245:
1246: #endif /** IKE_SA_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ike_sa.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libcharon / sa