src/charon/sa/task_manager.h

   1 /**
   2  * @file task_manager.h
   3  *
   4  * @brief Interface of task_manager_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 TASK_MANAGER_H_
  24 #define TASK_MANAGER_H_
  25
  26 typedef struct task_manager_t task_manager_t;
  27
  28 #include <library.h>
  29 #include <encoding/message.h>
  30 #include <sa/ike_sa.h>
  31 #include <sa/tasks/task.h>
  32
  33 /**
  34  * First retransmit timeout in milliseconds.
  35  *
  36  * @ingroup sa
  37  */
  38 #define RETRANSMIT_TIMEOUT 4000
  39
  40 /**
  41  * Base which is raised to the power of the retransmission try.
  42  *
  43  * @ingroup sa
  44  */
  45 #define RETRANSMIT_BASE 1.8
  46
  47 /**
  48  * Number of retransmits done before giving up.
  49  *
  50  * @ingroup sa
  51  */
  52 #define RETRANSMIT_TRIES 5
  53
  54
  55 /**
  56  * @brief The task manager, juggles task and handles message exchanges.
  57  *
  58  * On incoming requests, the task manager creates new tasks on demand and
  59  * juggles the request through all available tasks. Each task inspects the
  60  * request and adds payloads as necessary to the response.
  61  * On outgoing requests, the task manager delivers the request through the tasks
  62  * to build it, the response gets processed by each task to complete.
  63  * The task manager has an internal Queue to store task which should get
  64  * completed.
  65  * For the initial IKE_SA setup, several tasks are queued: One for the
  66  * unauthenticated IKE_SA setup, one for authentication, one for CHILD_SA setup
  67  * and maybe one for virtual IP assignement.
  68  * The task manager is also responsible for retransmission. It uses a backoff
  69  * algorithm. The timeout is calculated using
  70  * RETRANSMIT_TIMEOUT * (RETRANSMIT_BASE ** try).
  71  * When try reaches RETRANSMIT_TRIES, retransmission is given up.
  72  *
  73  * Using an initial TIMEOUT of 4s, a BASE of 1.8, and 5 TRIES gives us:
  74  * @verbatim
  75                    | relative | absolute
  76    ---------------------------------------------------------
  77    4s * (1.8 ** 0) =    4s         4s
  78    4s * (1.8 ** 1) =    7s        11s
  79    4s * (1.8 ** 2) =   13s        24s
  80    4s * (1.8 ** 3) =   23s        47s
  81    4s * (1.8 ** 4) =   42s        89s
  82    4s * (1.8 ** 5) =   76s       165s
  83
  84    @endberbatim
  85  * The peer is considered dead after 2min 45s when no reply comes in.
  86  *
  87  * @b Constructors:
  88  *  - task_manager_create()
  89  *
  90  * @ingroup sa
  91  */
  92 struct task_manager_t {
  93
  94         /**
  95          * @brief Process an incoming message.
  96          *
  97          * @param this                  calling object
  98          * @param message               message to add payloads to
  99          * @return
 100          *                                              - DESTROY_ME if IKE_SA must be closed
 101          *                                              - SUCCESS otherwise
 102          */
 103         status_t (*process_message) (task_manager_t *this, message_t *message);
 104
 105         /**
 106          * @brief Initiate an exchange with the currently queued tasks.
 107          *
 108          * @param this                  calling object
 109          */
 110         status_t (*initiate) (task_manager_t *this);
 111
 112         /**
 113          * @brief Queue a task in the manager.
 114          *
 115          * @param this                  calling object
 116          * @param task                  task to queue
 117          */
 118         void (*queue_task) (task_manager_t *this, task_t *task);
 119
 120         /**
 121          * @brief Retransmit a request if it hasn't been acknowledged yet.
 122          *
 123          * A return value of INVALID_STATE means that the message was already
 124          * acknowledged and has not to be retransmitted. A return value of SUCCESS
 125          * means retransmission was required and the message has been resent.
 126          *
 127          * @param this                  calling object
 128          * @param message_id    ID of the message to retransmit
 129          * @return
 130          *                                              - INVALID_STATE if retransmission not required
 131          *                                              - SUCCESS if retransmission sent
 132          */
 133         status_t (*retransmit) (task_manager_t *this, u_int32_t message_id);
 134
 135         /**
 136          * @brief Migrate all tasks from other to this.
 137          *
 138          * To rekey or reestablish an IKE_SA completely, all queued or active
 139          * tasks should get migrated to the new IKE_SA.
 140          *
 141          * @param this                  manager which gets all tasks
 142          * @param other                 manager which gives away its tasks
 143          */
 144         void (*adopt_tasks) (task_manager_t *this, task_manager_t *other);
 145
 146         /**
 147          * @brief Reset message ID counters of the task manager.
 148          *
 149          * The IKEv2 protocol requires to restart exchanges with message IDs
 150          * reset to zero (INVALID_KE_PAYLOAD, COOKIES, ...). The reset() method
 151          * resets the message IDs and resets all active tasks using the migrate()
 152          * method.
 153          *
 154          * @param this                  calling object
 155          * @param other                 manager which gives away its tasks
 156          */
 157         void (*reset) (task_manager_t *this);
 158
 159         /**
 160          * @brief Check if we are currently waiting for a reply.
 161          *
 162          * @param this                  calling object
 163          * @return                              TRUE if we are waiting, FALSE otherwise
 164          */
 165         bool (*busy) (task_manager_t *this);
 166
 167         /**
 168          * @brief Destroy the task_manager_t.
 169          *
 170          * @param this                  calling object
 171          */
 172         void (*destroy) (task_manager_t *this);
 173 };
 174
 175 /**
 176  * @brief Create an instance of the task manager.
 177  *
 178  * @param ike_sa                IKE_SA to manage.
 179  *
 180  * @ingroup sa
 181  */
 182 task_manager_t *task_manager_create(ike_sa_t *ike_sa);
 183
 184 #endif /* TASK_MANAGER_H_ */