src/charon/sa/child_sa.h

   1 /*
   2  * Copyright (C) 2006-2008 Tobias Brunner
   3  * Copyright (C) 2006-2007 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  * $Id$
  18  */
  19
  20 /**
  21  * @defgroup child_sa child_sa
  22  * @{ @ingroup sa
  23  */
  24
  25 #ifndef CHILD_SA_H_
  26 #define CHILD_SA_H_
  27
  28 typedef enum child_sa_state_t child_sa_state_t;
  29 typedef struct child_sa_t child_sa_t;
  30
  31 #include <library.h>
  32 #include <crypto/prf_plus.h>
  33 #include <encoding/payloads/proposal_substructure.h>
  34 #include <config/proposal.h>
  35 #include <config/child_cfg.h>
  36
  37 /**
  38  * States of a CHILD_SA
  39  */
  40 enum child_sa_state_t {
  41
  42         /**
  43          * Just created, uninstalled CHILD_SA
  44          */
  45         CHILD_CREATED,
  46
  47         /**
  48          * Installed SPD, but no SAD entries
  49          */
  50         CHILD_ROUTED,
  51
  52         /**
  53          * Installed an in-use CHILD_SA
  54          */
  55         CHILD_INSTALLED,
  56
  57         /**
  58          * While updating hosts, in update_hosts()
  59          */
  60         CHILD_UPDATING,
  61
  62         /**
  63          * CHILD_SA which is rekeying
  64          */
  65         CHILD_REKEYING,
  66
  67         /**
  68          * CHILD_SA in progress of delete
  69          */
  70         CHILD_DELETING,
  71
  72         /**
  73          * CHILD_SA object gets destroyed
  74          */
  75         CHILD_DESTROYING,
  76 };
  77
  78 /**
  79  * enum strings for child_sa_state_t.
  80  */
  81 extern enum_name_t *child_sa_state_names;
  82
  83 /**
  84  * Represents an IPsec SAs between two hosts.
  85  *
  86  * A child_sa_t contains two SAs. SAs for both
  87  * directions are managed in one child_sa_t object. Both
  88  * SAs and the policies have the same reqid.
  89  *
  90  * The procedure for child sa setup is as follows:
  91  * - A gets SPIs for a proposal via child_sa_t.alloc
  92  * - A send the updated proposal to B
  93  * - B selects a suitable proposal
  94  * - B calls child_sa_t.add to add and update the selected proposal
  95  * - B sends the updated proposal to A
  96  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  97  *
  98  * Once SAs are set up, policies can be added using add_policies.
  99  */
 100 struct child_sa_t {
 101
 102         /**
 103          * Get the name of the config this CHILD_SA uses.
 104          *
 105          * @return                      name
 106          */
 107         char* (*get_name) (child_sa_t *this);
 108
 109         /**
 110          * Get the reqid of the CHILD SA.
 111          *
 112          * Every CHILD_SA has a reqid. The kernel uses this ID to
 113          * identify it.
 114          *
 115          * @return                      reqid of the CHILD SA
 116          */
 117         u_int32_t (*get_reqid)(child_sa_t *this);
 118
 119         /**
 120          * Get the SPI of this CHILD_SA.
 121          *
 122          * Set the boolean parameter inbound to TRUE to
 123          * get the SPI for which we receive packets, use
 124          * FALSE to get those we use for sending packets.
 125          *
 126          * @param inbound       TRUE to get inbound SPI, FALSE for outbound.
 127          * @return                      SPI of the CHILD SA
 128          */
 129         u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
 130
 131         /**
 132          * Get the CPI of this CHILD_SA.
 133          *
 134          * Set the boolean parameter inbound to TRUE to
 135          * get the CPI for which we receive packets, use
 136          * FALSE to get those we use for sending packets.
 137          *
 138          * @param inbound       TRUE to get inbound CPI, FALSE for outbound.
 139          * @return                      CPI of the CHILD SA
 140          */
 141         u_int16_t (*get_cpi) (child_sa_t *this, bool inbound);
 142
 143         /**
 144          * Get the protocol which this CHILD_SA uses to protect traffic.
 145          *
 146          * @return                      AH | ESP
 147          */
 148         protocol_id_t (*get_protocol) (child_sa_t *this);
 149
 150         /**
 151          * Get the IPsec mode of this CHILD_SA.
 152          *
 153          * @return                      TUNNEL | TRANSPORT | BEET
 154          */
 155         ipsec_mode_t (*get_mode)(child_sa_t *this);
 156
 157         /**
 158          * Get the IPsec encryption key.
 159          *
 160          * @param inbound       TRUE for inbound, FALSE for outbound key
 161          * @param key           chunk where to write key pointer and length
 162          * @return                      encryption algorithm
 163          */
 164         encryption_algorithm_t (*get_encryption)(child_sa_t *this, bool inbound,
 165                                                                                          chunk_t *key);
 166         /**
 167          * Get the IPsec integrity.
 168          *
 169          * @param inbound       TRUE for inbound, FALSE for outbound key
 170          * @param key           chunk where to write key pointer and length
 171          * @return                      integrity algorithm
 172          */
 173         integrity_algorithm_t (*get_integrity)(child_sa_t *this, bool inbound,
 174                                                                                    chunk_t *key);
 175         /**
 176          * Get the lifetime of the CHILD_SA.
 177          *
 178          * @param hard          TRUE for hard lifetime, FALSE for soft (rekey) lifetime
 179          * @return                      lifetime in seconds
 180          */
 181         u_int32_t (*get_lifetime)(child_sa_t *this, bool hard);
 182
 183         /**
 184          * Get last use time of the CHILD_SA.
 185          *
 186          * @param inbound       TRUE for inbound traffic, FALSE for outbound
 187          * @return                      time of last use in seconds
 188          */
 189         u_int32_t (*get_usetime)(child_sa_t *this, bool inbound);
 190
 191         /**
 192          * Allocate SPIs for given proposals.
 193          *
 194          * Since the kernel manages SPIs for us, we need
 195          * to allocate them. If a proposal contains more
 196          * than one protocol, for each protocol an SPI is
 197          * allocated. SPIs are stored internally and written
 198          * back to the proposal.
 199          *
 200          * @param proposals     list of proposals for which SPIs are allocated
 201          */
 202         status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
 203
 204         /**
 205          * Install the kernel SAs for a proposal, without previous SPI allocation.
 206          *
 207          * @param proposal      proposal for which SPIs are allocated
 208          * @param mode          mode for the CHILD_SA
 209          * @param prf_plus      key material to use for key derivation
 210          * @return                      SUCCESS or FAILED
 211          */
 212         status_t (*add)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
 213                                         prf_plus_t *prf_plus);
 214
 215         /**
 216          * Install the kernel SAs for a proposal, after SPIs have been allocated.
 217          *
 218          * Updates an SA, for which SPIs are already allocated via alloc().
 219          *
 220          * @param proposal      proposal for which SPIs are allocated
 221          * @param mode          mode for the CHILD_SA
 222          * @param prf_plus      key material to use for key derivation
 223          * @return                      SUCCESS or FAILED
 224          */
 225         status_t (*update)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
 226                                            prf_plus_t *prf_plus);
 227
 228         /**
 229          * Update the hosts in the kernel SAs and policies.
 230          *
 231          * The CHILD must be INSTALLED to do this update.
 232          *
 233          * @param me            the new local host
 234          * @param other         the new remote host
 235          * @param vip           virtual IP, if any
 236          * @param                       TRUE to use UDP encapsulation for NAT traversal
 237          * @return                      SUCCESS or FAILED
 238          */
 239         status_t (*update_hosts)(child_sa_t *this, host_t *me, host_t *other,
 240                                                          host_t *vip, bool encap);
 241
 242         /**
 243          * Install the policies using some traffic selectors.
 244          *
 245          * Supplied lists of traffic_selector_t's specify the policies
 246          * to use for this child sa.
 247          *
 248          * @param my_ts         traffic selectors for local site
 249          * @param other_ts      traffic selectors for remote site
 250          * @param mode          mode for the SA: tunnel/transport
 251          * @param proto         protocol for policy, ESP/AH
 252          * @return                      SUCCESS or FAILED
 253          */
 254         status_t (*add_policies)(child_sa_t *this, linked_list_t *my_ts_list,
 255                                                          linked_list_t *other_ts_list, ipsec_mode_t mode,
 256                                                          protocol_id_t proto);
 257
 258         /**
 259          * Get the traffic selectors of added policies of local host.
 260          *
 261          * @param local         TRUE for own traffic selectors, FALSE for remote
 262          * @return                      list of traffic selectors
 263          */
 264         linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local);
 265
 266         /**
 267          * Create an enumerator over installed policies.
 268          *
 269          * @return                      enumerator over pairs of traffic selectors.
 270          */
 271         enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
 272
 273         /**
 274          * Get the state of the CHILD_SA.
 275          */
 276         child_sa_state_t (*get_state) (child_sa_t *this);
 277
 278         /**
 279          * Set the state of the CHILD_SA.
 280          *
 281          * @param state         state to set on CHILD_SA
 282          */
 283         void (*set_state) (child_sa_t *this, child_sa_state_t state);
 284
 285         /**
 286          * Get the config used to set up this child sa.
 287          *
 288          * @return                      child_cfg
 289          */
 290         child_cfg_t* (*get_config) (child_sa_t *this);
 291
 292         /**
 293          * Activate IPComp by setting the transform ID and CPI values.
 294          *
 295          * @param ipcomp        the IPComp transform to use
 296          * @param other_cpi     other Compression Parameter Index
 297          */
 298         void (*activate_ipcomp) (child_sa_t *this, ipcomp_transform_t ipcomp,
 299                                                          u_int16_t other_cpi);
 300
 301         /**
 302          * Returns the Compression Parameter Index (CPI) allocated from the kernel.
 303          *
 304          * @return                      allocated CPI
 305          */
 306         u_int16_t (*allocate_cpi) (child_sa_t *this);
 307
 308         /**
 309          * Destroys a child_sa.
 310          */
 311         void (*destroy) (child_sa_t *this);
 312 };
 313
 314 /**
 315  * Constructor to create a new child_sa_t.
 316  *
 317  * @param me                    own address
 318  * @param other                 remote address
 319  * @param my_id                 id of own peer
 320  * @param other_id              id of remote peer
 321  * @param config                config to use for this CHILD_SA
 322  * @param reqid                 reqid of old CHILD_SA when rekeying, 0 otherwise
 323  * @param encap                 TRUE to enable UDP encapsulation (NAT traversal)
 324  * @return                              child_sa_t object
 325  */
 326 child_sa_t * child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
 327                                                          u_int32_t reqid, bool encap);
 328
 329 #endif /*CHILD_SA_H_ @} */