src/charon/sa/transactions/transaction.h

   1 /**
   2  * @file transaction.h
   3  *
   4  * @brief Interface transaction_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 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 TRANSACTION_H_
  24 #define TRANSACTION_H_
  25
  26
  27 typedef struct transaction_t transaction_t;
  28
  29 #include <types.h>
  30 #include <encoding/message.h>
  31 #include <sa/ike_sa.h>
  32
  33
  34
  35 /**
  36  * @brief This interface represents a transaction an established IKE_SA can do.
  37  *
  38  * To every transaction, a message ID is associated. IKEv2 uses strict message
  39  * IDs, which are equal for a request/response pair in a transaction.
  40  * An initiator of a transaction does the following:
  41  * - create the transaction using a specific constructor
  42  * - call request() to get the message for initiaton
  43  * - call conclude() to process received reply
  44  * The other peer does the following:
  45  * - create a transanction using the generic transaction constructor
  46  * - call respond() to get a reply to send
  47  *
  48  * The responder must not destroy the transaction, until the
  49  * initiator initiates another transaction (or a number of transactions
  50  * > window size). This allows us to redo a transaction in case of a
  51  * message loss. The initiator can destroy the the transaction once
  52  * the conclude() function is called.
  53  *
  54  * @b Constructors:
  55  *  - transaction_create()
  56  *  - ike_sa_init_create()
  57  *  - ike_auth_create()
  58  *
  59  * @ingroup transactions
  60  */
  61 struct transaction_t {
  62
  63         /**
  64          * @brief Get the request to use for initiating the transaction.
  65          *
  66          * A transaction creates a request only once. The request is stored
  67          * internally and may be queried multiple times for retransmission.
  68          * The transaction is not responsible for generating/encrypting the
  69          * message, this is the job of the caller. But it MAY be already
  70          * generated when calling get_request() the second time.
  71          *
  72          * @param this                  calling object
  73          * @param[out] request  resultin request
  74          * @return
  75          *                                              - FAILED if transaction failed
  76          *                                              - DESTROY_ME if transaction failed and IKE SA
  77          *                                                must be deleted
  78          *                                              - SUCCESS
  79          */
  80         status_t (*get_request) (transaction_t *this, message_t **request);
  81
  82         /**
  83          * @brief Build the response for a received request.
  84          *
  85          * A transaction creates a response only once for a unique request.
  86          * This allows the use of get_response multiple times for retransmission
  87          * purposes.
  88          * The transaction is not responsible for generating/encrypting the
  89          * response, nor is it responsible for decrypting/parsing the request.
  90          * This is the job of the caller. But the response MAY be already
  91          * generated when calling get_request() the second time.
  92          * The initiator waits for a response, so we send one in every case. This
  93          * means response points always to a valid message. This message
  94          * may not be modified or destroyed, it gets destroyed along with the
  95          * transaction.
  96          * The get_response() function may return a next transaction. This allows
  97          * passing of informations from one transaction to a next one.
  98          *
  99          * @param this                  calling object
 100          * @param request               received request
 101          * @param[out] response resulting response
 102          * @param[out] next             transaction expected as next, or NULL
 103          * @return
 104          *                                              - FAILED if transaction failed
 105          *                                              - DESTROY_ME if transaction failed and IKE SA
 106          *                                                must be deleted
 107          *                                              - SUCCESS
 108          */
 109         status_t (*get_response) (transaction_t *this, message_t *request,
 110                                                           message_t **response, transaction_t **next);
 111
 112         /**
 113          * @brief Conclude an initiated transaction with a received response.
 114          *
 115          * The response must be decrypted and parsed. The conclude function
 116          * may return a new transaction. This transaction has to be executed
 117          * next to complete a multi-exchange scenario. It allows a clean
 118          * transaction mechanism, as the transaction knows best whats to do
 119          * after it completes. It must only be executed if conclude returns
 120          * SUCCESS.
 121          *
 122          * @param this                          calling object
 123          * @param response                      received response
 124          * @param[out] next                     transaction to execute as next, or NULL
 125          * @return
 126          *                                              - FAILED if transaction failed
 127          *                                              - DESTROY_ME if transaction failed and IKE SA
 128          *                                                must be deleted
 129          *                                              - SUCCESS
 130          */
 131         status_t (*conclude) (transaction_t *this, message_t *response,
 132                                                   transaction_t **next);
 133
 134         /**
 135          * @brief Get the message ID associated with this transaction.
 136          *
 137          * Every transaction consists of a message pair with the same
 138          * message ID. This ID can be queried with get_message_id().
 139          *
 140          * @param this                  calling object
 141          * @return                              message id
 142          */
 143         u_int32_t (*get_message_id) (transaction_t *this);
 144
 145         /**
 146          * @brief Times we already sent the request (retransmitted).
 147          *
 148          * The transaction stores an internal counter to see how
 149          * many times we sent the request. This counter is incremented
 150          * each time after a call to requested().
 151          *
 152          * @param this                  calling object
 153          * @return                              message id
 154          */
 155         u_int32_t (*requested) (transaction_t *this);
 156
 157         /**
 158          * @brief Destroys a transaction_t object.
 159          *
 160          * @param this                  calling object
 161          */
 162         void (*destroy) (transaction_t *this);
 163 };
 164
 165 /**
 166  * @brief Create a transaction instance based on a received request.
 167  *
 168  * Incoming requests are handled by a transaction. But as we don't
 169  * know what kind of transaction we use for a specific request, we use
 170  * a generic constructor. This constructor decides which instance will
 171  * handle the transaction, and creates it.
 172  *
 173  * @param ike_sa                ike_sa associated with this transaction
 174  * @param request               received request
 175  * @return
 176  *                                              - created transaction, or
 177  *                                              - NULL no transaction needed
 178  *
 179  * @ingroup transactions
 180  */
 181 transaction_t *transaction_create(ike_sa_t *ike_sa, message_t* request);
 182
 183 #endif /* TRANSACTION_H_ */