src/charon/sa/ike_sa.h

   1 /**
   2  * @file ike_sa.h
   3  *
   4  * @brief Interface of ike_sa_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 Tobias Brunner, Daniel Roethlisberger
  10  * Copyright (C) 2005-2006 Martin Willi
  11  * Copyright (C) 2005 Jan Hutter
  12  * Hochschule fuer Technik Rapperswil
  13  *
  14  * This program is free software; you can redistribute it and/or modify it
  15  * under the terms of the GNU General Public License as published by the
  16  * Free Software Foundation; either version 2 of the License, or (at your
  17  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  18  *
  19  * This program is distributed in the hope that it will be useful, but
  20  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  21  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22  * for more details.
  23  */
  24
  25 #ifndef IKE_SA_H_
  26 #define IKE_SA_H_
  27
  28 typedef enum ike_sa_state_t ike_sa_state_t;
  29 typedef struct ike_sa_t ike_sa_t;
  30
  31 #include <library.h>
  32 #include <encoding/message.h>
  33 #include <encoding/payloads/proposal_substructure.h>
  34 #include <sa/ike_sa_id.h>
  35 #include <sa/child_sa.h>
  36 #include <sa/tasks/task.h>
  37 #include <utils/randomizer.h>
  38 #include <crypto/prfs/prf.h>
  39 #include <crypto/crypters/crypter.h>
  40 #include <crypto/signers/signer.h>
  41 #include <crypto/ca.h>
  42 #include <config/peer_cfg.h>
  43 #include <config/ike_cfg.h>
  44
  45 /**
  46  * Timeout in milliseconds after that a half open IKE_SA gets deleted.
  47  *
  48  * @ingroup sa
  49  */
  50 #define HALF_OPEN_IKE_SA_TIMEOUT 30000
  51
  52 /**
  53  * Interval to send keepalives when NATed, in seconds.
  54  *
  55  * @ingroup sa
  56  */
  57 #define KEEPALIVE_INTERVAL 20
  58
  59 /**
  60  * After which time rekeying should be retried if it failed, in seconds.
  61  *
  62  * @ingroup sa
  63  */
  64 #define RETRY_INTERVAL 30
  65
  66 /**
  67  * Jitter to subtract from RETRY_INTERVAL to randomize rekey retry.
  68  *
  69  * @ingroup sa
  70  */
  71 #define RETRY_JITTER 20
  72
  73
  74 /**
  75  * @brief State of an IKE_SA.
  76  *
  77  * An IKE_SA passes various states in its lifetime. A newly created
  78  * SA is in the state CREATED.
  79  * @verbatim
  80                  +----------------+
  81                  ¦   SA_CREATED   ¦
  82                  +----------------+
  83                          ¦
  84     on initiate()--->    ¦   <----- on IKE_SA_INIT received
  85                          V
  86                  +----------------+
  87                  ¦ SA_CONNECTING  ¦
  88                  +----------------+
  89                          ¦
  90                          ¦   <----- on IKE_AUTH successfully completed
  91                          V
  92                  +----------------+
  93                  ¦ SA_ESTABLISHED ¦-------------------------+ <-- on rekeying
  94                  +----------------+                         ¦
  95                          ¦                                  V
  96     on delete()--->      ¦   <----- on IKE_SA        +-------------+
  97                          ¦          delete request   ¦ SA_REKEYING ¦
  98                          ¦          received         +-------------+
  99                          V                                  ¦
 100                  +----------------+                         ¦
 101                  ¦  SA_DELETING   ¦<------------------------+ <-- after rekeying
 102                  +----------------+
 103                          ¦
 104                          ¦   <----- after delete() acknowledged
 105                          ¦
 106                         \V/
 107                          X
 108                         / \
 109    @endverbatim
 110  *
 111  * @ingroup sa
 112  */
 113 enum ike_sa_state_t {
 114
 115         /**
 116          * IKE_SA just got created, but is not initiating nor responding yet.
 117          */
 118         IKE_CREATED,
 119
 120         /**
 121          * IKE_SA gets initiated actively or passively
 122          */
 123         IKE_CONNECTING,
 124
 125         /**
 126          * IKE_SA is fully established
 127          */
 128         IKE_ESTABLISHED,
 129
 130         /**
 131          * IKE_SA rekeying in progress
 132          */
 133         IKE_REKEYING,
 134
 135         /**
 136          * IKE_SA is in progress of deletion
 137          */
 138         IKE_DELETING,
 139 };
 140
 141 /**
 142  * enum names for ike_sa_state_t.
 143  */
 144 extern enum_name_t *ike_sa_state_names;
 145
 146 /**
 147  * @brief Class ike_sa_t representing an IKE_SA.
 148  *
 149  * An IKE_SA contains crypto information related to a connection
 150  * with a peer. It contains multiple IPsec CHILD_SA, for which
 151  * it is responsible. All traffic is handled by an IKE_SA, using
 152  * the task manager and its tasks.
 153  *
 154  * @b Constructors:
 155  * - ike_sa_create()
 156  *
 157  * @ingroup sa
 158  */
 159 struct ike_sa_t {
 160
 161         /**
 162          * @brief Get the id of the SA.
 163          *
 164          * Returned ike_sa_id_t object is not getting cloned!
 165          *
 166          * @param this                  calling object
 167          * @return                              ike_sa's ike_sa_id_t
 168          */
 169         ike_sa_id_t* (*get_id) (ike_sa_t *this);
 170
 171         /**
 172          * @brief Get the numerical ID uniquely defining this IKE_SA.
 173          *
 174          * @param this                  calling object
 175          * @return                              unique ID
 176          */
 177         u_int32_t (*get_unique_id) (ike_sa_t *this);
 178
 179         /**
 180          * @brief Get the state of the IKE_SA.
 181          *
 182          * @param this                  calling object
 183          * @return                              state of the IKE_SA
 184          */
 185         ike_sa_state_t (*get_state) (ike_sa_t *this);
 186
 187         /**
 188          * @brief Get some statistics about this IKE_SA.
 189          *
 190          * @param next_rekeying                 when the next rekeying is scheduled
 191          */
 192         void (*get_stats)(ike_sa_t *this, u_int32_t *next_rekeying);
 193
 194         /**
 195          * @brief Set the state of the IKE_SA.
 196          *
 197          * @param this                  calling object
 198          * @param state                 state to set for the IKE_SA
 199          */
 200         void (*set_state) (ike_sa_t *this, ike_sa_state_t ike_sa);
 201
 202         /**
 203          * @brief Get the name of the connection this IKE_SA uses.
 204          *
 205          * @param this                  calling object
 206          * @return                              name
 207          */
 208         char* (*get_name) (ike_sa_t *this);
 209
 210         /**
 211          * @brief Get the own host address.
 212          *
 213          * @param this                  calling object
 214          * @return                              host address
 215          */
 216         host_t* (*get_my_host) (ike_sa_t *this);
 217
 218         /**
 219          * @brief Set the own host address.
 220          *
 221          * @param this                  calling object
 222          * @param me                    host address
 223          */
 224         void (*set_my_host) (ike_sa_t *this, host_t *me);
 225
 226         /**
 227          * @brief Get the other peers host address.
 228          *
 229          * @param this                  calling object
 230          * @return                              host address
 231          */
 232         host_t* (*get_other_host) (ike_sa_t *this);
 233
 234         /**
 235          * @brief Set the others host address.
 236          *
 237          * @param this                  calling object
 238          * @param other                 host address
 239          */
 240         void (*set_other_host) (ike_sa_t *this, host_t *other);
 241
 242         /**
 243          * @brief Get the own identification.
 244          *
 245          * @param this                  calling object
 246          * @return                              identification
 247          */
 248         identification_t* (*get_my_id) (ike_sa_t *this);
 249
 250         /**
 251          * @brief Set the own identification.
 252          *
 253          * @param this                  calling object
 254          * @param me                    identification
 255          */
 256         void (*set_my_id) (ike_sa_t *this, identification_t *me);
 257
 258         /**
 259          * @brief Get the other peer's identification.
 260          *
 261          * @param this                  calling object
 262          * @return                              identification
 263          */
 264         identification_t* (*get_other_id) (ike_sa_t *this);
 265
 266         /**
 267          * @brief Set the other peer's identification.
 268          *
 269          * @param this                  calling object
 270          * @param other                 identification
 271          */
 272         void (*set_other_id) (ike_sa_t *this, identification_t *other);
 273
 274         /**
 275          * @brief Get the other peer's certification authority
 276          *
 277          * @param this                  calling object
 278          * @return                      ca_info_t record of other ca
 279          */
 280         ca_info_t* (*get_other_ca) (ike_sa_t *this);
 281
 282         /**
 283          * @brief Set the other peer's certification authority
 284          *
 285          * @param this                  calling object
 286          * @param other_ca              ca_info_t record of other ca
 287          */
 288         void (*set_other_ca) (ike_sa_t *this, ca_info_t *other_ca);
 289
 290         /**
 291          * @brief Get the config used to setup this IKE_SA.
 292          *
 293          * @param this                  calling object
 294          * @return                              ike_config
 295          */
 296         ike_cfg_t* (*get_ike_cfg) (ike_sa_t *this);
 297
 298         /**
 299          * @brief Set the config to setup this IKE_SA.
 300          *
 301          * @param this                  calling object
 302          * @param config                ike_config to use
 303          */
 304         void (*set_ike_cfg) (ike_sa_t *this, ike_cfg_t* config);
 305
 306         /**
 307          * @brief Get the peer config used by this IKE_SA.
 308          *
 309          * @param this                  calling object
 310          * @return                              peer_config
 311          */
 312         peer_cfg_t* (*get_peer_cfg) (ike_sa_t *this);
 313
 314         /**
 315          * @brief Set the peer config to use with this IKE_SA.
 316          *
 317          * @param this                  calling object
 318          * @param config                peer_config to use
 319          */
 320         void (*set_peer_cfg) (ike_sa_t *this, peer_cfg_t *config);
 321
 322         /**
 323          * @brief Initiate a new connection.
 324          *
 325          * The configs are owned by the IKE_SA after the call.
 326          *
 327          * @param this                  calling object
 328          * @param child_cfg             child config to create CHILD from
 329          * @return
 330          *                                              - SUCCESS if initialization started
 331          *                                              - DESTROY_ME if initialization failed
 332          */
 333         status_t (*initiate) (ike_sa_t *this, child_cfg_t *child_cfg);
 334
 335         /**
 336          * @brief Route a policy in the kernel.
 337          *
 338          * Installs the policies in the kernel. If traffic matches,
 339          * the kernel requests connection setup from the IKE_SA via acquire().
 340          *
 341          * @param this                  calling object
 342          * @param child_cfg             child config to route
 343          * @return
 344          *                                              - SUCCESS if routed successfully
 345          *                                              - FAILED if routing failed
 346          */
 347         status_t (*route) (ike_sa_t *this, child_cfg_t *child_cfg);
 348
 349         /**
 350          * @brief Unroute a policy in the kernel previously routed.
 351          *
 352          * @param this                  calling object
 353          * @param reqid                 reqid of CHILD_SA to unroute
 354          * @return
 355          *                                              - SUCCESS if route removed
 356          *                                              - NOT_FOUND if CHILD_SA not found
 357          *                                              - DESTROY_ME if last CHILD_SA was unrouted
 358          */
 359         status_t (*unroute) (ike_sa_t *this, u_int32_t reqid);
 360
 361         /**
 362          * @brief Acquire connection setup for an installed kernel policy.
 363          *
 364          * If an installed policy raises an acquire, the kernel calls
 365          * this function to establish the CHILD_SA (and maybe the IKE_SA).
 366          *
 367          * @param this                  calling object
 368          * @param reqid                 reqid of the CHILD_SA the policy belongs to.
 369          * @return
 370          *                                              - SUCCESS if initialization started
 371          *                                              - DESTROY_ME if initialization failed
 372          */
 373         status_t (*acquire) (ike_sa_t *this, u_int32_t reqid);
 374
 375         /**
 376          * @brief Initiates the deletion of an IKE_SA.
 377          *
 378          * Sends a delete message to the remote peer and waits for
 379          * its response. If the response comes in, or a timeout occurs,
 380          * the IKE SA gets deleted.
 381          *
 382          * @param this                  calling object
 383          * @return
 384          *                                              - SUCCESS if deletion is initialized
 385          *                                              - INVALID_STATE, if the IKE_SA is not in
 386          *                                                an established state and can not be
 387          *                                                delete (but destroyed).
 388          */
 389         status_t (*delete) (ike_sa_t *this);
 390
 391         /**
 392          * @brief Processes a incoming IKEv2-Message.
 393          *
 394          * Message processing may fail. If a critical failure occurs,
 395          * process_message() return DESTROY_ME. Then the caller must
 396          * destroy the IKE_SA immediatly, as it is unusable.
 397          *
 398          * @param this                  calling object
 399          * @param message       message to process
 400          * @return
 401          *                                              - SUCCESS
 402          *                                              - FAILED
 403          *                                              - DESTROY_ME if this IKE_SA MUST be deleted
 404          */
 405         status_t (*process_message) (ike_sa_t *this, message_t *message);
 406
 407         /**
 408          * @brief Generate a IKE message to send it to the peer.
 409          *
 410          * This method generates all payloads in the message and encrypts/signs
 411          * the packet.
 412          *
 413          * @param this                  calling object
 414          * @param message               message to generate
 415          * @param packet                generated output packet
 416          * @return
 417          *                                              - SUCCESS
 418          *                                              - FAILED
 419          *                                              - DESTROY_ME if this IKE_SA MUST be deleted
 420          */
 421         status_t (*generate_message) (ike_sa_t *this, message_t *message,
 422                                                                   packet_t **packet);
 423
 424         /**
 425          * @brief Retransmits a request.
 426          *
 427          * @param this                  calling object
 428          * @param message_id    ID of the request to retransmit
 429          * @return
 430          *                                              - SUCCESS
 431          *                                              - NOT_FOUND if request doesn't have to be retransmited
 432          */
 433         status_t (*retransmit) (ike_sa_t *this, u_int32_t message_id);
 434
 435         /**
 436          * @brief Sends a DPD request to the peer.
 437          *
 438          * To check if a peer is still alive, periodic
 439          * empty INFORMATIONAL messages are sent if no
 440          * other traffic was received.
 441          *
 442          * @param this                  calling object
 443          * @return
 444          *                                              - SUCCESS
 445          *                                              - DESTROY_ME, if peer did not respond
 446          */
 447         status_t (*send_dpd) (ike_sa_t *this);
 448
 449         /**
 450          * @brief Sends a keep alive packet.
 451          *
 452          * To refresh NAT tables in a NAT router
 453          * between the peers, periodic empty
 454          * UDP packets are sent if no other traffic
 455          * was sent.
 456          *
 457          * @param this                  calling object
 458          */
 459         void (*send_keepalive) (ike_sa_t *this);
 460
 461         /**
 462          * @brief Check if NAT traversal is enabled for this IKE_SA.
 463          *
 464          * @param this                  calling object
 465          * @return                              TRUE if NAT traversal enabled
 466          */
 467         bool (*is_natt_enabled) (ike_sa_t *this);
 468
 469         /**
 470          * @brief Enable NAT detection for this IKE_SA.
 471          *
 472          * If a Network address translation is detected with
 473          * NAT_DETECTION notifys, a SA must switch to ports
 474          * 4500. To enable this behavior, call enable_natt().
 475          * It is relevant which peer is NATted, this is specified
 476          * with the "local" parameter. Call it twice when both
 477          * are NATted.
 478          *
 479          * @param this                  calling object
 480          * @param local                 TRUE, if we are NATted, FALSE if other
 481          */
 482         void (*enable_natt) (ike_sa_t *this, bool local);
 483
 484         /**
 485          * @brief Derive all keys and create the transforms for IKE communication.
 486          *
 487          * Keys are derived using the diffie hellman secret, nonces and internal
 488          * stored SPIs.
 489          * Key derivation differs when an IKE_SA is set up to replace an
 490          * existing IKE_SA (rekeying). The SK_d key from the old IKE_SA
 491          * is included in the derivation process.
 492          *
 493          * @param this                  calling object
 494          * @param proposal              proposal which contains algorithms to use
 495          * @param secret                secret derived from DH exchange, gets freed
 496          * @param nonce_i               initiators nonce
 497          * @param nonce_r               responders nonce
 498          * @param initiator             TRUE if initiator, FALSE otherwise
 499          * @param child_prf             PRF with SK_d key when rekeying, NULL otherwise
 500          * @param old_prf               general purpose PRF of old SA when rekeying
 501          */
 502         status_t (*derive_keys)(ike_sa_t *this, proposal_t* proposal, chunk_t secret,
 503                                                         chunk_t nonce_i, chunk_t nonce_r,
 504                                                         bool initiator, prf_t *child_prf, prf_t *old_prf);
 505
 506         /**
 507          * @brief Get a multi purpose prf for the negotiated PRF function.
 508          *
 509          * @param this                  calling object
 510          * @return                              pointer to prf_t object
 511          */
 512         prf_t *(*get_prf) (ike_sa_t *this);
 513
 514         /**
 515          * @brief Get the prf-object, which is used to derive keys for child SAs.
 516          *
 517          * @param this                  calling object
 518          * @return                              pointer to prf_t object
 519          */
 520         prf_t *(*get_child_prf) (ike_sa_t *this);
 521
 522         /**
 523          * @brief Get the key to build outgoing authentication data.
 524          *
 525          * @param this                  calling object
 526          * @return                              pointer to prf_t object
 527          */
 528         chunk_t (*get_skp_build) (ike_sa_t *this);
 529
 530         /**
 531          * @brief Get the key to verify incoming authentication data.
 532          *
 533          * @param this                  calling object
 534          * @return                              pointer to prf_t object
 535          */
 536         chunk_t (*get_skp_verify) (ike_sa_t *this);
 537
 538         /**
 539          * @brief Associates a child SA to this IKE SA
 540          *
 541          * @param this                  calling object
 542          * @param child_sa              child_sa to add
 543          */
 544         void (*add_child_sa) (ike_sa_t *this, child_sa_t *child_sa);
 545
 546         /**
 547          * @brief Get a CHILD_SA identified by protocol and SPI.
 548          *
 549          * @param this                  calling object
 550          * @param protocol              protocol of the SA
 551          * @param spi                   SPI of the CHILD_SA
 552          * @param inbound               TRUE if SPI is inbound, FALSE if outbound
 553          * @return                              child_sa, or NULL if none found
 554          */
 555         child_sa_t* (*get_child_sa) (ike_sa_t *this, protocol_id_t protocol,
 556                                                                  u_int32_t spi, bool inbound);
 557
 558         /**
 559          * @brief Create an iterator over all CHILD_SAs.
 560          *
 561          * @param this                  calling object
 562          * @return                              iterator
 563          */
 564         iterator_t* (*create_child_sa_iterator) (ike_sa_t *this);
 565
 566         /**
 567          * @brief Rekey the CHILD SA with the specified reqid.
 568          *
 569          * Looks for a CHILD SA owned by this IKE_SA, and start the rekeing.
 570          *
 571          * @param this                  calling object
 572          * @param protocol              protocol of the SA
 573          * @param spi                   inbound SPI of the CHILD_SA
 574          * @return
 575          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 576          *                                              - SUCCESS, if rekeying initiated
 577          */
 578         status_t (*rekey_child_sa) (ike_sa_t *this, protocol_id_t protocol, u_int32_t spi);
 579
 580         /**
 581          * @brief Close the CHILD SA with the specified protocol/SPI.
 582          *
 583          * Looks for a CHILD SA owned by this IKE_SA, deletes it and
 584          * notify's the remote peer about the delete. The associated
 585          * states and policies in the kernel get deleted, if they exist.
 586          *
 587          * @param this                  calling object
 588          * @param protocol              protocol of the SA
 589          * @param spi                   inbound SPI of the CHILD_SA
 590          * @return
 591          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 592          *                                              - SUCCESS, if delete message sent
 593          */
 594         status_t (*delete_child_sa) (ike_sa_t *this, protocol_id_t protocol, u_int32_t spi);
 595
 596         /**
 597          * @brief Destroy a CHILD SA with the specified protocol/SPI.
 598          *
 599          * Looks for a CHILD SA owned by this IKE_SA and destroys it.
 600          *
 601          * @param this                  calling object
 602          * @param protocol              protocol of the SA
 603          * @param spi                   inbound SPI of the CHILD_SA
 604          * @return
 605          *                                              - NOT_FOUND, if IKE_SA has no such CHILD_SA
 606          *                                              - SUCCESS
 607          */
 608         status_t (*destroy_child_sa) (ike_sa_t *this, protocol_id_t protocol, u_int32_t spi);
 609
 610         /**
 611          * @brief Rekey the IKE_SA.
 612          *
 613          * Sets up a new IKE_SA, moves all CHILDs to it and deletes this IKE_SA.
 614          *
 615          * @param this                  calling object
 616          * @return                              - SUCCESS, if IKE_SA rekeying initiated
 617          */
 618         status_t (*rekey) (ike_sa_t *this);
 619
 620         /**
 621          * @brief Restablish the IKE_SA.
 622          *
 623          * Create a completely new IKE_SA with authentication, recreates all children
 624          * within the IKE_SA, but lets the old IKE_SA untouched.
 625          *
 626          * @param this                  calling object
 627          */
 628         void (*reestablish) (ike_sa_t *this);
 629
 630         /**
 631          * @brief Set the virtual IP to use for this IKE_SA and its children.
 632          *
 633          * The virtual IP is assigned per IKE_SA, not per CHILD_SA. It has the same
 634          * lifetime as the IKE_SA.
 635          *
 636          * @param this                  calling object
 637          */
 638         void (*set_virtual_ip) (ike_sa_t *this, bool local, host_t *ip);
 639
 640         /**
 641          * @brief Get the virtual IP configured.
 642          *
 643          * @param this                  calling object
 644          * @param local                 TRUE to get local virtual IP, FALSE for remote
 645          */
 646         host_t* (*get_virtual_ip) (ike_sa_t *this, bool local);
 647
 648         /**
 649          * @brief Add a DNS server to the system.
 650          *
 651          * An IRAS may send a DNS server. To use it, it is installed on the
 652          * system. The DNS entry has a lifetime until the IKE_SA gets closed.
 653          *
 654          * @param this                  calling object
 655          * @param dns                   DNS server to install on the system
 656          */
 657         void (*add_dns_server) (ike_sa_t *this, host_t *dns);
 658
 659         /**
 660          * @brief Inherit all attributes of other to this after rekeying.
 661          *
 662          * When rekeying is completed, all CHILD_SAs, the virtual IP and all
 663          * outstanding tasks are moved from other to this.
 664          * As this call may initiate inherited tasks, a status is returned.
 665          *
 666          * @param this                  calling object
 667          * @param other                 other task to inherit from
 668          * @return                              DESTROY_ME if initiation of inherited task failed
 669          */
 670         status_t (*inherit) (ike_sa_t *this, ike_sa_t *other);
 671
 672         /**
 673          * @brief Reset the IKE_SA, useable when initiating fails
 674          *
 675          * @param this                  calling object
 676          */
 677         void (*reset) (ike_sa_t *this);
 678
 679         /**
 680          * @brief Destroys a ike_sa_t object.
 681          *
 682          * @param this                  calling object
 683          */
 684         void (*destroy) (ike_sa_t *this);
 685 };
 686
 687 /**
 688  * @brief Creates an ike_sa_t object with a specific ID.
 689  *
 690  * @param ike_sa_id     ike_sa_id_t object to associate with new IKE_SA
 691  * @return                              ike_sa_t object
 692  *
 693  * @ingroup sa
 694  */
 695 ike_sa_t *ike_sa_create(ike_sa_id_t *ike_sa_id);
 696
 697 #endif /* IKE_SA_H_ */