src/libcharon/sa/ike_sa.h

   1 /*
   2  * Copyright (C) 2006-2012 Tobias Brunner
   3  * Copyright (C) 2006 Daniel Roethlisberger
   4  * Copyright (C) 2005-2009 Martin Willi
   5  * Copyright (C) 2005 Jan Hutter
   6  * 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 struct ike_sa_t ike_sa_t;
  32
  33 #include <library.h>
  34 #include <attributes/attribute_handler.h>
  35 #include <encoding/message.h>
  36 #include <encoding/payloads/proposal_substructure.h>
  37 #include <encoding/payloads/configuration_attribute.h>
  38 #include <sa/ike_sa_id.h>
  39 #include <sa/child_sa.h>
  40 #include <sa/task.h>
  41 #include <sa/task_manager.h>
  42 #include <sa/keymat.h>
  43 #include <config/peer_cfg.h>
  44 #include <config/ike_cfg.h>
  45 #include <credentials/auth_cfg.h>
  46
  47 /**
  48  * Timeout in seconds after that a half open IKE_SA gets deleted.
  49  */
  50 #define HALF_OPEN_IKE_SA_TIMEOUT 30
  51
  52 /**
  53  * Interval to send keepalives when NATed, in seconds.
  54  */
  55 #define KEEPALIVE_INTERVAL 20
  56
  57 /**
  58  * After which time rekeying should be retried if it failed, in seconds.
  59  */
  60 #define RETRY_INTERVAL 30
  61
  62 /**
  63  * Jitter to subtract from RETRY_INTERVAL to randomize rekey retry.
  64  */
  65 #define RETRY_JITTER 20
  66
  67 /**
  68  * Extensions (or optional features) the peer supports
  69  */
  70 enum ike_extension_t {
  71
  72         /**
  73          * peer supports NAT traversal as specified in RFC4306 or RFC3947
  74          */
  75         EXT_NATT = (1<<0),
  76
  77         /**
  78          * peer supports MOBIKE (RFC4555)
  79          */
  80         EXT_MOBIKE = (1<<1),
  81
  82         /**
  83          * peer supports HTTP cert lookups as specified in RFC4306
  84          */
  85         EXT_HASH_AND_URL = (1<<2),
  86
  87         /**
  88          * peer supports multiple authentication exchanges, RFC4739
  89          */
  90         EXT_MULTIPLE_AUTH = (1<<3),
  91
  92         /**
  93          * peer uses strongSwan, accept private use extensions
  94          */
  95         EXT_STRONGSWAN = (1<<4),
  96
  97         /**
  98          * peer supports EAP-only authentication, draft-eronen-ipsec-ikev2-eap-auth
  99          */
 100         EXT_EAP_ONLY_AUTHENTICATION = (1<<5),
 101
 102         /**
 103          * peer is probably a Windows 7 RAS client
 104          */
 105         EXT_MS_WINDOWS = (1<<6),
 106
 107         /**
 108          * peer supports XAuth authentication, draft-ietf-ipsec-isakmp-xauth-06
 109          */
 110         EXT_XAUTH = (1<<7),
 111
 112         /**
 113          * peer supports DPD detection, RFC 3706 (or IKEv2)
 114          */
 115         EXT_DPD = (1<<8),
 116 };
 117
 118 /**
 119  * Conditions of an IKE_SA, change during its lifetime
 120  */
 121 enum ike_condition_t {
 122
 123         /**
 124          * Connection is natted (or faked) somewhere
 125          */
 126         COND_NAT_ANY = (1<<0),
 127
 128         /**
 129          * we are behind NAT
 130          */
 131         COND_NAT_HERE = (1<<1),
 132
 133         /**
 134          * other is behind NAT
 135          */
 136         COND_NAT_THERE = (1<<2),
 137
 138         /**
 139          * Faking NAT to enforce UDP encapsulation
 140          */
 141         COND_NAT_FAKE = (1<<3),
 142
 143         /**
 144          * peer has been authenticated using EAP at least once
 145          */
 146         COND_EAP_AUTHENTICATED = (1<<4),
 147
 148         /**
 149          * received a certificate request from the peer
 150          */
 151         COND_CERTREQ_SEEN = (1<<5),
 152
 153         /**
 154          * Local peer is the "original" IKE initiator. Unaffected from rekeying.
 155          */
 156         COND_ORIGINAL_INITIATOR = (1<<6),
 157
 158         /**
 159          * IKE_SA is stale, the peer is currently unreachable (MOBIKE)
 160          */
 161         COND_STALE = (1<<7),
 162
 163         /**
 164          * Initial contact received
 165          */
 166         COND_INIT_CONTACT_SEEN = (1<<8),
 167
 168         /**
 169          * Peer has been authenticated using XAuth
 170          */
 171         COND_XAUTH_AUTHENTICATED = (1<<9),
 172 };
 173
 174 /**
 175  * Timing information and statistics to query from an SA
 176  */
 177 enum statistic_t {
 178         /** Timestamp of SA establishement */
 179         STAT_ESTABLISHED = 0,
 180         /** Timestamp of scheudled rekeying */
 181         STAT_REKEY,
 182         /** Timestamp of scheudled reauthentication */
 183         STAT_REAUTH,
 184         /** Timestamp of scheudled delete */
 185         STAT_DELETE,
 186         /** Timestamp of last inbound IKE packet */
 187         STAT_INBOUND,
 188         /** Timestamp of last outbound IKE packet */
 189         STAT_OUTBOUND,
 190
 191         STAT_MAX
 192 };
 193
 194 /**
 195  * State of an IKE_SA.
 196  *
 197  * An IKE_SA passes various states in its lifetime. A newly created
 198  * SA is in the state CREATED.
 199  * @verbatim
 200                  +----------------+
 201                  ¦   SA_CREATED   ¦
 202                  +----------------+
 203                          ¦
 204     on initiate()--->    ¦   <----- on IKE_SA_INIT received
 205                          V
 206                  +----------------+
 207                  ¦ SA_CONNECTING  ¦
 208                  +----------------+
 209                          ¦
 210                          ¦   <----- on IKE_AUTH successfully completed
 211                          V
 212                  +----------------+
 213                  ¦ SA_ESTABLISHED ¦-------------------------+ <-- on rekeying
 214                  +----------------+                         ¦
 215                          ¦                                  V
 216     on delete()--->      ¦   <----- on IKE_SA        +-------------+
 217                          ¦          delete request   ¦ SA_REKEYING ¦
 218                          ¦          received         +-------------+
 219                          V                                  ¦
 220                  +----------------+                         ¦
 221                  ¦  SA_DELETING   ¦<------------------------+ <-- after rekeying
 222                  +----------------+
 223                          ¦
 224                          ¦   <----- after delete() acknowledged
 225                          ¦
 226                         \V/
 227                          X
 228                         / \
 229    @endverbatim
 230  */
 231 enum ike_sa_state_t {
 232
 233         /**
 234          * IKE_SA just got created, but is not initiating nor responding yet.
 235          */
 236         IKE_CREATED,
 237
 238         /**
 239          * IKE_SA gets initiated actively or passively
 240          */
 241         IKE_CONNECTING,
 242
 243         /**
 244          * IKE_SA is fully established
 245          */
 246         IKE_ESTABLISHED,
 247
 248         /**
 249          * IKE_SA is managed externally and does not process messages
 250          */
 251         IKE_PASSIVE,
 252
 253         /**
 254          * IKE_SA rekeying in progress
 255          */
 256         IKE_REKEYING,
 257
 258         /**
 259          * IKE_SA is in progress of deletion
 260          */
 261         IKE_DELETING,
 262
 263         /**
 264          * IKE_SA object gets destroyed
 265          */
 266         IKE_DESTROYING,
 267 };
 268
 269 /**
 270  * enum names for ike_sa_state_t.
 271  */
 272 extern enum_name_t *ike_sa_state_names;
 273
 274 /**
 275  * Class ike_sa_t representing an IKE_SA.
 276  *
 277  * An IKE_SA contains crypto information related to a connection
 278  * with a peer. It contains multiple IPsec CHILD_SA, for which
 279  * it is responsible. All traffic is handled by an IKE_SA, using
 280  * the task manager and its tasks.
 281  */
 282 struct ike_sa_t {
 283
 284         /**
 285          * Get the id of the SA.
 286          *
 287          * Returned ike_sa_id_t object is not getting cloned!
 288          *
 289          * @return                              ike_sa's ike_sa_id_t
 290          */
 291         ike_sa_id_t* (*get_id) (ike_sa_t *this);
 292
 293         /**
 294          * Gets the IKE version of the SA
 295          */
 296         ike_version_t (*get_version)(ike_sa_t *this);
 297
 298         /**
 299          * Get the numerical ID uniquely defining this IKE_SA.
 300          *
 301          * @return                              unique ID
 302          */
 303         u_int32_t (*get_unique_id) (ike_sa_t *this);
 304
 305         /**
 306          * Get the state of the IKE_SA.
 307          *
 308          * @return                              state of the IKE_SA
 309          */
 310         ike_sa_state_t (*get_state) (ike_sa_t *this);
 311
 312         /**
 313          * Set the state of the IKE_SA.
 314          *
 315          * @param state                 state to set for the IKE_SA
 316          */
 317         void (*set_state) (ike_sa_t *this, ike_sa_state_t state);
 318
 319         /**
 320          * Get the name of the connection this IKE_SA uses.
 321          *
 322          * @return                              name
 323          */
 324         char* (*get_name) (ike_sa_t *this);
 325
 326         /**
 327          * Get statistic values from the IKE_SA.
 328          *
 329          * @param kind                  kind of requested value
 330          * @return                              value as integer
 331          */
 332         u_int32_t (*get_statistic)(ike_sa_t *this, statistic_t kind);
 333
 334         /**
 335          * Set statistic value of the IKE_SA.
 336          *
 337          * @param kind                  kind of value to update
 338          * @param value                 value as integer
 339          */
 340         void (*set_statistic)(ike_sa_t *this, statistic_t kind, u_int32_t value);
 341
 342         /**
 343          * Get the own host address.
 344          *
 345          * @return                              host address
 346          */
 347         host_t* (*get_my_host) (ike_sa_t *this);
 348
 349         /**
 350          * Set the own host address.
 351          *
 352          * @param me                    host address
 353          */
 354         void (*set_my_host) (ike_sa_t *this, host_t *me);
 355
 356         /**
 357          * Get the other peers host address.
 358          *
 359          * @return                              host address
 360          */
 361         host_t* (*get_other_host) (ike_sa_t *this);
 362
 363         /**
 364          * Set the others host address.
 365          *
 366          * @param other                 host address
 367          */
 368         void (*set_other_host) (ike_sa_t *this, host_t *other);
 369
 370         /**
 371          * Float to port 4500 (e.g. if a NAT is detected).
 372          *
 373          * The port of either endpoint is changed only if it is currently
 374          * set to the default value of 500.
 375          */
 376         void (*float_ports)(ike_sa_t *this);
 377
 378         /**
 379          * Update the IKE_SAs host.
 380          *
 381          * Hosts may be NULL to use current host.
 382          *
 383          * @param me                    new local host address, or NULL
 384          * @param other                 new remote host address, or NULL
 385          * @param force                 force update
 386          */
 387         void (*update_hosts)(ike_sa_t *this, host_t *me, host_t *other, bool force);
 388
 389         /**
 390          * Get the own identification.
 391          *
 392          * @return                              identification
 393          */
 394         identification_t* (*get_my_id) (ike_sa_t *this);
 395
 396         /**
 397          * Set the own identification.
 398          *
 399          * @param me                    identification
 400          */
 401         void (*set_my_id) (ike_sa_t *this, identification_t *me);
 402
 403         /**
 404          * Get the other peer's identification.
 405          *
 406          * @return                              identification
 407          */
 408         identification_t* (*get_other_id) (ike_sa_t *this);
 409
 410         /**
 411          * Get the others peer identity, but prefer an EAP-Identity.
 412          *
 413          * @return                              EAP or IKEv2 identity
 414          */
 415         identification_t* (*get_other_eap_id)(ike_sa_t *this);
 416
 417         /**
 418          * Set the other peer's identification.
 419          *
 420          * @param other                 identification
 421          */
 422         void (*set_other_id) (ike_sa_t *this, identification_t *other);
 423
 424         /**
 425          * Get the config used to setup this IKE_SA.
 426          *
 427          * @return                              ike_config
 428          */
 429         ike_cfg_t* (*get_ike_cfg) (ike_sa_t *this);
 430
 431         /**
 432          * Set the config to setup this IKE_SA.
 433          *
 434          * @param config                ike_config to use
 435          */
 436         void (*set_ike_cfg) (ike_sa_t *this, ike_cfg_t* config);
 437
 438         /**
 439          * Get the peer config used by this IKE_SA.
 440          *
 441          * @return                              peer_config
 442          */
 443         peer_cfg_t* (*get_peer_cfg) (ike_sa_t *this);
 444
 445         /**
 446          * Set the peer config to use with this IKE_SA.
 447          *
 448          * @param config                peer_config to use
 449          */
 450         void (*set_peer_cfg) (ike_sa_t *this, peer_cfg_t *config);
 451
 452         /**
 453          * Get the authentication config with rules of the current auth round.
 454          *
 455          * @param local                 TRUE for local rules, FALSE for remote constraints
 456          * @return                              current cfg
 457          */
 458         auth_cfg_t* (*get_auth_cfg)(ike_sa_t *this, bool local);
 459
 460         /**
 461          * Insert a completed authentication round.
 462          *
 463          * @param local                 TRUE for own rules, FALSE for others constraints
 464          * @param cfg                   auth config to append
 465          */
 466         void (*add_auth_cfg)(ike_sa_t *this, bool local, auth_cfg_t *cfg);
 467
 468         /**
 469          * Create an enumerator over added authentication rounds.
 470          *
 471          * @param local                 TRUE for own rules, FALSE for others constraints
 472          * @return                              enumerator over auth_cfg_t
 473          */
 474         enumerator_t* (*create_auth_cfg_enumerator)(ike_sa_t *this, bool local);
 475
 476         /**
 477          * Get the selected proposal of this IKE_SA.
 478          *
 479          * @return                              selected proposal
 480          */
 481         proposal_t* (*get_proposal)(ike_sa_t *this);
 482
 483         /**
 484          * Set the proposal selected for this IKE_SA.
 485          *
 486          * @param                               selected proposal
 487          */
 488         void (*set_proposal)(ike_sa_t *this, proposal_t *proposal);
 489
 490         /**
 491          * Set the message id of the IKE_SA.
 492          *
 493          * The IKE_SA stores two message IDs, one for initiating exchanges (send)
 494          * and one to respond to exchanges (expect).
 495          *
 496          * @param initiate              TRUE to set message ID for initiating
 497          * @param mid                   message id to set
 498          */
 499         void (*set_message_id)(ike_sa_t *this, bool initiate, u_int32_t mid);
 500
 501         /**
 502          * Add an additional address for the peer.
 503          *
 504          * In MOBIKE, a peer may transmit additional addresses where it is
 505          * reachable. These are stored in the IKE_SA.
 506          * The own list of addresses is not stored, they are queried from
 507          * the kernel when required.
 508          *
 509          * @param host                  host to add to list
 510          */
 511         void (*add_peer_address)(ike_sa_t *this, host_t *host);
 512
 513         /**
 514          * Create an enumerator over all known addresses of the peer.
 515          *
 516          * @return                              enumerator over addresses
 517          */
 518         enumerator_t* (*create_peer_address_enumerator)(ike_sa_t *this);
 519
 520         /**
 521          * Remove all known addresses of the peer.
 522          */
 523         void (*clear_peer_addresses)(ike_sa_t *this);
 524
 525         /**
 526          * Check if mappings have changed on a NAT for our source address.
 527          *
 528          * @param hash                  received DESTINATION_IP hash
 529          * @return                              TRUE if mappings have changed
 530          */
 531         bool (*has_mapping_changed)(ike_sa_t *this, chunk_t hash);
 532
 533         /**
 534          * Enable an extension the peer supports.
 535          *
 536          * If support for an IKE extension is detected, this method is called
 537          * to enable that extension and behave accordingly.
 538          *
 539          * @param extension             extension to enable
 540          */
 541         void (*enable_extension)(ike_sa_t *this, ike_extension_t extension);
 542
 543         /**
 544          * Check if the peer supports an extension.
 545          *
 546          * @param extension             extension to check for support
 547          * @return                              TRUE if peer supports it, FALSE otherwise
 548          */
 549         bool (*supports_extension)(ike_sa_t *this, ike_extension_t extension);
 550
 551         /**
 552          * Enable/disable a condition flag for this IKE_SA.
 553          *
 554          * @param condition             condition to enable/disable
 555          * @param enable                TRUE to enable condition, FALSE to disable
 556          */
 557         void (*set_condition) (ike_sa_t *this, ike_condition_t condition, bool enable);
 558
 559         /**
 560          * Check if a condition flag is set.
 561          *
 562          * @param condition             condition to check
 563          * @return                              TRUE if condition flag set, FALSE otherwise
 564          */
 565         bool (*has_condition) (ike_sa_t *this, ike_condition_t condition);
 566
 567         /**
 568          * Get the number of queued MOBIKE address updates.
 569          *
 570          * @return                              number of pending updates
 571          */
 572         u_int32_t (*get_pending_updates)(ike_sa_t *this);
 573
 574         /**
 575          * Set the number of queued MOBIKE address updates.
 576          *
 577          * @param updates               number of pending updates
 578          */
 579         void (*set_pending_updates)(ike_sa_t *this, u_int32_t updates);
 580
 581 #ifdef ME
 582         /**
 583          * Activate mediation server functionality for this IKE_SA.
 584          */
 585         void (*act_as_mediation_server) (ike_sa_t *this);
 586
 587         /**
 588          * Get the server reflexive host.
 589          *
 590          * @return                              server reflexive host
 591          */
 592         host_t* (*get_server_reflexive_host) (ike_sa_t *this);
 593
 594         /**
 595          * Set the server reflexive host.
 596          *
 597          * @param host                  server reflexive host
 598          */
 599         void (*set_server_reflexive_host) (ike_sa_t *this, host_t *host);
 600
 601         /**
 602          * Get the connect ID.
 603          *
 604          * @return                              connect ID
 605          */
 606         chunk_t (*get_connect_id) (ike_sa_t *this);
 607
 608         /**
 609          * Initiate the mediation of a mediated connection (i.e. initiate a
 610          * ME_CONNECT exchange to a mediation server).
 611          *
 612          * @param mediated_cfg  peer_cfg of the mediated connection
 613          * @return
 614          *                                              - SUCCESS if initialization started
 615          *                                              - DESTROY_ME if initialization failed
 616          */
 617         status_t (*initiate_mediation) (ike_sa_t *this, peer_cfg_t *mediated_cfg);
 618
 619         /**
 620          * Initiate the mediated connection
 621          *
 622          * @param me                    local endpoint (gets cloned)
 623          * @param other                 remote endpoint (gets cloned)
 624          * @param connect_id    connect ID (gets cloned)
 625          * @return
 626          *                                              - SUCCESS if initialization started
 627          *                                              - DESTROY_ME if initialization failed
 628          */
 629         status_t (*initiate_mediated) (ike_sa_t *this, host_t *me, host_t *other,
 630                                                                    chunk_t connect_id);
 631
 632         /**
 633          * Relay data from one peer to another (i.e. initiate a ME_CONNECT exchange
 634          * to a peer).
 635          *
 636          * Data is cloned.
 637          *
 638          * @param requester             ID of the requesting peer
 639          * @param connect_id    data of the ME_CONNECTID payload
 640          * @param connect_key   data of the ME_CONNECTKEY payload
 641          * @param endpoints             endpoints
 642          * @param response              TRUE if this is a response
 643          * @return
 644          *                                              - SUCCESS if relay started
 645          *                                              - DESTROY_ME if relay failed
 646          */
 647         status_t (*relay) (ike_sa_t *this, identification_t *requester,
 648                                            chunk_t connect_id, chunk_t connect_key,
 649                                            linked_list_t *endpoints, bool response);
 650
 651         /**
 652          * Send a callback to a peer.
 653          *
 654          * Data is cloned.
 655          *
 656          * @param peer_id               ID of the other peer
 657          * @return
 658          *                                              - SUCCESS if response started
 659          *                                              - DESTROY_ME if response failed
 660          */
 661         status_t (*callback) (ike_sa_t *this, identification_t *peer_id);
 662
 663         /**
 664          * Respond to a ME_CONNECT request.
 665          *
 666          * Data is cloned.
 667          *
 668          * @param peer_id               ID of the other peer
 669          * @param connect_id    the connect ID supplied by the initiator
 670          * @return
 671          *                                              - SUCCESS if response started
 672          *                                              - DESTROY_ME if response failed
 673          */
 674         status_t (*respond) (ike_sa_t *this, identification_t *peer_id,
 675                                                  chunk_t connect_id);
 676 #endif /* ME */
 677
 678         /**
 679          * Initiate a new connection.
 680          *
 681          * The configs are owned by the IKE_SA after the call. If the initiate
 682          * is triggered by a packet, traffic selectors of the packet can be added
 683          * to the CHILD_SA.
 684          *
 685          * @param child_cfg             child config to create CHILD from
 686          * @param reqid                 reqid to use for CHILD_SA, 0 assigne uniquely
 687          * @param tsi                   source of triggering packet
 688          * @param tsr                   destination of triggering packet.
 689          * @return
 690          *                                              - SUCCESS if initialization started
 691          *                                              - DESTROY_ME if initialization failed
 692          */
 693         status_t (*initiate) (ike_sa_t *this, child_cfg_t *child_cfg,
 694                                                   u_int32_t reqid, traffic_selector_t *tsi,
 695                                                   traffic_selector_t *tsr);
 696
 697         /**
 698          * Retry initiation of this IKE_SA after it got deferred previously.
 699          *
 700          * @return
 701          *                                              - SUCCESS if initiation deferred or started
 702          *                                              - DESTROY_ME if initiation failed
 703          */
 704         status_t (*retry_initiate) (ike_sa_t *this);
 705
 706         /**
 707          * Initiates the deletion of an IKE_SA.
 708          *
 709          * Sends a delete message to the remote peer and waits for
 710          * its response. If the response comes in, or a timeout occurs,
 711          * the IKE SA gets deleted.
 712          *
 713          * @return
 714          *                                              - SUCCESS if deletion is initialized
 715          *                                              - DESTROY_ME, if the IKE_SA is not in
 716          *                                                an established state and can not be
 717          *                                                deleted (but destroyed).
 718          */
 719         status_t (*delete) (ike_sa_t *this);
 720
 721         /**
 722          * Update IKE_SAs after network interfaces have changed.
 723          *
 724          * Whenever the network interface configuration changes, the kernel
 725          * interface calls roam() on each IKE_SA. The IKE_SA then checks if
 726          * the new network config requires changes, and handles appropriate.
 727          * If MOBIKE is supported, addresses are updated; If not, the tunnel is
 728          * restarted.
 729          *
 730          * @param address               TRUE if address list changed, FALSE otherwise
 731          * @return                              SUCCESS, FAILED, DESTROY_ME
 732          */
 733         status_t (*roam)(ike_sa_t *this, bool address);
 734
 735         /**
 736          * Processes a incoming IKEv2-Message.
 737          *
 738          * Message processing may fail. If a critical failure occurs,
 739          * process_message() return DESTROY_ME. Then the caller must
 740          * destroy the IKE_SA immediately, as it is unusable.
 741          *
 742          * @param message               message to process
 743          * @return
 744          *                                              - SUCCESS
 745          *                                              - FAILED
 746          *                                              - DESTROY_ME if this IKE_SA MUST be deleted
 747          */
 748         status_t (*process_message) (ike_sa_t *this, message_t *message);
 749
 750         /**
 751          * Generate a IKE message to send it to the peer.
 752          *
 753          * This method generates all payloads in the message and encrypts/signs
 754          * the packet.
 755          *
 756          * @param message               message to generate
 757          * @param packet                generated output packet
 758          * @return
 759          *                                              - SUCCESS
 760          *                                              - FAILED
 761          *                                              - DESTROY_ME if this IKE_SA MUST be deleted
 762          */
 763         status_t (*generate_message) (ike_sa_t *this, message_t *message,
 764                                                                   packet_t **packet);
 765
 766         /**
 767          * Retransmits a request.
 768          *
 769          * @param message_id    ID of the request to retransmit
 770          * @return
 771          *                                              - SUCCESS
 772          *                                              - NOT_FOUND if request doesn't have to be retransmited
 773          */
 774         status_t (*retransmit) (ike_sa_t *this, u_int32_t message_id);
 775
 776         /**
 777          * Sends a DPD request to the peer.
 778          *
 779          * To check if a peer is still alive, periodic
 780          * empty INFORMATIONAL messages are sent if no
 781          * other traffic was received.
 782          *
 783          * @return
 784          *                                              - SUCCESS
 785          *                                              - DESTROY_ME, if peer did not respond
 786          */
 787         status_t (*send_dpd) (ike_sa_t *this);
 788
 789         /**
 790          * Sends a keep alive packet.
 791          *
 792          * To refresh NAT tables in a NAT router
 793          * between the peers, periodic empty
 794          * UDP packets are sent if no other traffic
 795          * was sent.
 796          */
 797         void (*send_keepalive) (ike_sa_t *this);
 798
 799         /**
 800          * Get the keying material of this IKE_SA.
 801          *
 802          * @return                              per IKE_SA keymat instance
 803          */
 804         keymat_t* (*get_keymat)(ike_sa_t *this);
 805
 806         /**
 807          * Associates a child SA to this IKE SA
 808          *
 809          * @param child_sa              child_sa to add
 810          */
 811         void (*add_child_sa) (ike_sa_t *this, child_sa_t *child_sa);
 812
 813         /**
 814          * Get a CHILD_SA identified by protocol and SPI.
 815          *
 816          * @param protocol              protocol of the SA
 817          * @param spi                   SPI of the CHILD_SA
 818          * @param inbound               TRUE if SPI is inbound, FALSE if outbound
 819          * @return                              child_sa, or NULL if none found
 820          */
 821         child_sa_t* (*get_child_sa) (ike_sa_t *this, protocol_id_t protocol,
 822                                                                  u_int32_t spi, bool inbound);
 823
 824         /**
 825          * Get the number of CHILD_SAs.
 826          *
 827          * @return                              number of CHILD_SAs
 828          */
 829         int (*get_child_count) (ike_sa_t *this);
 830
 831         /**
 832          * Create an enumerator over all CHILD_SAs.
 833          *
 834          * @return                              enumerator
 835          */
 836         enumerator_t* (*create_child_sa_enumerator) (ike_sa_t *this);
 837
 838         /**
 839          * Remove the CHILD_SA the given enumerator points to from this IKE_SA.
 840          *
 841          * @param enumerator    enumerator pointing to CHILD_SA
 842          */
 843         void (*remove_child_sa) (ike_sa_t *this, enumerator_t *enumerator);
 844
 845         /**
 846          * Rekey the CHILD SA with the specified reqid.
 847          *
 848          * Looks for a CHILD SA owned by this IKE_SA, and start the rekeing.
 849          *
 850          * @param protocol              protocol of the SA
 851          * @param spi                   inbound SPI of the CHILD_SA
 852          * @return
 853          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 854          *                                              - SUCCESS, if rekeying initiated
 855          */
 856         status_t (*rekey_child_sa) (ike_sa_t *this, protocol_id_t protocol, u_int32_t spi);
 857
 858         /**
 859          * Close the CHILD SA with the specified protocol/SPI.
 860          *
 861          * Looks for a CHILD SA owned by this IKE_SA, deletes it and
 862          * notify's the remote peer about the delete. The associated
 863          * states and policies in the kernel get deleted, if they exist.
 864          *
 865          * @param protocol              protocol of the SA
 866          * @param spi                   inbound SPI of the CHILD_SA
 867          * @param expired               TRUE if CHILD_SA is expired
 868          * @return
 869          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 870          *                                              - SUCCESS, if delete message sent
 871          */
 872         status_t (*delete_child_sa)(ike_sa_t *this, protocol_id_t protocol,
 873                                                                 u_int32_t spi, bool expired);
 874
 875         /**
 876          * Destroy a CHILD SA with the specified protocol/SPI.
 877          *
 878          * Looks for a CHILD SA owned by this IKE_SA and destroys it.
 879          *
 880          * @param protocol              protocol of the SA
 881          * @param spi                   inbound SPI of the CHILD_SA
 882          * @return
 883          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 884          *                                              - SUCCESS
 885          */
 886         status_t (*destroy_child_sa) (ike_sa_t *this, protocol_id_t protocol, u_int32_t spi);
 887
 888         /**
 889          * Rekey the IKE_SA.
 890          *
 891          * Sets up a new IKE_SA, moves all CHILDs to it and deletes this IKE_SA.
 892          *
 893          * @return                              - SUCCESS, if IKE_SA rekeying initiated
 894          */
 895         status_t (*rekey) (ike_sa_t *this);
 896
 897         /**
 898          * Reauthenticate the IKE_SA.
 899          *
 900          * Create a completely new IKE_SA with authentication, recreates all children
 901          * within the IKE_SA, closes this IKE_SA.
 902          *
 903          * @return                              DESTROY_ME to destroy the IKE_SA
 904          */
 905         status_t (*reauth) (ike_sa_t *this);
 906
 907         /**
 908          * Restablish the IKE_SA.
 909          *
 910          * Reestablish an IKE_SA after it has been closed.
 911          *
 912          * @return                              DESTROY_ME to destroy the IKE_SA
 913          */
 914         status_t (*reestablish) (ike_sa_t *this);
 915
 916         /**
 917          * Set the lifetime limit received/to send in a AUTH_LIFETIME notify.
 918          *
 919          * If the IKE_SA is already ESTABLISHED, an INFORMATIONAL is sent with
 920          * an AUTH_LIFETIME notify. The call never fails on unestablished SAs.
 921          *
 922          * @param lifetime              lifetime in seconds
 923          * @return                              DESTROY_ME to destroy the IKE_SA
 924          */
 925         status_t (*set_auth_lifetime)(ike_sa_t *this, u_int32_t lifetime);
 926
 927         /**
 928          * Set the virtual IP to use for this IKE_SA and its children.
 929          *
 930          * The virtual IP is assigned per IKE_SA, not per CHILD_SA. It has the same
 931          * lifetime as the IKE_SA.
 932          *
 933          * @param local                 TRUE to set local address, FALSE for remote
 934          * @param ip                    IP to set as virtual IP
 935          */
 936         void (*set_virtual_ip) (ike_sa_t *this, bool local, host_t *ip);
 937
 938         /**
 939          * Get the virtual IP configured.
 940          *
 941          * @param local                 TRUE to get local virtual IP, FALSE for remote
 942          * @return                              host_t *virtual IP
 943          */
 944         host_t* (*get_virtual_ip) (ike_sa_t *this, bool local);
 945
 946         /**
 947          * Register a configuration attribute to the IKE_SA.
 948          *
 949          * If an IRAS sends a configuration attribute it is installed and
 950          * registered at the IKE_SA. Attributes are inherit()ed and get released
 951          * when the IKE_SA is closed.
 952          *
 953          * @param handler               handler installed the attribute, use for release()
 954          * @param type                  configuration attribute type
 955          * @param data                  associated attribute data
 956          */
 957         void (*add_configuration_attribute)(ike_sa_t *this,
 958                                                         attribute_handler_t *handler,
 959                                                         configuration_attribute_type_t type, chunk_t data);
 960
 961         /**
 962          * Set local and remote host addresses to be used for IKE.
 963          *
 964          * These addresses are communicated via the KMADDRESS field of a MIGRATE
 965          * message sent via the NETLINK or PF _KEY kernel socket interface.
 966          *
 967          * @param local                 local kmaddress
 968          * @param remote                remote kmaddress
 969          */
 970         void (*set_kmaddress) (ike_sa_t *this, host_t *local, host_t *remote);
 971
 972         /**
 973          * Create enumerator over a task queue of this IKE_SA.
 974          *
 975          * @param                               queue type to enumerate
 976          * @return                              enumerator over task_t
 977          */
 978         enumerator_t* (*create_task_enumerator)(ike_sa_t *this, task_queue_t queue);
 979
 980         /**
 981          * Flush a task queue, cancelling all tasks in it.
 982          *
 983          * @param queue                 queue type to flush
 984          */
 985         void (*flush_queue)(ike_sa_t *this, task_queue_t queue);
 986
 987         /**
 988          * Queue a task for initiaton to the task manager.
 989          *
 990          * @param task                  task to queue
 991          */
 992         void (*queue_task)(ike_sa_t *this, task_t *task);
 993
 994         /**
 995          * Inherit all attributes of other to this after rekeying.
 996          *
 997          * When rekeying is completed, all CHILD_SAs, the virtual IP and all
 998          * outstanding tasks are moved from other to this.
 999          * As this call may initiate inherited tasks, a status is returned.
1000          *
1001          * @param other                 other task to inherit from
1002          */
1003         void (*inherit) (ike_sa_t *this, ike_sa_t *other);
1004
1005         /**
1006          * Reset the IKE_SA, useable when initiating fails
1007          */
1008         void (*reset) (ike_sa_t *this);
1009
1010         /**
1011          * Destroys a ike_sa_t object.
1012          */
1013         void (*destroy) (ike_sa_t *this);
1014 };
1015
1016 /**
1017  * Creates an ike_sa_t object with a specific ID and IKE version.
1018  *
1019  * @param ike_sa_id             ike_sa_id_t to associate with new IKE_SA/ISAKMP_SA
1020  * @param initiator             TRUE to create this IKE_SA as initiator
1021  * @param version               IKE version of this SA
1022  * @return                              ike_sa_t object
1023  */
1024 ike_sa_t *ike_sa_create(ike_sa_id_t *ike_sa_id, bool initiator,
1025                                                 ike_version_t version);
1026
1027 #endif /** IKE_SA_H_ @}*/