src/charon/sa/child_sa.h

   1 /*
   2  * Copyright (C) 2006-2008 Tobias Brunner
   3  * Copyright (C) 2006-2008 Martin Willi
   4  * Copyright (C) 2006 Daniel Roethlisberger
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup child_sa child_sa
  20  * @{ @ingroup sa
  21  */
  22
  23 #ifndef CHILD_SA_H_
  24 #define CHILD_SA_H_
  25
  26 typedef enum child_sa_state_t child_sa_state_t;
  27 typedef struct child_sa_t child_sa_t;
  28
  29 #include <library.h>
  30 #include <crypto/prf_plus.h>
  31 #include <encoding/payloads/proposal_substructure.h>
  32 #include <config/proposal.h>
  33 #include <config/child_cfg.h>
  34
  35 /**
  36  * States of a CHILD_SA
  37  */
  38 enum child_sa_state_t {
  39
  40         /**
  41          * Just created, uninstalled CHILD_SA
  42          */
  43         CHILD_CREATED,
  44
  45         /**
  46          * Installed SPD, but no SAD entries
  47          */
  48         CHILD_ROUTED,
  49
  50         /**
  51          * Installing an in-use CHILD_SA
  52          */
  53         CHILD_INSTALLING,
  54
  55         /**
  56          * Installed an in-use CHILD_SA
  57          */
  58         CHILD_INSTALLED,
  59
  60         /**
  61          * While updating hosts, in update_hosts()
  62          */
  63         CHILD_UPDATING,
  64
  65         /**
  66          * CHILD_SA which is rekeying
  67          */
  68         CHILD_REKEYING,
  69
  70         /**
  71          * CHILD_SA in progress of delete
  72          */
  73         CHILD_DELETING,
  74
  75         /**
  76          * CHILD_SA object gets destroyed
  77          */
  78         CHILD_DESTROYING,
  79 };
  80
  81 /**
  82  * enum strings for child_sa_state_t.
  83  */
  84 extern enum_name_t *child_sa_state_names;
  85
  86 /**
  87  * Represents an IPsec SAs between two hosts.
  88  *
  89  * A child_sa_t contains two SAs. SAs for both
  90  * directions are managed in one child_sa_t object. Both
  91  * SAs and the policies have the same reqid.
  92  *
  93  * The procedure for child sa setup is as follows:
  94  * - A gets SPIs for a all protocols in its proposals via child_sa_t.alloc
  95  * - A send the proposals with the allocated SPIs to B
  96  * - B selects a suitable proposal
  97  * - B allocates an SPI for the selected protocol
  98  * - B calls child_sa_t.install for both, the allocated and received SPI
  99  * - B sends the proposal with the allocated SPI to A
 100  * - A calls child_sa_t.install for both, the allocated and recevied SPI
 101  *
 102  * Once SAs are set up, policies can be added using add_policies.
 103  */
 104 struct child_sa_t {
 105
 106         /**
 107          * Get the name of the config this CHILD_SA uses.
 108          *
 109          * @return                      name
 110          */
 111         char* (*get_name) (child_sa_t *this);
 112
 113         /**
 114          * Get the reqid of the CHILD SA.
 115          *
 116          * Every CHILD_SA has a reqid. The kernel uses this ID to
 117          * identify it.
 118          *
 119          * @return                      reqid of the CHILD SA
 120          */
 121         u_int32_t (*get_reqid)(child_sa_t *this);
 122
 123         /**
 124          * Get the config used to set up this child sa.
 125          *
 126          * @return                      child_cfg
 127          */
 128         child_cfg_t* (*get_config) (child_sa_t *this);
 129
 130         /**
 131          * Get the state of the CHILD_SA.
 132          *
 133          * @return                      CHILD_SA state
 134          */
 135         child_sa_state_t (*get_state) (child_sa_t *this);
 136
 137         /**
 138          * Set the state of the CHILD_SA.
 139          *
 140          * @param state         state to set on CHILD_SA
 141          */
 142         void (*set_state) (child_sa_t *this, child_sa_state_t state);
 143
 144         /**
 145          * Get the SPI of this CHILD_SA.
 146          *
 147          * Set the boolean parameter inbound to TRUE to
 148          * get the SPI for which we receive packets, use
 149          * FALSE to get those we use for sending packets.
 150          *
 151          * @param inbound       TRUE to get inbound SPI, FALSE for outbound.
 152          * @return                      SPI of the CHILD SA
 153          */
 154         u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
 155
 156         /**
 157          * Get the CPI of this CHILD_SA.
 158          *
 159          * Set the boolean parameter inbound to TRUE to
 160          * get the CPI for which we receive packets, use
 161          * FALSE to get those we use for sending packets.
 162          *
 163          * @param inbound       TRUE to get inbound CPI, FALSE for outbound.
 164          * @return                      CPI of the CHILD SA
 165          */
 166         u_int16_t (*get_cpi) (child_sa_t *this, bool inbound);
 167
 168         /**
 169          * Get the protocol which this CHILD_SA uses to protect traffic.
 170          *
 171          * @return                      AH | ESP
 172          */
 173         protocol_id_t (*get_protocol) (child_sa_t *this);
 174
 175         /**
 176          * Set the negotiated protocol to use for this CHILD_SA.
 177          *
 178          * @param protocol      AH | ESP
 179          */
 180         void (*set_protocol)(child_sa_t *this, protocol_id_t protocol);
 181
 182         /**
 183          * Get the IPsec mode of this CHILD_SA.
 184          *
 185          * @return                      TUNNEL | TRANSPORT | BEET
 186          */
 187         ipsec_mode_t (*get_mode)(child_sa_t *this);
 188
 189         /**
 190          * Set the negotiated IPsec mode to use.
 191          *
 192          * @param mode          TUNNEL | TRANPORT | BEET
 193          */
 194         void (*set_mode)(child_sa_t *this, ipsec_mode_t mode);
 195
 196         /**
 197          * Get the used IPComp algorithm.
 198          *
 199          * @return                      IPComp compression algorithm.
 200          */
 201         ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);
 202
 203         /**
 204          * Set the IPComp algorithm to use.
 205          *
 206          * @param ipcomp        the IPComp transform to use
 207          */
 208         void (*set_ipcomp)(child_sa_t *this, ipcomp_transform_t ipcomp);
 209
 210         /**
 211          * Get the selected proposal.
 212          *
 213          * @return                      selected proposal
 214          */
 215         proposal_t* (*get_proposal)(child_sa_t *this);
 216
 217         /**
 218          * Set the negotiated proposal.
 219          *
 220          * @param proposal      selected proposal
 221          */
 222         void (*set_proposal)(child_sa_t *this, proposal_t *proposal);
 223
 224         /**
 225          * Check if this CHILD_SA uses UDP encapsulation.
 226          *
 227          * @return                      TRUE if SA encapsulates ESP packets
 228          */
 229         bool (*has_encap)(child_sa_t *this);
 230
 231         /**
 232          * Get the lifetime of the CHILD_SA.
 233          *
 234          * @param hard          TRUE for hard lifetime, FALSE for soft (rekey) lifetime
 235          * @return                      lifetime in seconds
 236          */
 237         u_int32_t (*get_lifetime)(child_sa_t *this, bool hard);
 238
 239         /**
 240          * Get last use time of the CHILD_SA.
 241          *
 242          * @param inbound       TRUE for inbound traffic, FALSE for outbound
 243          * @return                      time of last use in seconds
 244          */
 245         u_int32_t (*get_usetime)(child_sa_t *this, bool inbound);
 246
 247         /**
 248          * Get the traffic selectors list added for one side.
 249          *
 250          * @param local         TRUE for own traffic selectors, FALSE for remote
 251          * @return                      list of traffic selectors
 252          */
 253         linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local);
 254
 255         /**
 256          * Create an enumerator over installed policies.
 257          *
 258          * @return                      enumerator over pairs of traffic selectors.
 259          */
 260         enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
 261
 262         /**
 263          * Allocate an SPI to include in a proposal.
 264          *
 265          * @param protocol      protocol to allocate SPI for (ESP|AH)
 266          * @param spi           SPI output pointer
 267          * @return                      SPI, 0 on failure
 268          */
 269         u_int32_t (*alloc_spi)(child_sa_t *this, protocol_id_t protocol);
 270
 271         /**
 272          * Allocate a CPI to use for IPComp.
 273          *
 274          * @return                      CPI, 0 on failure
 275          */
 276         u_int16_t (*alloc_cpi)(child_sa_t *this);
 277
 278         /**
 279          * Install an IPsec SA for one direction.
 280          *
 281          * @param encr          encryption key, if any
 282          * @param integ         integrity key
 283          * @param spi           SPI to use, allocated for inbound
 284          * @param cpi           CPI to use, allocated for outbound
 285          * @param inbound       TRUE to install an inbound SA, FALSE for outbound
 286          * @return                      SUCCESS or FAILED
 287          */
 288         status_t (*install)(child_sa_t *this, chunk_t encr, chunk_t integ,
 289                                                 u_int32_t spi, u_int16_t cpi, bool inbound);
 290         /**
 291          * Install the policies using some traffic selectors.
 292          *
 293          * Supplied lists of traffic_selector_t's specify the policies
 294          * to use for this child sa.
 295          *
 296          * @param my_ts         traffic selectors for local site
 297          * @param other_ts      traffic selectors for remote site
 298          * @return                      SUCCESS or FAILED
 299          */
 300         status_t (*add_policies)(child_sa_t *this, linked_list_t *my_ts_list,
 301                                                          linked_list_t *other_ts_list);
 302         /**
 303          * Update hosts and ecapulation mode in the kernel SAs and policies.
 304          *
 305          * @param me            the new local host
 306          * @param other         the new remote host
 307          * @param vip           virtual IP, if any
 308          * @param                       TRUE to use UDP encapsulation for NAT traversal
 309          * @return                      SUCCESS or FAILED
 310          */
 311         status_t (*update)(child_sa_t *this, host_t *me, host_t *other,
 312                                            host_t *vip, bool encap);
 313         /**
 314          * Destroys a child_sa.
 315          */
 316         void (*destroy) (child_sa_t *this);
 317 };
 318
 319 /**
 320  * Constructor to create a new child_sa_t.
 321  *
 322  * @param me                            own address
 323  * @param other                         remote address
 324  * @param config                        config to use for this CHILD_SA
 325  * @param reqid                         reqid of old CHILD_SA when rekeying, 0 otherwise
 326  * @param encap                         TRUE to enable UDP encapsulation (NAT traversal)
 327  * @return                                      child_sa_t object
 328  */
 329 child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
 330                                                          u_int32_t reqid, bool encap);
 331
 332 #endif /** CHILD_SA_H_ @}*/