src/charon/kernel/kernel_interface.h

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