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 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 #include <kernel/kernel_ipsec.h>
  36 #include <kernel/kernel_net.h>
  37
  38 /**
  39  * Constructor function for ipsec kernel interface
  40  */
  41 typedef kernel_ipsec_t* (*kernel_ipsec_constructor_t)(void);
  42
  43 /**
  44  * Constructor function for network kernel interface
  45  */
  46 typedef kernel_net_t* (*kernel_net_constructor_t)(void);
  47
  48 /**
  49  * Manager and wrapper for different kernel interfaces.
  50  *
  51  * The kernel interface handles the communication with the kernel
  52  * for SA and policy management and interface and IP address management.
  53  */
  54 struct kernel_interface_t {
  55
  56         /**
  57          * Get a SPI from the kernel.
  58          *
  59          * @warning get_spi() implicitly creates an SA with
  60          * the allocated SPI, therefore the replace flag
  61          * in add_sa() must be set when installing this SA.
  62          *
  63          * @param src           source address of SA
  64          * @param dst           destination address of SA
  65          * @param protocol      protocol for SA (ESP/AH)
  66          * @param reqid         unique ID for this SA
  67          * @param spi           allocated spi
  68          * @return                              SUCCESS if operation completed
  69          */
  70         status_t (*get_spi)(kernel_interface_t *this, host_t *src, host_t *dst,
  71                                                 protocol_id_t protocol, u_int32_t reqid, u_int32_t *spi);
  72
  73         /**
  74          * Get a Compression Parameter Index (CPI) from the kernel.
  75          *
  76          * @param src           source address of SA
  77          * @param dst           destination address of SA
  78          * @param reqid         unique ID for the corresponding SA
  79          * @param cpi           allocated cpi
  80          * @return                              SUCCESS if operation completed
  81          */
  82         status_t (*get_cpi)(kernel_interface_t *this, host_t *src, host_t *dst,
  83                                                 u_int32_t reqid, u_int16_t *cpi);
  84
  85         /**
  86          * Add an SA to the SAD.
  87          *
  88          * add_sa() may update an already allocated
  89          * SPI (via get_spi). In this case, the replace
  90          * flag must be set.
  91          * This function does install a single SA for a
  92          * single protocol in one direction. The kernel-interface
  93          * gets the keys itself from the PRF, as we don't know
  94          * his algorithms and key sizes.
  95          *
  96          * @param src                   source address for this SA
  97          * @param dst                   destination address for this SA
  98          * @param spi                   SPI allocated by us or remote peer
  99          * @param protocol              protocol for this SA (ESP/AH)
 100          * @param reqid                 unique ID for this SA
 101          * @param expire_soft   lifetime in seconds before rekeying
 102          * @param expire_hard   lifetime in seconds before delete
 103          * @param enc_alg               Algorithm to use for encryption (ESP only)
 104          * @param enc_key               key to use for encryption
 105          * @param int_alg               Algorithm to use for integrity protection
 106          * @param int_key               key to use for integrity protection
 107          * @param mode                  mode of the SA (tunnel, transport)
 108          * @param ipcomp                IPComp transform to use
 109          * @param encap                 enable UDP encapsulation for NAT traversal
 110          * @param replace               Should an already installed SA be updated?
 111          * @return                              SUCCESS if operation completed
 112          */
 113         status_t (*add_sa) (kernel_interface_t *this,
 114                                                 host_t *src, host_t *dst, u_int32_t spi,
 115                                                 protocol_id_t protocol, u_int32_t reqid,
 116                                                 u_int64_t expire_soft, u_int64_t expire_hard,
 117                                             u_int16_t enc_alg, chunk_t enc_key,
 118                                             u_int16_t int_alg, chunk_t int_key,
 119                                                 ipsec_mode_t mode, u_int16_t ipcomp, bool encap,
 120                                                 bool update);
 121
 122         /**
 123          * Update the hosts on an installed SA.
 124          *
 125          * We cannot directly update the destination address as the kernel
 126          * requires the spi, the protocol AND the destination address (and family)
 127          * to identify SAs. Therefore if the destination address changed we
 128          * create a new SA and delete the old one.
 129          *
 130          * @param spi                   SPI of the SA
 131          * @param protocol              protocol for this SA (ESP/AH)
 132          * @param src                   current source address
 133          * @param dst                   current destination address
 134          * @param new_src               new source address
 135          * @param new_dst               new destination address
 136          * @param encap                 use UDP encapsulation
 137          * @return                              SUCCESS if operation completed
 138          */
 139         status_t (*update_sa)(kernel_interface_t *this,
 140                                                   u_int32_t spi, protocol_id_t protocol,
 141                                                   host_t *src, host_t *dst,
 142                                                   host_t *new_src, host_t *new_dst, bool encap);
 143
 144         /**
 145          * Delete a previously installed SA from the SAD.
 146          *
 147          * @param dst                   destination address for this SA
 148          * @param spi                   SPI allocated by us or remote peer
 149          * @param protocol              protocol for this SA (ESP/AH)
 150          * @return                              SUCCESS if operation completed
 151          */
 152         status_t (*del_sa) (kernel_interface_t *this, host_t *dst, u_int32_t spi,
 153                                                 protocol_id_t protocol);
 154
 155         /**
 156          * Add a policy to the SPD.
 157          *
 158          * A policy is always associated to an SA. Traffic which matches a
 159          * policy is handled by the SA with the same reqid.
 160          *
 161          * @param src                   source address of SA
 162          * @param dst                   dest address of SA
 163          * @param src_ts                traffic selector to match traffic source
 164          * @param dst_ts                traffic selector to match traffic dest
 165          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 166          * @param protocol              protocol to use to protect traffic (AH/ESP)
 167          * @param reqid                 unique ID of an SA to use to enforce policy
 168          * @param high_prio             if TRUE, uses a higher priority than any with FALSE
 169          * @param mode                  mode of SA (tunnel, transport)
 170          * @param ipcomp                the IPComp transform used
 171          * @return                              SUCCESS if operation completed
 172          */
 173         status_t (*add_policy) (kernel_interface_t *this,
 174                                                         host_t *src, host_t *dst,
 175                                                         traffic_selector_t *src_ts,
 176                                                         traffic_selector_t *dst_ts,
 177                                                         policy_dir_t direction, protocol_id_t protocol,
 178                                                         u_int32_t reqid, bool high_prio, ipsec_mode_t mode,
 179                                                         u_int16_t ipcomp);
 180
 181         /**
 182          * Query the use time of a policy.
 183          *
 184          * The use time of a policy is the time the policy was used
 185          * for the last time.
 186          *
 187          * @param src_ts                traffic selector to match traffic source
 188          * @param dst_ts                traffic selector to match traffic dest
 189          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 190          * @param[out] use_time the time of this SA's last use
 191          * @return                              SUCCESS if operation completed
 192          */
 193         status_t (*query_policy) (kernel_interface_t *this,
 194                                                           traffic_selector_t *src_ts,
 195                                                           traffic_selector_t *dst_ts,
 196                                                           policy_dir_t direction, u_int32_t *use_time);
 197
 198         /**
 199          * Remove a policy from the SPD.
 200          *
 201          * The kernel interface implements reference counting for policies.
 202          * If the same policy is installed multiple times (in the case of rekeying),
 203          * the reference counter is increased. del_policy() decreases the ref counter
 204          * and removes the policy only when no more references are available.
 205          *
 206          * @param src_ts                traffic selector to match traffic source
 207          * @param dst_ts                traffic selector to match traffic dest
 208          * @param direction             direction of traffic, POLICY_IN, POLICY_OUT, POLICY_FWD
 209          * @return                              SUCCESS if operation completed
 210          */
 211         status_t (*del_policy) (kernel_interface_t *this,
 212                                                         traffic_selector_t *src_ts,
 213                                                         traffic_selector_t *dst_ts,
 214                                                         policy_dir_t direction);
 215
 216         /**
 217          * Get our outgoing source address for a destination.
 218          *
 219          * Does a route lookup to get the source address used to reach dest.
 220          * The returned host is allocated and must be destroyed.
 221          * An optional src address can be used to check if a route is available
 222          * for given source to dest.
 223          *
 224          * @param dest                  target destination address
 225          * @param src                   source address to check, or NULL
 226          * @return                              outgoing source address, NULL if unreachable
 227          */
 228         host_t* (*get_source_addr)(kernel_interface_t *this,
 229                                                            host_t *dest, host_t *src);
 230
 231         /**
 232          * Get the next hop for a destination.
 233          *
 234          * Does a route lookup to get the next hop used to reach dest.
 235          * The returned host is allocated and must be destroyed.
 236          *
 237          * @param dest                  target destination address
 238          * @return                              next hop address, NULL if unreachable
 239          */
 240         host_t* (*get_nexthop)(kernel_interface_t *this, host_t *dest);
 241
 242         /**
 243          * Get the interface name of a local address.
 244          *
 245          * @param host                  address to get interface name from
 246          * @return                              allocated interface name, or NULL if not found
 247          */
 248         char* (*get_interface) (kernel_interface_t *this, host_t *host);
 249
 250         /**
 251          * Creates an enumerator over all local addresses.
 252          *
 253          * This function blocks an internal cached address list until the
 254          * enumerator gets destroyed.
 255          * The hosts are read-only, do not modify of free.
 256          *
 257          * @param include_down_ifaces   TRUE to enumerate addresses from down interfaces
 258          * @param include_virtual_ips   TRUE to enumerate virtual ip addresses
 259          * @return                                              enumerator over host_t's
 260          */
 261         enumerator_t *(*create_address_enumerator) (kernel_interface_t *this,
 262                                                 bool include_down_ifaces, bool include_virtual_ips);
 263
 264         /**
 265          * Add a virtual IP to an interface.
 266          *
 267          * Virtual IPs are attached to an interface. If an IP is added multiple
 268          * times, the IP is refcounted and not removed until del_ip() was called
 269          * as many times as add_ip().
 270          * The virtual IP is attached to the interface where the iface_ip is found.
 271          *
 272          * @param virtual_ip    virtual ip address to assign
 273          * @param iface_ip              IP of an interface to attach virtual IP
 274          * @return                              SUCCESS if operation completed
 275          */
 276         status_t (*add_ip) (kernel_interface_t *this, host_t *virtual_ip,
 277                                                 host_t *iface_ip);
 278
 279         /**
 280          * Remove a virtual IP from an interface.
 281          *
 282          * The kernel interface uses refcounting, see add_ip().
 283          *
 284          * @param virtual_ip    virtual ip address to assign
 285          * @return                              SUCCESS if operation completed
 286          */
 287         status_t (*del_ip) (kernel_interface_t *this, host_t *virtual_ip);
 288
 289         /**
 290          * Add a route.
 291          *
 292          * @param dst_net               destination net
 293          * @param prefixlen             destination net prefix length
 294          * @param gateway               gateway for this route
 295          * @param src_ip                sourc ip of the route
 296          * @param if_name               name of the interface the route is bound to
 297          * @return                              SUCCESS if operation completed
 298          *                                              ALREADY_DONE if the route already exists
 299          */
 300         status_t (*add_route) (kernel_interface_t *this, chunk_t dst_net, u_int8_t prefixlen,
 301                                                                 host_t *gateway, host_t *src_ip, char *if_name);
 302
 303         /**
 304          * Delete a route.
 305          *
 306          * @param dst_net               destination net
 307          * @param prefixlen             destination net prefix length
 308          * @param gateway               gateway for this route
 309          * @param src_ip                sourc ip of the route
 310          * @param if_name               name of the interface the route is bound to
 311          * @return                              SUCCESS if operation completed
 312          */
 313         status_t (*del_route) (kernel_interface_t *this, chunk_t dst_net, u_int8_t prefixlen,
 314                                                                 host_t *gateway, host_t *src_ip, char *if_name);
 315
 316         /**
 317          * manager methods
 318          */
 319
 320         /**
 321          * Tries to find an ip address of a local interface that is included in the
 322          * supplied traffic selector.
 323          *
 324          * @param ts                    traffic selector
 325          * @param ip                    returned ip (has to be destroyed)
 326          * @return                              SUCCESS if address found
 327          */
 328         status_t (*get_address_by_ts) (kernel_interface_t *this,
 329                                                                                 traffic_selector_t *ts, host_t **ip);
 330
 331         /**
 332          * Register an ipsec kernel interface constructor on the manager.
 333          *
 334          * @param create                        constructor to register
 335          */
 336         void (*add_ipsec_interface)(kernel_interface_t *this, kernel_ipsec_constructor_t create);
 337
 338         /**
 339          * Unregister an ipsec kernel interface constructor.
 340          *
 341          * @param create                        constructor to unregister
 342          */
 343         void (*remove_ipsec_interface)(kernel_interface_t *this, kernel_ipsec_constructor_t create);
 344
 345         /**
 346          * Register a network kernel interface constructor on the manager.
 347          *
 348          * @param create                        constructor to register
 349          */
 350         void (*add_net_interface)(kernel_interface_t *this, kernel_net_constructor_t create);
 351
 352         /**
 353          * Unregister a network kernel interface constructor.
 354          *
 355          * @param create                        constructor to unregister
 356          */
 357         void (*remove_net_interface)(kernel_interface_t *this, kernel_net_constructor_t create);
 358
 359         /**
 360          * Create the kernel interfaces classes.
 361          */
 362         void (*create_interfaces)(kernel_interface_t *this);
 363
 364         /**
 365          * Destroys a kernel_interface_manager_t object.
 366          */
 367         void (*destroy) (kernel_interface_t *this);
 368 };
 369
 370 /**
 371  * Creates an object of type kernel_interface_t.
 372  */
 373 kernel_interface_t *kernel_interface_create(void);
 374
 375 #endif /* KERNEL_INTERFACE_H_ @} */