Source/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) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef IKE_SA_H_
  24 #define IKE_SA_H_
  25
  26 #include <types.h>
  27 #include <encoding/message.h>
  28 #include <encoding/payloads/proposal_substructure.h>
  29 #include <sa/ike_sa_id.h>
  30 #include <config/configuration_manager.h>
  31 #include <utils/logger.h>
  32 #include <utils/randomizer.h>
  33 #include <sa/states/state.h>
  34 #include <transforms/prfs/prf.h>
  35 #include <transforms/crypters/crypter.h>
  36 #include <transforms/signers/signer.h>
  37
  38 /**
  39  * Nonce size in bytes for nonces sending to other peer.
  40  *
  41  * @warning Nonce size MUST be between 16 and 256 bytes.
  42  *
  43  * @ingroup sa
  44  */
  45 #define NONCE_SIZE 16
  46
  47
  48 typedef struct ike_sa_t ike_sa_t;
  49
  50 /**
  51  * @brief Class ike_sa_t representing an IKE_SA.
  52  *
  53  * An object of this type is managed by an ike_sa_manager_t object
  54  * and represents an IKE_SA. Message processing is split up in different states.
  55  * They will handle all related things for the state they represent.
  56  *
  57  * @b Constructors:
  58  * - ike_sa_create()
  59  *
  60  * @ingroup sa
  61  */
  62 struct ike_sa_t {
  63
  64         /**
  65          * @brief Processes a incoming IKEv2-Message of type message_t.
  66          *
  67          * @param this ike_sa_t object object
  68          * @param[in] message message_t object to process
  69          * @return
  70          *                                              - SUCCESS
  71          *                                              - FAILED
  72          *                                              - DELETE_ME if this IKE_SA MUST be deleted
  73          */
  74         status_t (*process_message) (ike_sa_t *this,message_t *message);
  75
  76         /**
  77          * @brief Initiate a new connection with given configuration name.
  78          *
  79          * @param this                  calling object
  80          * @param name                  name of the configuration
  81          * @return
  82          *                                              - SUCCESS if initialization started
  83          *                                              - FAILED if in wrong state
  84          *                                              - DELETE_ME if initialization failed and IKE_SA MUST be deleted
  85          */
  86         status_t (*initialize_connection) (ike_sa_t *this, char *name);
  87
  88         /**
  89          * @brief Retransmits a request.
  90          *
  91          * @param this                  calling object
  92          * @param message_id    ID of the request to retransmit
  93          * @return
  94          *                                              - SUCCESS
  95          *                                              - NOT_FOUND if request doesn't have to be retransmited
  96          */
  97         status_t (*retransmit_request) (ike_sa_t *this, u_int32_t message_id);
  98
  99         /**
 100          * @brief Sends a request to delete IKE_SA.
 101          *
 102          * Only supported in state IKE_SA_ESTABLISHED
 103          *
 104          * @param this                  calling object
 105          */
 106         void (*send_delete_ike_sa_request) (ike_sa_t *this);
 107
 108         /**
 109          * @brief Get the id of the SA.
 110          *
 111          * Returned ike_sa_id_t object is not getting cloned!
 112          *
 113          * @param this                  calling object
 114          * @return                              ike_sa's ike_sa_id_t
 115          */
 116         ike_sa_id_t* (*get_id) (ike_sa_t *this);
 117
 118         /**
 119          * @brief Get the state of type of associated state object.
 120          *
 121          * @param this                  calling object
 122          * @return                              state of IKE_SA
 123          */
 124         ike_sa_state_t (*get_state) (ike_sa_t *this);
 125
 126         /**
 127          * @brief Destroys a ike_sa_t object.
 128          *
 129          * @param this                  calling object
 130          */
 131         void (*destroy) (ike_sa_t *this);
 132 };
 133
 134
 135 typedef struct protected_ike_sa_t protected_ike_sa_t;
 136
 137 /**
 138  * @brief Protected functions of an ike_sa_t object.
 139  *
 140  * This members are only accessed out from
 141  * the various state_t implementations.
 142  *
 143  * @ingroup sa
 144  */
 145 struct protected_ike_sa_t {
 146
 147         /**
 148          * Public interface of an ike_sa_t object.
 149          */
 150         ike_sa_t public;
 151
 152         /**
 153          * @brief Build an empty IKEv2-Message and fills in default informations.
 154          *
 155          * Depending on the type of message (request or response), the message id is
 156          * either message_id_out or message_id_in.
 157          *
 158          * Used in state_t Implementation to build an empty IKEv2-Message.
 159          *
 160          * @param this                          calling object
 161          * @param type                          exchange type of new message
 162          * @param request                       TRUE, if message has to be a request
 163          * @param message                       new message is stored at this location
 164          */
 165         void (*build_message) (protected_ike_sa_t *this, exchange_type_t type, bool request, message_t **message);
 166
 167         /**
 168          * @brief Get the internal stored logger_t object for given ike_sa_t object.
 169          *
 170          * @warning Returned logger_t object is original one and managed by this object.
 171          *
 172          * @param this                          calling object
 173          * @return                                      pointer to the internal stored logger_t object
 174          */
 175         logger_t *(*get_logger) (protected_ike_sa_t *this);
 176
 177         /**
 178          * @brief Get the internal stored init_config_t object.
 179          *
 180          * @param this                          calling object
 181          * @return                                      pointer to the internal stored init_config_t object
 182          */
 183         init_config_t *(*get_init_config) (protected_ike_sa_t *this);
 184
 185         /**
 186          * @brief Set the internal init_config_t object.
 187          *
 188          * @param this                          calling object
 189          * @param init_config           object of type init_config_t
 190          */
 191         void (*set_init_config) (protected_ike_sa_t *this,init_config_t *init_config);
 192
 193         /**
 194          * @brief Get the internal stored sa_config_t object.
 195          *
 196          * @param this                          calling object
 197          * @return                                      pointer to the internal stored sa_config_t object
 198          */
 199         sa_config_t *(*get_sa_config) (protected_ike_sa_t *this);
 200
 201         /**
 202          * @brief Set the internal sa_config_t object.
 203          *
 204          * @param this                          calling object
 205          * @param sa_config                     object of type sa_config_t
 206          */
 207         void (*set_sa_config) (protected_ike_sa_t *this,sa_config_t *sa_config);
 208
 209         /**
 210          * @brief Get the internal stored host_t object for my host.
 211          *
 212          * @param this                          calling object
 213          * @return                                      pointer to the internal stored host_t object
 214          */
 215         host_t *(*get_my_host) (protected_ike_sa_t *this);
 216
 217         /**
 218          * @brief Get the internal stored host_t object for other host.
 219          *
 220          * @param this                          calling object
 221          * @return                                      pointer to the internal stored host_t object
 222          */
 223         host_t *(*get_other_host) (protected_ike_sa_t *this);
 224
 225         /**
 226          * @brief Set the internal stored host_t object for my host.
 227          *
 228          * Allready existing object gets destroyed. object gets not cloned!
 229          *
 230          * @param this                          calling object
 231          * @param my_host                       pointer to the new host_t object
 232          */
 233         void (*set_my_host) (protected_ike_sa_t *this,host_t * my_host);
 234
 235         /**
 236          * @brief Set the internal stored host_t object for other host.
 237          *
 238          * Allready existing object gets destroyed. object gets not cloned!
 239          *
 240          * @param this                          calling object
 241          * @param other_host                    pointer to the new host_t object
 242          */
 243         void (*set_other_host) (protected_ike_sa_t *this,host_t *other_host);
 244
 245         /**
 246          * @brief Derive all keys and create the transforms for IKE communication.
 247          *
 248          * Keys are derived using the diffie hellman secret, nonces and internal
 249          * stored SPIs.
 250          * Allready existing objects get destroyed.
 251          *
 252          * @param this                          calling object
 253          * @param proposal                      proposal which contains algorithms to use
 254          * @param dh                            diffie hellman object with shared secret
 255          * @param nonce_i                       initiators nonce
 256          * @param nonce_r                       responders nonce
 257          */
 258         status_t (*build_transforms) (protected_ike_sa_t *this, proposal_t* proposal,
 259                                                                  diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
 260
 261         /**
 262          * @brief Send the next request message.
 263          *
 264          * Also the first retransmit job is created.
 265          *
 266          * Last stored requested message gets destroyed. Object gets not cloned!
 267          *
 268          * @param this                          calling object
 269          * @param message                       pointer to the message which should be sent
 270          * @return
 271          *                                                      - SUCCESS
 272          *                                                      - FAILED if message id is not next expected one
 273          */
 274         status_t (*send_request) (protected_ike_sa_t *this,message_t * message);
 275
 276         /**
 277          * @brief Send the next response message.
 278          *
 279          * Last stored responded message gets destroyed. Object gets not cloned!
 280          *
 281          * @param this                          calling object
 282          * @param message                       pointer to the message which should be sent
 283          * return
 284          *                                                      - SUCCESS
 285          *                                                      - FAILED if message id is not next expected one
 286          */
 287         status_t (*send_response) (protected_ike_sa_t *this,message_t * message);
 288
 289         /**
 290          * @brief Send a notify reply message.
 291          *
 292          * @param this                          calling object
 293          * @param exchange_type         type of exchange in which the notify should be wrapped
 294          * @param type                          type of the notify message to send
 295          * @param data                          notification data
 296          */
 297         void (*send_notify) (protected_ike_sa_t *this, exchange_type_t exchange_type, notify_message_type_t type, chunk_t data);
 298
 299         /**
 300          * @brief Get the internal stored randomizer_t object.
 301          *
 302          * @param this                          calling object
 303          * @return                                      pointer to the internal randomizer_t object
 304          */
 305         randomizer_t *(*get_randomizer) (protected_ike_sa_t *this);
 306
 307         /**
 308          * @brief Set the new state_t object of the IKE_SA object.
 309          *
 310          * The old state_t object gets not destroyed. It's the callers duty to
 311          * make sure old state is destroyed (Normally the old state is the caller).
 312          *
 313          * @param this                          calling object
 314          * @param state                         pointer to the new state_t object
 315          */
 316         void (*set_new_state) (protected_ike_sa_t *this,state_t *state);
 317
 318         /**
 319          * @brief Set the last replied message id.
 320          *
 321          * @param this                          calling object
 322          * @param message_id            message id
 323          */
 324         void (*set_last_replied_message_id) (protected_ike_sa_t *this,u_int32_t message_id);
 325
 326         /**
 327          * @brief Get the internal stored initiator crypter_t object.
 328          *
 329          * @param this                          calling object
 330          * @return                                      pointer to crypter_t object
 331          */
 332         crypter_t *(*get_crypter_initiator) (protected_ike_sa_t *this);
 333
 334         /**
 335          * @brief Get the internal stored initiator signer_t object.
 336          *
 337          * @param this                          calling object
 338          * @return                                      pointer to signer_t object
 339          */
 340         signer_t *(*get_signer_initiator) (protected_ike_sa_t *this);
 341
 342         /**
 343          * @brief Get the internal stored responder crypter_t object.
 344          *
 345          * @param this                          calling object
 346          * @return                                      pointer to crypter_t object
 347          */
 348         crypter_t *(*get_crypter_responder) (protected_ike_sa_t *this);
 349
 350         /**
 351          * @brief Get the internal stored responder signer object.
 352          *
 353          * @param this                          calling object
 354          * @return                                      pointer to signer_t object
 355          */
 356         signer_t *(*get_signer_responder) (protected_ike_sa_t *this);
 357
 358         /**
 359          * @brief Get the multi purpose prf.
 360          *
 361          * @param this                          calling object
 362          * @return                                      pointer to prf_t object
 363          */
 364         prf_t *(*get_prf) (protected_ike_sa_t *this);
 365
 366         /**
 367          * @brief Get the prf-object, which is used to derive keys for child SAs.
 368          *
 369          * @param this                          calling object
 370          * @return                                      pointer to prf_t object
 371          */
 372         prf_t *(*get_child_prf) (protected_ike_sa_t *this);
 373
 374         /**
 375          * @brief Get the prf used for authentication of initiator.
 376          *
 377          * @param this                          calling object
 378          * @return                                      pointer to prf_t object
 379          */
 380         prf_t *(*get_prf_auth_i) (protected_ike_sa_t *this);
 381
 382         /**
 383          * @brief Get the prf used for authentication of responder.
 384          *
 385          * @param this                          calling object
 386          * @return                                      pointer to prf_t object
 387          */
 388         prf_t *(*get_prf_auth_r) (protected_ike_sa_t *this);
 389
 390         /**
 391          * @brief Get the last responded message.
 392          *
 393          * @param this                          calling object
 394          * @return
 395          *                                                      - last received as message_t object
 396          *                                                      - NULL if no last request available
 397          */
 398         message_t *(*get_last_responded_message) (protected_ike_sa_t *this);
 399
 400         /**
 401          * @brief Get the last requested message.
 402          *
 403          * @param this                          calling object
 404          * @return
 405          *                                                      - last sent as message_t object
 406          *                                                      - NULL if no last request available
 407          */
 408         message_t *(*get_last_requested_message) (protected_ike_sa_t *this);
 409
 410         /**
 411          * @brief Resets message counters and does destroy stored received and sent messages.
 412          *
 413          * @param this                          calling object
 414          */
 415         void (*reset_message_buffers) (protected_ike_sa_t *this);
 416
 417         /**
 418          * @brief Creates a job of type DELETE_ESTABLISHED_IKE_SA for the current IKE_SA.
 419          *
 420          * @param this                          calling object
 421          * @param timeout                       timeout after the IKE_SA gets deleted
 422          *
 423          */
 424         void (*create_delete_established_ike_sa_job) (protected_ike_sa_t *this,u_int32_t timeout);
 425 };
 426
 427
 428 /**
 429  * @brief Creates an ike_sa_t object with a specific ID.
 430  *
 431  * @warning the Content of internal ike_sa_id_t object can change over time
 432  *                      e.g. when a IKE_SA_INIT has been finished.
 433  *
 434  * @param[in] ike_sa_id         ike_sa_id_t object to associate with new IKE_SA.
 435  *                                                      The object is internal getting cloned
 436  *                                                      and so has to be destroyed by the caller.
 437  * @return                                      ike_sa_t object
 438  *
 439  * @ingroup sa
 440  */
 441 ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id);
 442
 443 #endif /*IKE_SA_H_*/