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          * CHILD_SA which is rekeying
  59          */
  60         CHILD_REKEYING,
  61
  62         /**
  63          * CHILD_SA in progress of delete
  64          */
  65         CHILD_DELETING,
  66
  67         /**
  68          * CHILD_SA object gets destroyed
  69          */
  70         CHILD_DESTROYING,
  71 };
  72
  73 /**
  74  * enum strings for child_sa_state_t.
  75  */
  76 extern enum_name_t *child_sa_state_names;
  77
  78 /**
  79  * Represents an IPsec SAs between two hosts.
  80  *
  81  * A child_sa_t contains two SAs. SAs for both
  82  * directions are managed in one child_sa_t object. Both
  83  * SAs and the policies have the same reqid.
  84  *
  85  * The procedure for child sa setup is as follows:
  86  * - A gets SPIs for a proposal via child_sa_t.alloc
  87  * - A send the updated proposal to B
  88  * - B selects a suitable proposal
  89  * - B calls child_sa_t.add to add and update the selected proposal
  90  * - B sends the updated proposal to A
  91  * - A calls child_sa_t.update to update the already allocated SPIs with the chosen proposal
  92  *
  93  * Once SAs are set up, policies can be added using add_policies.
  94  */
  95 struct child_sa_t {
  96
  97         /**
  98          * Get the name of the config this CHILD_SA uses.
  99          *
 100          * @return                      name
 101          */
 102         char* (*get_name) (child_sa_t *this);
 103
 104         /**
 105          * Get the reqid of the CHILD SA.
 106          *
 107          * Every CHILD_SA has a reqid. The kernel uses this ID to
 108          * identify it.
 109          *
 110          * @return                      reqid of the CHILD SA
 111          */
 112         u_int32_t (*get_reqid)(child_sa_t *this);
 113
 114         /**
 115          * Get the SPI of this CHILD_SA.
 116          *
 117          * Set the boolean parameter inbound to TRUE to
 118          * get the SPI for which we receive packets, use
 119          * FALSE to get those we use for sending packets.
 120          *
 121          * @param inbound       TRUE to get inbound SPI, FALSE for outbound.
 122          * @return                      SPI of the CHILD SA
 123          */
 124         u_int32_t (*get_spi) (child_sa_t *this, bool inbound);
 125
 126         /**
 127          * Get the CPI of this CHILD_SA.
 128          *
 129          * Set the boolean parameter inbound to TRUE to
 130          * get the CPI for which we receive packets, use
 131          * FALSE to get those we use for sending packets.
 132          *
 133          * @param inbound       TRUE to get inbound CPI, FALSE for outbound.
 134          * @return                      CPI of the CHILD SA
 135          */
 136         u_int16_t (*get_cpi) (child_sa_t *this, bool inbound);
 137
 138         /**
 139          * Get the protocol which this CHILD_SA uses to protect traffic.
 140          *
 141          * @return                      AH | ESP
 142          */
 143         protocol_id_t (*get_protocol) (child_sa_t *this);
 144
 145         /**
 146          * Get info and statistics about this CHILD_SA.
 147          *
 148          * @param mode          mode this IKE_SA uses
 149          * @param encr_algo     encryption algorithm used by this CHILD_SA.
 150          * @param encr_len      key length of the algorithm, if any
 151          * @param int_algo      integrity algorithm used by this CHILD_SA
 152          * @param int_len       key length of the algorithm, if any
 153          * @param rekey         time when rekeying is scheduled
 154          * @param use_in        time when last traffic was seen coming in
 155          * @param use_out       time when last traffic was seen going out
 156          * @param use_fwd       time when last traffic was getting forwarded
 157          */
 158         void (*get_stats)(child_sa_t *this, ipsec_mode_t *mode,
 159                                           encryption_algorithm_t *encr, size_t *encr_len,
 160                                           integrity_algorithm_t *int_algo, size_t *int_len,
 161                                           u_int32_t *rekey, u_int32_t *use_in, u_int32_t *use_out,
 162                                           u_int32_t *use_fwd);
 163
 164         /**
 165          * Allocate SPIs for given proposals.
 166          *
 167          * Since the kernel manages SPIs for us, we need
 168          * to allocate them. If a proposal contains more
 169          * than one protocol, for each protocol an SPI is
 170          * allocated. SPIs are stored internally and written
 171          * back to the proposal.
 172          *
 173          * @param proposals     list of proposals for which SPIs are allocated
 174          */
 175         status_t (*alloc)(child_sa_t *this, linked_list_t* proposals);
 176
 177         /**
 178          * Install the kernel SAs for a proposal, without previous SPI allocation.
 179          *
 180          * @param proposal      proposal for which SPIs are allocated
 181          * @param mode          mode for the CHILD_SA
 182          * @param prf_plus      key material to use for key derivation
 183          * @return                      SUCCESS or FAILED
 184          */
 185         status_t (*add)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
 186                                         prf_plus_t *prf_plus);
 187
 188         /**
 189          * Install the kernel SAs for a proposal, after SPIs have been allocated.
 190          *
 191          * Updates an SA, for which SPIs are already allocated via alloc().
 192          *
 193          * @param proposal      proposal for which SPIs are allocated
 194          * @param mode          mode for the CHILD_SA
 195          * @param prf_plus      key material to use for key derivation
 196          * @return                      SUCCESS or FAILED
 197          */
 198         status_t (*update)(child_sa_t *this, proposal_t *proposal, ipsec_mode_t mode,
 199                                            prf_plus_t *prf_plus);
 200
 201         /**
 202          * Update the hosts in the kernel SAs and policies.
 203          *
 204          * The CHILD must be INSTALLED to do this update.
 205          *
 206          * @param me            the new local host
 207          * @param other         the new remote host
 208          * @param                       TRUE to use UDP encapsulation for NAT traversal
 209          * @return                      SUCCESS or FAILED
 210          */
 211         status_t (*update_hosts)(child_sa_t *this, host_t *me, host_t *other,
 212                                                          bool encap);
 213
 214         /**
 215          * Install the policies using some traffic selectors.
 216          *
 217          * Supplied lists of traffic_selector_t's specify the policies
 218          * to use for this child sa.
 219          *
 220          * @param my_ts         traffic selectors for local site
 221          * @param other_ts      traffic selectors for remote site
 222          * @param mode          mode for the SA: tunnel/transport
 223          * @param proto         protocol for policy, ESP/AH
 224          * @return                      SUCCESS or FAILED
 225          */
 226         status_t (*add_policies)(child_sa_t *this, linked_list_t *my_ts_list,
 227                                                          linked_list_t *other_ts_list, ipsec_mode_t mode,
 228                                                          protocol_id_t proto);
 229
 230         /**
 231          * Get the traffic selectors of added policies of local host.
 232          *
 233          * @param local         TRUE for own traffic selectors, FALSE for remote
 234          * @return                      list of traffic selectors
 235          */
 236         linked_list_t* (*get_traffic_selectors) (child_sa_t *this, bool local);
 237
 238         /**
 239          * Get the time of this child_sa_t's last use (i.e. last use of any of its policies)
 240          *
 241          * @param inbound       query for in- or outbound usage
 242          * @param use_time      the time
 243          * @return                      SUCCESS or FAILED
 244          */
 245         status_t (*get_use_time) (child_sa_t *this, bool inbound, time_t *use_time);
 246
 247         /**
 248          * Get the state of the CHILD_SA.
 249          */
 250         child_sa_state_t (*get_state) (child_sa_t *this);
 251
 252         /**
 253          * Set the state of the CHILD_SA.
 254          *
 255          * @param state         state to set on CHILD_SA
 256          */
 257         void (*set_state) (child_sa_t *this, child_sa_state_t state);
 258
 259         /**
 260          * Get the config used to set up this child sa.
 261          *
 262          * @return                      child_cfg
 263          */
 264         child_cfg_t* (*get_config) (child_sa_t *this);
 265
 266         /**
 267          * Set the virtual IP used received from IRAS.
 268          *
 269          * To allow proper setup of firewall rules, the virtual IP is required
 270          * for filtering.
 271          *
 272          * @param ip            own virtual IP
 273          */
 274         void (*set_virtual_ip) (child_sa_t *this, host_t *ip);
 275
 276         /**
 277          * Activate IPComp by setting the transform ID and CPI values.
 278          *
 279          * @param ipcomp        the IPComp transform to use
 280          * @param other_cpi     other Compression Parameter Index
 281          */
 282         void (*activate_ipcomp) (child_sa_t *this, ipcomp_transform_t ipcomp,
 283                                                 u_int16_t other_cpi);
 284
 285         /**
 286          * Returns the Compression Parameter Index (CPI) allocated from the kernel.
 287          *
 288          * @return                      allocated CPI
 289          */
 290         u_int16_t (*allocate_cpi) (child_sa_t *this);
 291
 292         /**
 293          * Destroys a child_sa.
 294          */
 295         void (*destroy) (child_sa_t *this);
 296 };
 297
 298 /**
 299  * Constructor to create a new child_sa_t.
 300  *
 301  * @param me                    own address
 302  * @param other                 remote address
 303  * @param my_id                 id of own peer
 304  * @param other_id              id of remote peer
 305  * @param config                config to use for this CHILD_SA
 306  * @param reqid                 reqid of old CHILD_SA when rekeying, 0 otherwise
 307  * @param encap                 TRUE to enable UDP encapsulation (NAT traversal)
 308  * @return                              child_sa_t object
 309  */
 310 child_sa_t * child_sa_create(host_t *me, host_t *other,
 311                                                          identification_t *my_id, identification_t* other_id,
 312                                                          child_cfg_t *config, u_int32_t reqid, bool encap);
 313
 314 #endif /*CHILD_SA_H_ @} */