src/charon/kernel/kernel_ipsec.h

   1 /*
   2  * Copyright (C) 2006-2008 Tobias Brunner
   3  * Copyright (C) 2006 Daniel Roethlisberger
   4  * Copyright (C) 2005-2006 Martin Willi
   5  * Copyright (C) 2005 Jan Hutter
   6  * Hochschule fuer Technik Rapperswil
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU General Public License as published by the
  10  * Free Software Foundation; either version 2 of the License, or (at your
  11  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  15  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * for more details.
  17  *
  18  * $Id$
  19  */
  20
  21 /**
  22  * @defgroup kernel_ipsec kernel_ipsec
  23  * @{ @ingroup kernel
  24  */
  25
  26 #ifndef KERNEL_IPSEC_H_
  27 #define KERNEL_IPSEC_H_
  28
  29 typedef enum ipsec_mode_t ipsec_mode_t;
  30 typedef enum policy_dir_t policy_dir_t;
  31 typedef struct kernel_ipsec_t kernel_ipsec_t;
  32
  33 #include <utils/host.h>
  34 #include <crypto/prf_plus.h>
  35 #include <encoding/payloads/proposal_substructure.h>
  36
  37 /**
  38  * Mode of an CHILD_SA.
  39  *
  40  * These are equal to those defined in XFRM, so don't change.
  41  */
  42 enum ipsec_mode_t {
  43         /** transport mode, no inner address */
  44         MODE_TRANSPORT = 0,
  45         /** tunnel mode, inner and outer addresses */
  46         MODE_TUNNEL = 1,
  47         /** BEET mode, tunnel mode but fixed, bound inner addresses */
  48         MODE_BEET = 4,
  49 };
  50
  51 /**
  52  * enum names for ipsec_mode_t.
  53  */
  54 extern enum_name_t *ipsec_mode_names;
  55
  56 /**
  57  * Direction of a policy. These are equal to those
  58  * defined in xfrm.h, but we want to stay implementation
  59  * neutral here.
  60  */
  61 enum policy_dir_t {
  62         /** Policy for inbound traffic */
  63         POLICY_IN = 0,
  64         /** Policy for outbound traffic */
  65         POLICY_OUT = 1,
  66         /** Policy for forwarded traffic */
  67         POLICY_FWD = 2,
  68 };
  69
  70 /**
  71  * enum names for policy_dir_t.
  72  */
  73 extern enum_name_t *policy_dir_names;
  74
  75 /**
  76  * Interface to the ipsec subsystem of the kernel.
  77  *
  78  * The kernel ipsec interface handles the communication with the kernel
  79  * for SA and policy management. It allows setup of these, and provides
  80  * further the handling of kernel events.
  81  * Policy information are cached in the interface. This is necessary to do
  82  * reference counting. The Linux kernel does not allow the same policy
  83  * installed twice, but we need this as CHILD_SA exist multiple times
  84  * when rekeying. Thats why we do reference counting of policies.
  85  */
  86 struct kernel_ipsec_t {
  87
  88         /**
  89          * Get a SPI from the kernel.
  90          *
  91          * @warning get_spi() implicitly creates an SA with
  92          * the allocated SPI, therefore the replace flag
  93          * in add_sa() must be set when installing this SA.
  94          *
  95          * @param src           source address of SA
  96          * @param dst           destination address of SA
  97          * @param protocol      protocol for SA (ESP/AH)
  98          * @param reqid         unique ID for this SA
  99          * @param spi           allocated spi
 100          * @return                              SUCCESS if operation completed
 101          */
 102         status_t (*get_spi)(kernel_ipsec_t *this, host_t *src, host_t *dst,
 103                                                 protocol_id_t protocol, u_int32_t reqid, u_int32_t *spi);
 104
 105         /**
 106          * Get a Compression Parameter Index (CPI) from the kernel.
 107          *
 108          * @param src           source address of SA
 109          * @param dst           destination address of SA
 110          * @param reqid         unique ID for the corresponding SA
 111          * @param cpi           allocated cpi
 112          * @return                              SUCCESS if operation completed
 113          */
 114         status_t (*get_cpi)(kernel_ipsec_t *this, host_t *src, host_t *dst,
 115                                                 u_int32_t reqid, u_int16_t *cpi);
 116
 117         /**
 118          * Add an SA to the SAD.
 119          *
 120          * add_sa() may update an already allocated
 121          * SPI (via get_spi). In this case, the replace
 122          * flag must be set.
 123          * This function does install a single SA for a
 124          * single protocol in one direction. The kernel-interface
 125          * gets the keys itself from the PRF, as we don't know
 126          * his algorithms and key sizes.
 127          *
 128          * @param src                   source address for this SA
 129          * @param dst                   destination address for this SA
 130          * @param spi                   SPI allocated by us or remote peer
 131          * @param protocol              protocol for this SA (ESP/AH)
 132          * @param reqid                 unique ID for this SA
 133          * @param expire_soft   lifetime in seconds before rekeying
 134          * @param expire_hard   lifetime in seconds before delete
 135          * @param enc_alg               Algorithm to use for encryption (ESP only)
 136          * @param enc_size              key length of encryption algorithm, if dynamic
 137          * @param int_alg               Algorithm to use for integrity protection
 138          * @param int_size              key length of integrity algorithm, if dynamic
 139          * @param prf_plus              PRF to derive keys from
 140          * @param mode                  mode of the SA (tunnel, transport)
 141          * @param ipcomp                IPComp transform to use
 142          * @param encap                 enable UDP encapsulation for NAT traversal
 143          * @param replace               Should an already installed SA be updated?
 144          * @return                              SUCCESS if operation completed
 145          */
 146         status_t (*add_sa) (kernel_ipsec_t *this,
 147                                                 host_t *src, host_t *dst, u_int32_t spi,
 148                                                 protocol_id_t protocol, u_int32_t reqid,
 149                                                 u_int64_t expire_soft, u_int64_t expire_hard,
 150                                             u_int16_t enc_alg, u_int16_t enc_size,
 151                                             u_int16_t int_alg, u_int16_t int_size,
 152                                                 prf_plus_t *prf_plus, ipsec_mode_t mode,
 153                                                 u_int16_t ipcomp, bool encap,
 154                                                 bool update);
 155
 156         /**
 157          * Update the hosts on an installed SA.
 158          *
 159          * We cannot directly update the destination address as the kernel
 160          * requires the spi, the protocol AND the destination address (and family)
 161          * to identify SAs. Therefore if the destination address changed we
 162          * create a new SA and delete the old one.
 163          *
 164          * @param spi                   SPI of the SA
 165          * @param protocol              protocol for this SA (ESP/AH)
 166          * @param src                   current source address
 167          * @param dst                   current destination address
 168          * @param new_src               new source address
 169          * @param new_dst               new destination address
 170          * @param encap                 use UDP encapsulation
 171          * @return                              SUCCESS if operation completed
 172          */
 173         status_t (*update_sa)(kernel_ipsec_t *this,
 174                                                   u_int32_t spi, protocol_id_t protocol,
 175                                                   host_t *src, host_t *dst,
 176                                                   host_t *new_src, host_t *new_dst, bool encap);
 177
 178         /**
 179          * Delete a previusly installed SA from the SAD.
 180          *
 181          * @param dst                   destination address for this SA
 182          * @param spi                   SPI allocated by us or remote peer
 183          * @param protocol              protocol for this SA (ESP/AH)
 184          * @return                              SUCCESS if operation completed
 185          */
 186         status_t (*del_sa) (kernel_ipsec_t *this, host_t *dst, u_int32_t spi,
 187                                                 protocol_id_t protocol);
 188
 189         /**
 190          * Add a policy to the SPD.
 191          *
 192          * A policy is always associated to an SA. Traffic which matches a
 193          * policy is handled by the SA with the same reqid.
 194          *
 195          * @param src                   source address of SA
 196          * @param dst                   dest address of SA
 197          * @param src_ts                traffic selector to match traffic source
 198          * @param dst_ts                traffic selector to match traffic dest
 199          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 200          * @param protocol              protocol to use to protect traffic (AH/ESP)
 201          * @param reqid                 unique ID of an SA to use to enforce policy
 202          * @param high_prio             if TRUE, uses a higher priority than any with FALSE
 203          * @param mode                  mode of SA (tunnel, transport)
 204          * @param ipcomp                the IPComp transform used
 205          * @return                              SUCCESS if operation completed
 206          */
 207         status_t (*add_policy) (kernel_ipsec_t *this,
 208                                                         host_t *src, host_t *dst,
 209                                                         traffic_selector_t *src_ts,
 210                                                         traffic_selector_t *dst_ts,
 211                                                         policy_dir_t direction, protocol_id_t protocol,
 212                                                         u_int32_t reqid, bool high_prio, ipsec_mode_t mode,
 213                                                         u_int16_t ipcomp);
 214
 215         /**
 216          * Query the use time of a policy.
 217          *
 218          * The use time of a policy is the time the policy was used
 219          * for the last time.
 220          *
 221          * @param src_ts                traffic selector to match traffic source
 222          * @param dst_ts                traffic selector to match traffic dest
 223          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 224          * @param[out] use_time the time of this SA's last use
 225          * @return                              SUCCESS if operation completed
 226          */
 227         status_t (*query_policy) (kernel_ipsec_t *this,
 228                                                           traffic_selector_t *src_ts,
 229                                                           traffic_selector_t *dst_ts,
 230                                                           policy_dir_t direction, u_int32_t *use_time);
 231
 232         /**
 233          * Remove a policy from the SPD.
 234          *
 235          * The kernel interface implements reference counting for policies.
 236          * If the same policy is installed multiple times (in the case of rekeying),
 237          * the reference counter is increased. del_policy() decreases the ref counter
 238          * and removes the policy only when no more references are available.
 239          *
 240          * @param src_ts                traffic selector to match traffic source
 241          * @param dst_ts                traffic selector to match traffic dest
 242          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 243          * @return                              SUCCESS if operation completed
 244          */
 245         status_t (*del_policy) (kernel_ipsec_t *this,
 246                                                         traffic_selector_t *src_ts,
 247                                                         traffic_selector_t *dst_ts,
 248                                                         policy_dir_t direction);
 249
 250         /**
 251          * Destroy the implementation.
 252          */
 253         void (*destroy) (kernel_ipsec_t *this);
 254 };
 255
 256 #endif /* KERNEL_IPSEC_H_ @} */