src/charon/kernel/kernel_interface.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_interface kernel_interface
  23  * @{ @ingroup kernel
  24  */
  25
  26 #ifndef KERNEL_INTERFACE_H_
  27 #define KERNEL_INTERFACE_H_
  28
  29 typedef enum policy_dir_t policy_dir_t;
  30 typedef struct kernel_interface_t kernel_interface_t;
  31
  32 #include <utils/host.h>
  33 #include <crypto/prf_plus.h>
  34 #include <encoding/payloads/proposal_substructure.h>
  35
  36
  37 /**
  38  * Direction of a policy. These are equal to those
  39  * defined in xfrm.h, but we want to stay implementation
  40  * neutral here.
  41  */
  42 enum policy_dir_t {
  43         /** Policy for inbound traffic */
  44         POLICY_IN = 0,
  45         /** Policy for outbound traffic */
  46         POLICY_OUT = 1,
  47         /** Policy for forwarded traffic */
  48         POLICY_FWD = 2,
  49 };
  50
  51 /**
  52  * Interface to the kernel.
  53  *
  54  * The kernel interface handles the communication with the kernel
  55  * for SA and policy management. It allows setup of these, and provides
  56  * further the handling of kernel events.
  57  * Policy information are cached in the interface. This is necessary to do
  58  * reference counting. The Linux kernel does not allow the same policy
  59  * installed twice, but we need this as CHILD_SA exist multiple times
  60  * when rekeying. Thats why we do reference counting of policies.
  61  */
  62 struct kernel_interface_t {
  63
  64         /**
  65          * Get a SPI from the kernel.
  66          *
  67          * @warning get_spi() implicitely creates an SA with
  68          * the allocated SPI, therefore the replace flag
  69          * in add_sa() must be set when installing this SA.
  70          *
  71          * @param src           source address of SA
  72          * @param dst           destination address of SA
  73          * @param protocol      protocol for SA (ESP/AH)
  74          * @param reqid         unique ID for this SA
  75          * @param spi           allocated spi
  76          * @return                              SUCCESS if operation completed
  77          */
  78         status_t (*get_spi)(kernel_interface_t *this, host_t *src, host_t *dst,
  79                                                 protocol_id_t protocol, u_int32_t reqid, u_int32_t *spi);
  80
  81         /**
  82          * Get a Compression Parameter Index (CPI) from the kernel.
  83          *
  84          * @param src           source address of SA
  85          * @param dst           destination address of SA
  86          * @param reqid         unique ID for the corresponding SA
  87          * @param cpi           allocated cpi
  88          * @return                              SUCCESS if operation completed
  89          */
  90         status_t (*get_cpi)(kernel_interface_t *this, host_t *src, host_t *dst,
  91                                                 u_int32_t reqid, u_int16_t *cpi);
  92
  93         /**
  94          * Add an SA to the SAD.
  95          *
  96          * add_sa() may update an already allocated
  97          * SPI (via get_spi). In this case, the replace
  98          * flag must be set.
  99          * This function does install a single SA for a
 100          * single protocol in one direction. The kernel-interface
 101          * gets the keys itself from the PRF, as we don't know
 102          * his algorithms and key sizes.
 103          *
 104          * @param src                   source address for this SA
 105          * @param dst                   destination address for this SA
 106          * @param spi                   SPI allocated by us or remote peer
 107          * @param protocol              protocol for this SA (ESP/AH)
 108          * @param reqid                 unique ID for this SA
 109          * @param expire_soft   lifetime in seconds before rekeying
 110          * @param expire_hard   lieftime in seconds before delete
 111          * @param enc_alg               Algorithm to use for encryption (ESP only)
 112          * @param enc_size              key length of encryption algorithm, if dynamic
 113          * @param int_alg               Algorithm to use for integrity protection
 114          * @param int_size              key length of integrity algorithm, if dynamic
 115          * @param prf_plus              PRF to derive keys from
 116          * @param mode                  mode of the SA (tunnel, transport)
 117          * @param ipcomp                IPComp transform to use
 118          * @param encap                 enable UDP encapsulation for NAT traversal
 119          * @param replace               Should an already installed SA be updated?
 120          * @return                              SUCCESS if operation completed
 121          */
 122         status_t (*add_sa) (kernel_interface_t *this,
 123                                                 host_t *src, host_t *dst, u_int32_t spi,
 124                                                 protocol_id_t protocol, u_int32_t reqid,
 125                                                 u_int64_t expire_soft, u_int64_t expire_hard,
 126                                             u_int16_t enc_alg, u_int16_t enc_size,
 127                                             u_int16_t int_alg, u_int16_t int_size,
 128                                                 prf_plus_t *prf_plus, mode_t mode,
 129                                                 u_int16_t ipcomp, bool encap,
 130                                                 bool update);
 131
 132         /**
 133          * Update the hosts on an installed SA.
 134          *
 135          * We cannot directly update the destination address as the kernel
 136          * requires the spi, the protocol AND the destination address (and family)
 137          * to identify SAs. Therefore if the destination address changed we
 138          * create a new SA and delete the old one.
 139          *
 140          * @param spi                   SPI of the SA
 141          * @param protocol              protocol for this SA (ESP/AH)
 142          * @param src                   current source address
 143          * @param dst                   current destination address
 144          * @param new_src               new source address
 145          * @param new_dst               new destination address
 146          * @param encap                 use UDP encapsulation
 147          * @return                              SUCCESS if operation completed
 148          */
 149         status_t (*update_sa)(kernel_interface_t *this,
 150                                                   u_int32_t spi, protocol_id_t protocol,
 151                                                   host_t *src, host_t *dst,
 152                                                   host_t *new_src, host_t *new_dst, bool encap);
 153
 154         /**
 155          * Query the use time of an SA.
 156          *
 157          * The use time of an SA is not the time of the last usage, but
 158          * the time of the first usage of the SA.
 159          *
 160          * @param dst                   destination address for this SA
 161          * @param spi                   SPI allocated by us or remote peer
 162          * @param protocol              protocol for this SA (ESP/AH)
 163          * @param use_time              pointer receives the time of this SA's last use
 164          * @return                              SUCCESS if operation completed
 165          */
 166         status_t (*query_sa) (kernel_interface_t *this, host_t *dst, u_int32_t spi,
 167                                                   protocol_id_t protocol, u_int32_t *use_time);
 168
 169         /**
 170          * Delete a previusly installed SA from the SAD.
 171          *
 172          * @param dst                   destination address for this SA
 173          * @param spi                   SPI allocated by us or remote peer
 174          * @param protocol              protocol for this SA (ESP/AH)
 175          * @return                              SUCCESS if operation completed
 176          */
 177         status_t (*del_sa) (kernel_interface_t *this, host_t *dst, u_int32_t spi,
 178                                                 protocol_id_t protocol);
 179
 180         /**
 181          * Add a policy to the SPD.
 182          *
 183          * A policy is always associated to an SA. Traffic which matches a
 184          * policy is handled by the SA with the same reqid.
 185          *
 186          * @param src                   source address of SA
 187          * @param dst                   dest address of SA
 188          * @param src_ts                traffic selector to match traffic source
 189          * @param dst_ts                traffic selector to match traffic dest
 190          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 191          * @param protocol              protocol to use to protect traffic (AH/ESP)
 192          * @param reqid                 uniqe ID of an SA to use to enforce policy
 193          * @param high_prio             if TRUE, uses a higher priority than any with FALSE
 194          * @param mode                  mode of SA (tunnel, transport)
 195          * @param ipcomp                the IPComp transform used
 196          * @return                              SUCCESS if operation completed
 197          */
 198         status_t (*add_policy) (kernel_interface_t *this,
 199                                                         host_t *src, host_t *dst,
 200                                                         traffic_selector_t *src_ts,
 201                                                         traffic_selector_t *dst_ts,
 202                                                         policy_dir_t direction, protocol_id_t protocol,
 203                                                         u_int32_t reqid, bool high_prio, mode_t mode,
 204                                                         u_int16_t ipcomp);
 205
 206         /**
 207          * Query the use time of a policy.
 208          *
 209          * The use time of a policy is the time the policy was used
 210          * for the last time.
 211          *
 212          * @param src_ts                traffic selector to match traffic source
 213          * @param dst_ts                traffic selector to match traffic dest
 214          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 215          * @param[out] use_time the time of this SA's last use
 216          * @return                              SUCCESS if operation completed
 217          */
 218         status_t (*query_policy) (kernel_interface_t *this,
 219                                                           traffic_selector_t *src_ts,
 220                                                           traffic_selector_t *dst_ts,
 221                                                           policy_dir_t direction, u_int32_t *use_time);
 222
 223         /**
 224          * Remove a policy from the SPD.
 225          *
 226          * The kernel interface implements reference counting for policies.
 227          * If the same policy is installed multiple times (in the case of rekeying),
 228          * the reference counter is increased. del_policy() decreases the ref counter
 229          * and removes the policy only when no more references are available.
 230          *
 231          * @param src_ts                traffic selector to match traffic source
 232          * @param dst_ts                traffic selector to match traffic dest
 233          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 234          * @return                              SUCCESS if operation completed
 235          */
 236         status_t (*del_policy) (kernel_interface_t *this,
 237                                                         traffic_selector_t *src_ts,
 238                                                         traffic_selector_t *dst_ts,
 239                                                         policy_dir_t direction);
 240
 241         /**
 242          * Get our outgoing source address for a destination.
 243          *
 244          * Does a route lookup to get the source address used to reach dest.
 245          * The returned host is allocated and must be destroyed.
 246          *
 247          * @param dest                  target destination address
 248          * @return                              outgoing source address, NULL if unreachable
 249          */
 250         host_t* (*get_source_addr)(kernel_interface_t *this, host_t *dest);
 251
 252         /**
 253          * Get the interface name of a local address.
 254          *
 255          * @param host                  address to get interface name from
 256          * @return                              allocated interface name, or NULL if not found
 257          */
 258         char* (*get_interface) (kernel_interface_t *this, host_t *host);
 259
 260         /**
 261          * Creates an iterator over all local addresses.
 262          *
 263          * This function blocks an internal cached address list until the
 264          * iterator gets destroyed.
 265          * These hosts are read-only, do not modify or free.
 266          *
 267          * @return                              iterator over host_t's
 268          */
 269         iterator_t *(*create_address_iterator) (kernel_interface_t *this);
 270
 271         /**
 272          * Add a virtual IP to an interface.
 273          *
 274          * Virtual IPs are attached to an interface. If an IP is added multiple
 275          * times, the IP is refcounted and not removed until del_ip() was called
 276          * as many times as add_ip().
 277          * The virtual IP is attached to the interface where the iface_ip is found.
 278          *
 279          * @param virtual_ip    virtual ip address to assign
 280          * @param iface_ip              IP of an interface to attach virtual IP
 281          * @return                              SUCCESS if operation completed
 282          */
 283         status_t (*add_ip) (kernel_interface_t *this, host_t *virtual_ip,
 284                                                 host_t *iface_ip);
 285
 286         /**
 287          * Remove a virtual IP from an interface.
 288          *
 289          * The kernel interface uses refcounting, see add_ip().
 290          *
 291          * @param virtual_ip    virtual ip address to assign
 292          * @return                              SUCCESS if operation completed
 293          */
 294         status_t (*del_ip) (kernel_interface_t *this, host_t *virtual_ip);
 295
 296         /**
 297          * Destroys a kernel_interface object.
 298          */
 299         void (*destroy) (kernel_interface_t *kernel_interface);
 300 };
 301
 302 /**
 303  * Creates an object of type kernel_interface_t.
 304  */
 305 kernel_interface_t *kernel_interface_create(void);
 306
 307 #endif /*KERNEL_INTERFACE_H_ @} */