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