src/libcharon/sa/tasks/task.h

   1 /*
   2  * Copyright (C) 2007 Tobias Brunner
   3  * Copyright (C) 2006 Martin Willi
   4  * Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup task task
  19  * @{ @ingroup tasks
  20  */
  21
  22 #ifndef TASK_H_
  23 #define TASK_H_
  24
  25 typedef enum task_type_t task_type_t;
  26 typedef struct task_t task_t;
  27
  28 #include <library.h>
  29 #include <sa/ike_sa.h>
  30 #include <encoding/message.h>
  31
  32 /**
  33  * Different kinds of tasks.
  34  */
  35 enum task_type_t {
  36         /** establish an unauthenticated IKE_SA */
  37         TASK_IKE_INIT,
  38         /** detect NAT situation */
  39         TASK_IKE_NATD,
  40         /** handle MOBIKE stuff */
  41         TASK_IKE_MOBIKE,
  42         /** authenticate the initiated IKE_SA */
  43         TASK_IKE_AUTH,
  44         /** AUTH_LIFETIME negotiation, RFC4478 */
  45         TASK_IKE_AUTH_LIFETIME,
  46         /** certificate processing before authentication (certreqs, cert parsing) */
  47         TASK_IKE_CERT_PRE,
  48         /** certificate processing after authentication (certs payload generation) */
  49         TASK_IKE_CERT_POST,
  50         /** Configuration payloads, virtual IP and such */
  51         TASK_IKE_CONFIG,
  52         /** rekey an IKE_SA */
  53         TASK_IKE_REKEY,
  54         /** reestablish a complete IKE_SA */
  55         TASK_IKE_REAUTH,
  56         /** delete an IKE_SA */
  57         TASK_IKE_DELETE,
  58         /** liveness check */
  59         TASK_IKE_DPD,
  60         /** Vendor ID processing */
  61         TASK_IKE_VENDOR,
  62 #ifdef ME
  63         /** handle ME stuff */
  64         TASK_IKE_ME,
  65 #endif /* ME */
  66         /** establish a CHILD_SA within an IKE_SA */
  67         TASK_CHILD_CREATE,
  68         /** delete an established CHILD_SA */
  69         TASK_CHILD_DELETE,
  70         /** rekey an CHILD_SA */
  71         TASK_CHILD_REKEY,
  72         /** IKEv1 main mode */
  73         TASK_MAIN_MODE,
  74         /** IKEv1 informational exchange */
  75         TASK_INFORMATIONAL,
  76         /** IKEv1 delete using an informational */
  77         TASK_ISAKMP_DELETE,
  78         /** IKEv1 XAUTH authentication */
  79         TASK_XAUTH,
  80         /** IKEv1 Mode Config */
  81         TASK_MODE_CONFIG,
  82         /** IKEv1 quick mode */
  83         TASK_QUICK_MODE,
  84         /** IKEv1 delete of a quick mode SA */
  85         TASK_QUICK_DELETE,
  86         /** IKEv1 vendor ID payload handling */
  87         TASK_VENDOR_V1,
  88         /** IKEv1 NAT detection */
  89         TASK_IKE_NATD_V1,
  90         /** IKEv1 pre-authentication certificate handling */
  91         TASK_IKE_CERT_PRE_V1,
  92         /** IKEv1 post-authentication certificate handling */
  93         TASK_ISAKMP_CERT_POST,
  94 };
  95
  96 /**
  97  * enum names for task_type_t.
  98  */
  99 extern enum_name_t *task_type_names;
 100
 101 /**
 102  * Interface for a task, an operation handled within exchanges.
 103  *
 104  * A task is an elemantary operation. It may be handled by a single or by
 105  * multiple exchanges. An exchange may even complete multiple tasks.
 106  * A task has a build() and an process() operation. The build() operation
 107  * creates payloads and adds it to the message. The process() operation
 108  * inspects a message and handles its payloads. An initiator of an exchange
 109  * first calls build() to build the request, and processes the response message
 110  * with the process() method.
 111  * A responder does the opposite; it calls process() first to handle an incoming
 112  * request and secondly calls build() to build an appropriate response.
 113  * Both methods return either SUCCESS, NEED_MORE or FAILED. A SUCCESS indicates
 114  * that the task completed, even when the task completed unsuccessfully. The
 115  * manager then removes the task from the list. A NEED_MORE is returned when
 116  * the task needs further build()/process() calls to complete, the manager
 117  * leaves the taks in the queue. A returned FAILED indicates a critical failure.
 118  * The manager closes the IKE_SA whenever a task returns FAILED.
 119  */
 120 struct task_t {
 121
 122         /**
 123          * Build a request or response message for this task.
 124          *
 125          * @param message               message to add payloads to
 126          * @return
 127          *                                              - FAILED if a critical error occurred
 128          *                                              - DESTROY_ME if IKE_SA has been properly deleted
 129          *                                              - NEED_MORE if another call to build/process needed
 130          *                                              - ALREADY_DONE to cancel all active or passive tasks
 131          *                                              - SUCCESS if task completed
 132          */
 133         status_t (*build) (task_t *this, message_t *message);
 134
 135         /**
 136          * Process a request or response message for this task.
 137          *
 138          * @param message               message to read payloads from
 139          * @return
 140          *                                              - FAILED if a critical error occurred
 141          *                                              - DESTROY_ME if IKE_SA has been properly deleted
 142          *                                              - NEED_MORE if another call to build/process needed
 143          *                                              - ALREADY_DONE to cancel all active or passive tasks
 144          *                                              - SUCCESS if task completed
 145          */
 146         status_t (*process) (task_t *this, message_t *message);
 147
 148         /**
 149          * Get the type of the task implementation.
 150          */
 151         task_type_t (*get_type) (task_t *this);
 152
 153         /**
 154          * Migrate a task to a new IKE_SA.
 155          *
 156          * After migrating a task, it goes back to a state where it can be
 157          * used again to initate an exchange. This is useful when a task
 158          * has to get migrated to a new IKE_SA.
 159          * A special usage is when a INVALID_KE_PAYLOAD is received. A call
 160          * to reset resets the task, but uses another DH group for the next
 161          * try.
 162          * The ike_sa is the new IKE_SA this task belongs to and operates on.
 163          *
 164          * @param ike_sa                new IKE_SA this task works for
 165          */
 166         void (*migrate) (task_t *this, ike_sa_t *ike_sa);
 167
 168         /**
 169          * Destroys a task_t object.
 170          */
 171         void (*destroy) (task_t *this);
 172 };
 173
 174 #endif /** TASK_H_ @}*/