src/libcharon/sa/ike_sa.h

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