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