src/charon/sa/child_sa.h

   1 /**
   2  * @file child_sa.h
   3  *
   4  * @brief Interface of child_sa_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 Tobias Brunner, Daniel Roethlisberger
  10  * Copyright (C) 2006 Martin Willi
  11  * Hochschule fuer Technik Rapperswil
  12  *
  13  * This program is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by the
  15  * Free Software Foundation; either version 2 of the License, or (at your
  16  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21  * for more details.
  22  */
  23
  24
  25 #ifndef CHILD_SA_H_
  26 #define CHILD_SA_H_
  27
  28 #include <types.h>
  29 #include <crypto/prf_plus.h>
  30 #include <encoding/payloads/proposal_substructure.h>
  31 #include <config/proposal.h>
  32 #include <utils/logger.h>
  33
  34 /**
  35  * Where we should start with reqid enumeration
  36  */
  37 #define REQID_START 2000000000
  38
  39 typedef enum child_sa_state_t child_sa_state_t;
  40
  41 /**
  42  * @brief States of a CHILD_SA
  43  */
  44 enum child_sa_state_t {
  45
  46         /**
  47          * Just created, uninstalled CHILD_SA
  48          */
  49         CHILD_CREATED,
  50
  51         /**
  52          * Installed SPD, but no SAD entries
  53          */
  54         CHILD_ROUTED,
  55
  56         /**
  57          * Installed an in-use CHILD_SA
  58          */
  59         CHILD_INSTALLED,
  60
  61         /**
  62          * CHILD_SA which is rekeying
  63          */
  64         CHILD_REKEYING,
  65
  66         /**
  67          * CHILD_SA in progress of delete
  68          */
  69         CHILD_DELETING,
  70 };
  71
  72 /**
  73  * String mappings for child_sa_state_t.
  74  */
  75 extern mapping_t child_sa_state_m[];
  76
  77 typedef struct child_sa_t child_sa_t;
  78
  79 /**
  80  * @brief Represents an IPsec SAs between two hosts.
  81  *
  82  * A child_sa_t contains two SAs. SAs for both
  83  * directions are managed in one child_sa_t object. Both
  84  * SAs and the policies have the same reqid.
  85  *
  86  * The procedure for child sa setup is as follows:
  87  * - A gets SPIs for a proposal via child_sa_t.alloc
  88  * - A send the updated proposal to B
  89  * - B selects a suitable proposal
  90  * - B calls child_sa_t.add to add and update the selected proposal
  91  * - B sends the updated proposal to A
  92  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  93  *
  94  * Once SAs are set up, policies can be added using add_policies.
  95  *
  96  *
  97  * @b Constructors:
  98  *  - child_sa_create()
  99  *
 100  * @ingroup sa
 101  */
 102 struct child_sa_t {
 103
 104         /**
 105          * @brief Get the name of the policy this CHILD_SA uses.
 106          *
 107          * @param this                  calling object
 108          * @return                              name
 109          */
 110         char* (*get_name) (child_sa_t *this);
 111
 112         /**
 113          * @brief Set the name of the policy this IKE_SA uses.
 114          *
 115          * @param this                  calling object
 116          * @param name                  name, gets cloned
 117          */
 118         void (*set_name) (child_sa_t *this, char* name);
 119
 120         /**
 121          * @brief Get the unique reqid of the CHILD SA.
 122          *
 123          * Every CHILD_SA has a unique reqid, which is also
 124          * stored down in the kernel.
 125          *
 126          * @param this          calling object
 127          * @return                      reqid of the CHILD SA
 128          */
 129         u_int32_t (*get_reqid)(child_sa_t *this);
 130
 131         /**
 132          * @brief Get the SPI of this CHILD_SA.
 133          *
 134          * Set the boolean parameter inbound to TRUE to
 135          * get the SPI for which we receive packets, use
 136          * FALSE to get those we use for sending packets.
 137          *
 138          * @param this          calling object
 139          * @param inbound       TRUE to get inbound SPI, FALSE for outbound.
 140          * @return                      spi of the CHILD SA
 141          */
 142         u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
 143
 144         /**
 145          * @brief Get the protocol which this CHILD_SA uses to protect traffic.
 146          *
 147          * @param this          calling object
 148          * @return                      AH | ESP
 149          */
 150         protocol_id_t (*get_protocol) (child_sa_t *this);
 151
 152         /**
 153          * @brief Allocate SPIs for given proposals.
 154          *
 155          * Since the kernel manages SPIs for us, we need
 156          * to allocate them. If a proposal contains more
 157          * than one protocol, for each protocol an SPI is
 158          * allocated. SPIs are stored internally and written
 159          * back to the proposal.
 160          *
 161          * @param this          calling object
 162          * @param proposals     list of proposals for which SPIs are allocated
 163          */
 164         status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
 165
 166         /**
 167          * @brief Install the kernel SAs for a proposal, without previous SPI allocation.
 168          *
 169          * @param this          calling object
 170          * @param proposal      proposal for which SPIs are allocated
 171          * @param prf_plus      key material to use for key derivation
 172          * @return                      SUCCESS or FAILED
 173          */
 174         status_t (*add)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
 175
 176         /**
 177          * @brief Install the kernel SAs for a proposal, after SPIs have been allocated.
 178          *
 179          * Updates an SA, for which SPIs are already allocated via alloc().
 180          *
 181          * @param this          calling object
 182          * @param proposal      proposal for which SPIs are allocated
 183          * @param prf_plus      key material to use for key derivation
 184          * @return                      SUCCESS or FAILED
 185          */
 186         status_t (*update)(child_sa_t *this, proposal_t *proposal, prf_plus_t *prf_plus);
 187
 188         /**
 189          * @brief Update the hosts in the kernel SAs and policies
 190          *
 191          * @warning only call this after update() has been called.
 192          *
 193          * @param this                  calling object
 194          * @param new_me                the new local host
 195          * @param new_other             the new remote host
 196          * @param my_diff               differences to apply for me
 197          * @param other_diff    differences to apply for other
 198          * @return                              SUCCESS or FAILED
 199          */
 200         status_t (*update_hosts) (child_sa_t *this, host_t *new_me, host_t *new_other,
 201         host_diff_t my_diff, host_diff_t other_diff);
 202
 203         /**
 204          * @brief Install the policies using some traffic selectors.
 205          *
 206          * Supplied lists of traffic_selector_t's specify the policies
 207          * to use for this child sa.
 208          *
 209          * @param this          calling object
 210          * @param my_ts         traffic selectors for local site
 211          * @param other_ts      traffic selectors for remote site
 212          * @return                      SUCCESS or FAILED
 213          */
 214         status_t (*add_policies) (child_sa_t *this, linked_list_t *my_ts_list, linked_list_t *other_ts_list);
 215
 216         /**
 217          * @brief Get the traffic selectors of added policies of local host.
 218          *
 219          * @param this          calling object
 220          * @return                      list of traffic selectors
 221          */
 222         linked_list_t* (*get_my_traffic_selectors) (child_sa_t *this);
 223
 224         /**
 225          * @brief Get the traffic selectors of added policies of remote host.
 226          *
 227          * @param this          calling object
 228          * @return                      list of traffic selectors
 229          */
 230         linked_list_t* (*get_other_traffic_selectors) (child_sa_t *this);
 231
 232         /**
 233          * @brief Get the time of this child_sa_t's last use (i.e. last use of any of its policies)
 234          *
 235          * @param this          calling object
 236          * @param inbound       query for in- or outbound usage
 237          * @param use_time      the time
 238          * @return                      SUCCESS or FAILED
 239          */
 240         status_t (*get_use_time) (child_sa_t *this, bool inbound, time_t *use_time);
 241
 242         /**
 243          * @brief Get the state of the CHILD_SA.
 244          *
 245          * @param this          calling object
 246          */
 247         child_sa_state_t (*get_state) (child_sa_t *this);
 248
 249         /**
 250          * @brief Set the state of the CHILD_SA.
 251          *
 252          * @param this          calling object
 253          */
 254         void (*set_state) (child_sa_t *this, child_sa_state_t state);
 255
 256         /**
 257          * @brief Set the transaction which rekeys this CHILD_SA.
 258          *
 259          * Since either end may initiate CHILD_SA rekeying, we must detect
 260          * such situations to handle them cleanly. A rekeying transaction
 261          * registers itself to the CHILD_SA, and checks later if another
 262          * transaction is in progress of a rekey.
 263          *
 264          * @todo Fix include problematics to allow inclusion of
 265          * the create_child_sa_t transaction.
 266          *
 267          * @param this          calling object
 268          */
 269         void (*set_rekeying_transaction) (child_sa_t *this, void *transaction);
 270
 271         /**
 272          * @brief Get the transaction which rekeys this CHILD_SA.
 273          *
 274          * @see set_rekeying_transactoin().
 275          *
 276          * @param this          calling object
 277          */
 278         void* (*get_rekeying_transaction) (child_sa_t *this);
 279
 280         /**
 281          * @brief Log the status of a child_sa to a logger.
 282          *
 283          * The status of ESP/AH SAs is logged with the supplied logger in
 284          * a human readable form.
 285          * Supplying NULL as logger uses the internal child_sa logger
 286          * to do the logging.
 287          *
 288          * @param this          calling object
 289          * @param logger        logger to use for logging
 290          */
 291         void (*log_status) (child_sa_t *this, logger_t *logger);
 292
 293         /**
 294          * @brief Destroys a child_sa.
 295          *
 296          * @param this          calling object
 297          */
 298         void (*destroy) (child_sa_t *this);
 299 };
 300
 301 /**
 302  * @brief Constructor to create a new child_sa_t.
 303  *
 304  * @param rekey_reqid   reqid of old CHILD_SA when rekeying, 0 otherwise
 305  * @param me                    own address
 306  * @param other                 remote address
 307  * @param soft_lifetime time before rekeying
 308  * @param hard_lifteime time before delete
 309  * @param use_natt              TRUE if NAT traversal is used
 310  * @return                              child_sa_t object
 311  *
 312  * @ingroup sa
 313  */
 314 child_sa_t * child_sa_create(u_int32_t rekey_reqid, host_t *me, host_t *other,
 315                                                          u_int32_t soft_lifetime, u_int32_t hard_lifetime,
 316                                                          bool use_natt);
 317
 318 #endif /*CHILD_SA_H_*/