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