src/charon/sa/task_manager.h

   1 /*
   2  * Copyright (C) 2006 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup task_manager task_manager
  18  * @{ @ingroup sa
  19  */
  20
  21 #ifndef TASK_MANAGER_H_
  22 #define TASK_MANAGER_H_
  23
  24 typedef struct task_manager_t task_manager_t;
  25
  26 #include <limits.h>
  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 #define RETRANSMIT_TIMEOUT 4000
  37
  38 /**
  39  * Base which is raised to the power of the retransmission try.
  40  */
  41 #define RETRANSMIT_BASE 1.8
  42
  43 /**
  44  * Number of retransmits done before giving up.
  45  */
  46 #define RETRANSMIT_TRIES 5
  47
  48 /**
  49  * Interval for mobike routability checks in ms.
  50  */
  51 #define ROUTEABILITY_CHECK_INTERVAL 2500
  52
  53 /**
  54  * Number of routability checks before giving up
  55  */
  56 #define ROUTEABILITY_CHECK_TRIES 10
  57
  58
  59 /**
  60  * The task manager, juggles task and handles message exchanges.
  61  *
  62  * On incoming requests, the task manager creates new tasks on demand and
  63  * juggles the request through all available tasks. Each task inspects the
  64  * request and adds payloads as necessary to the response.
  65  * On outgoing requests, the task manager delivers the request through the tasks
  66  * to build it, the response gets processed by each task to complete.
  67  * The task manager has an internal Queue to store task which should get
  68  * completed.
  69  * For the initial IKE_SA setup, several tasks are queued: One for the
  70  * unauthenticated IKE_SA setup, one for authentication, one for CHILD_SA setup
  71  * and maybe one for virtual IP assignement.
  72  * The task manager is also responsible for retransmission. It uses a backoff
  73  * algorithm. The timeout is calculated using
  74  * RETRANSMIT_TIMEOUT * (RETRANSMIT_BASE ** try).
  75  * When try reaches RETRANSMIT_TRIES, retransmission is given up.
  76  *
  77  * Using an initial TIMEOUT of 4s, a BASE of 1.8, and 5 TRIES gives us:
  78  * @verbatim
  79                    | relative | absolute
  80    ---------------------------------------------------------
  81    4s * (1.8 ** 0) =    4s         4s
  82    4s * (1.8 ** 1) =    7s        11s
  83    4s * (1.8 ** 2) =   13s        24s
  84    4s * (1.8 ** 3) =   23s        47s
  85    4s * (1.8 ** 4) =   42s        89s
  86    4s * (1.8 ** 5) =   76s       165s
  87
  88    @endverbatim
  89  * The peer is considered dead after 2min 45s when no reply comes in.
  90  */
  91 struct task_manager_t {
  92
  93         /**
  94          * Process an incoming message.
  95          *
  96          * @param message               message to add payloads to
  97          * @return
  98          *                                              - DESTROY_ME if IKE_SA must be closed
  99          *                                              - SUCCESS otherwise
 100          */
 101         status_t (*process_message) (task_manager_t *this, message_t *message);
 102
 103         /**
 104          * Initiate an exchange with the currently queued tasks.
 105          */
 106         status_t (*initiate) (task_manager_t *this);
 107
 108         /**
 109          * Queue a task in the manager.
 110          *
 111          * @param task                  task to queue
 112          */
 113         void (*queue_task) (task_manager_t *this, task_t *task);
 114
 115         /**
 116          * Retransmit a request if it hasn't been acknowledged yet.
 117          *
 118          * A return value of INVALID_STATE means that the message was already
 119          * acknowledged and has not to be retransmitted. A return value of SUCCESS
 120          * means retransmission was required and the message has been resent.
 121          *
 122          * @param message_id    ID of the message to retransmit
 123          * @return
 124          *                                              - INVALID_STATE if retransmission not required
 125          *                                              - SUCCESS if retransmission sent
 126          */
 127         status_t (*retransmit) (task_manager_t *this, u_int32_t message_id);
 128
 129         /**
 130          * Migrate all tasks from other to this.
 131          *
 132          * To rekey or reestablish an IKE_SA completely, all queued or active
 133          * tasks should get migrated to the new IKE_SA.
 134          *
 135          * @param other                 manager which gives away its tasks
 136          */
 137         void (*adopt_tasks) (task_manager_t *this, task_manager_t *other);
 138
 139         /**
 140          * Reset message ID counters of the task manager.
 141          *
 142          * The IKEv2 protocol requires to restart exchanges with message IDs
 143          * reset to zero (INVALID_KE_PAYLOAD, COOKIES, ...). The reset() method
 144          * resets the message IDs and resets all active tasks using the migrate()
 145          * method.
 146          * Use a value of UINT_MAX to keep the current message ID.
 147          *
 148          * @param initiate              message ID to initiate exchanges (send)
 149          * @param respond               message ID to respond to exchanges (expect)
 150          */
 151         void (*reset) (task_manager_t *this, u_int32_t initiate, u_int32_t respond);
 152
 153         /**
 154          * Check if we are currently waiting for a reply.
 155          *
 156          * @return                              TRUE if we are waiting, FALSE otherwise
 157          */
 158         bool (*busy) (task_manager_t *this);
 159
 160         /**
 161          * Destroy the task_manager_t.
 162          */
 163         void (*destroy) (task_manager_t *this);
 164 };
 165
 166 /**
 167  * Create an instance of the task manager.
 168  *
 169  * @param ike_sa                IKE_SA to manage.
 170  */
 171 task_manager_t *task_manager_create(ike_sa_t *ike_sa);
 172
 173 #endif /** TASK_MANAGER_H_ @}*/