src/libcharon/kernel/kernel_interface.h

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