src/libhydra/kernel/kernel_interface.h

   1 /*
   2  * Copyright (C) 2006-2012 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 hkernel
  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
  32 #include <kernel/kernel_listener.h>
  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                                                 u_int8_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 mark                  optional mark for this SA
  94          * @param tfc                   Traffic Flow Confidentiality padding for this SA
  95          * @param lifetime              lifetime_cfg_t for this SA
  96          * @param enc_alg               Algorithm to use for encryption (ESP only)
  97          * @param enc_key               key to use for encryption
  98          * @param int_alg               Algorithm to use for integrity protection
  99          * @param int_key               key to use for integrity protection
 100          * @param mode                  mode of the SA (tunnel, transport)
 101          * @param ipcomp                IPComp transform to use
 102          * @param cpi                   CPI for IPComp
 103          * @param encap                 enable UDP encapsulation for NAT traversal
 104          * @param esn                   TRUE to use Extended Sequence Numbers
 105          * @param inbound               TRUE if this is an inbound SA
 106          * @param src_ts                traffic selector with BEET source address
 107          * @param dst_ts                traffic selector with BEET destination address
 108          * @return                              SUCCESS if operation completed
 109          */
 110         status_t (*add_sa) (kernel_interface_t *this,
 111                                                 host_t *src, host_t *dst, u_int32_t spi,
 112                                                 u_int8_t protocol, u_int32_t reqid, mark_t mark,
 113                                                 u_int32_t tfc, lifetime_cfg_t *lifetime,
 114                                                 u_int16_t enc_alg, chunk_t enc_key,
 115                                                 u_int16_t int_alg, chunk_t int_key,
 116                                                 ipsec_mode_t mode, u_int16_t ipcomp, u_int16_t cpi,
 117                                                 bool encap, bool esn, bool inbound,
 118                                                 traffic_selector_t *src_ts, traffic_selector_t *dst_ts);
 119
 120         /**
 121          * Update the hosts on an installed SA.
 122          *
 123          * We cannot directly update the destination address as the kernel
 124          * requires the spi, the protocol AND the destination address (and family)
 125          * to identify SAs. Therefore if the destination address changed we
 126          * create a new SA and delete the old one.
 127          *
 128          * @param spi                   SPI of the SA
 129          * @param protocol              protocol for this SA (ESP/AH)
 130          * @param cpi                   CPI for IPComp, 0 if no IPComp is used
 131          * @param src                   current source address
 132          * @param dst                   current destination address
 133          * @param new_src               new source address
 134          * @param new_dst               new destination address
 135          * @param encap                 current use of UDP encapsulation
 136          * @param new_encap             new use of UDP encapsulation
 137          * @param mark                  optional mark for this SA
 138          * @return                              SUCCESS if operation completed, NOT_SUPPORTED if
 139          *                                        the kernel interface can't update the SA
 140          */
 141         status_t (*update_sa)(kernel_interface_t *this,
 142                                                   u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 143                                                   host_t *src, host_t *dst,
 144                                                   host_t *new_src, host_t *new_dst,
 145                                                   bool encap, bool new_encap, mark_t mark);
 146
 147         /**
 148          * Query the number of bytes processed by an SA from the SAD.
 149          *
 150          * @param src                   source address for this SA
 151          * @param dst                   destination address for this SA
 152          * @param spi                   SPI allocated by us or remote peer
 153          * @param protocol              protocol for this SA (ESP/AH)
 154          * @param mark                  optional mark for this SA
 155          * @param[out] bytes    the number of bytes processed by SA
 156          * @return                              SUCCESS if operation completed
 157          */
 158         status_t (*query_sa) (kernel_interface_t *this, host_t *src, host_t *dst,
 159                                                   u_int32_t spi, u_int8_t protocol, mark_t mark,
 160                                                   u_int64_t *bytes);
 161
 162         /**
 163          * Delete a previously installed SA from the SAD.
 164          *
 165          * @param src                   source address for this SA
 166          * @param dst                   destination address for this SA
 167          * @param spi                   SPI allocated by us or remote peer
 168          * @param protocol              protocol for this SA (ESP/AH)
 169          * @param cpi                   CPI for IPComp or 0
 170          * @param mark                  optional mark for this SA
 171          * @return                              SUCCESS if operation completed
 172          */
 173         status_t (*del_sa) (kernel_interface_t *this, host_t *src, host_t *dst,
 174                                                 u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 175                                                 mark_t mark);
 176
 177         /**
 178          * Flush all SAs from the SAD.
 179          *
 180          * @return                              SUCCESS if operation completed
 181          */
 182         status_t (*flush_sas) (kernel_interface_t *this);
 183
 184         /**
 185          * 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 src                   source address of SA
 191          * @param dst                   dest address of SA
 192          * @param src_ts                traffic selector to match traffic source
 193          * @param dst_ts                traffic selector to match traffic dest
 194          * @param direction             direction of traffic, POLICY_(IN|OUT|FWD)
 195          * @param type                  type of policy, POLICY_(IPSEC|PASS|DROP)
 196          * @param sa                    details about the SA(s) tied to this policy
 197          * @param mark                  mark for this policy
 198          * @param priority              priority of this policy
 199          * @return                              SUCCESS if operation completed
 200          */
 201         status_t (*add_policy) (kernel_interface_t *this,
 202                                                         host_t *src, host_t *dst,
 203                                                         traffic_selector_t *src_ts,
 204                                                         traffic_selector_t *dst_ts,
 205                                                         policy_dir_t direction, policy_type_t type,
 206                                                         ipsec_sa_cfg_t *sa, mark_t mark,
 207                                                         policy_priority_t priority);
 208
 209         /**
 210          * Query the use time of a policy.
 211          *
 212          * The use time of a policy is the time the policy was used
 213          * for the last time.
 214          *
 215          * @param src_ts                traffic selector to match traffic source
 216          * @param dst_ts                traffic selector to match traffic dest
 217          * @param direction             direction of traffic, POLICY_(IN|OUT|FWD)
 218          * @param mark                  optional mark
 219          * @param[out] use_time the time of this SA's last use
 220          * @return                              SUCCESS if operation completed
 221          */
 222         status_t (*query_policy) (kernel_interface_t *this,
 223                                                           traffic_selector_t *src_ts,
 224                                                           traffic_selector_t *dst_ts,
 225                                                           policy_dir_t direction, mark_t mark,
 226                                                           u_int32_t *use_time);
 227
 228         /**
 229          * Remove a policy from the SPD.
 230          *
 231          * The kernel interface implements reference counting for policies.
 232          * If the same policy is installed multiple times (in the case of rekeying),
 233          * the reference counter is increased. del_policy() decreases the ref counter
 234          * and removes the policy only when no more references are available.
 235          *
 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|OUT|FWD)
 239          * @param reqid                 unique ID of the associated SA
 240          * @param mark                  optional mark
 241          * @param priority              priority of the policy
 242          * @return                              SUCCESS if operation completed
 243          */
 244         status_t (*del_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 reqid,
 248                                                         mark_t mark, policy_priority_t priority);
 249
 250         /**
 251          * Flush all policies from the SPD.
 252          *
 253          * @return                              SUCCESS if operation completed
 254          */
 255         status_t (*flush_policies) (kernel_interface_t *this);
 256
 257         /**
 258          * Get our outgoing source address for a destination.
 259          *
 260          * Does a route lookup to get the source address used to reach dest.
 261          * The returned host is allocated and must be destroyed.
 262          * An optional src address can be used to check if a route is available
 263          * for given source to dest.
 264          *
 265          * @param dest                  target destination address
 266          * @param src                   source address to check, or NULL
 267          * @return                              outgoing source address, NULL if unreachable
 268          */
 269         host_t* (*get_source_addr)(kernel_interface_t *this,
 270                                                            host_t *dest, host_t *src);
 271
 272         /**
 273          * Get the next hop for a destination.
 274          *
 275          * Does a route lookup to get the next hop used to reach dest.
 276          * The returned host is allocated and must be destroyed.
 277          *
 278          * @param dest                  target destination address
 279          * @return                              next hop address, NULL if unreachable
 280          */
 281         host_t* (*get_nexthop)(kernel_interface_t *this, host_t *dest);
 282
 283         /**
 284          * Get the interface name of a local address.
 285          *
 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          * Creates an enumerator over all local addresses.
 293          *
 294          * This function blocks an internal cached address list until the
 295          * enumerator gets destroyed.
 296          * The hosts are read-only, do not modify of free.
 297          *
 298          * @param include_down_ifaces   TRUE to enumerate addresses from down interfaces
 299          * @param include_virtual_ips   TRUE to enumerate virtual ip addresses
 300          * @return                                              enumerator over host_t's
 301          */
 302         enumerator_t *(*create_address_enumerator) (kernel_interface_t *this,
 303                                                 bool include_down_ifaces, bool include_virtual_ips);
 304
 305         /**
 306          * Add a virtual IP to an interface.
 307          *
 308          * Virtual IPs are attached to an interface. If an IP is added multiple
 309          * times, the IP is refcounted and not removed until del_ip() was called
 310          * as many times as add_ip().
 311          * The virtual IP is attached to the interface where the iface_ip is found.
 312          *
 313          * @param virtual_ip    virtual ip address to assign
 314          * @param iface_ip              IP of an interface to attach virtual IP
 315          * @return                              SUCCESS if operation completed
 316          */
 317         status_t (*add_ip) (kernel_interface_t *this, host_t *virtual_ip,
 318                                                 host_t *iface_ip);
 319
 320         /**
 321          * Remove a virtual IP from an interface.
 322          *
 323          * The kernel interface uses refcounting, see add_ip().
 324          *
 325          * @param virtual_ip    virtual ip address to assign
 326          * @return                              SUCCESS if operation completed
 327          */
 328         status_t (*del_ip) (kernel_interface_t *this, host_t *virtual_ip);
 329
 330         /**
 331          * Add a route.
 332          *
 333          * @param dst_net               destination net
 334          * @param prefixlen             destination net prefix length
 335          * @param gateway               gateway for this route
 336          * @param src_ip                sourc ip of the route
 337          * @param if_name               name of the interface the route is bound to
 338          * @return                              SUCCESS if operation completed
 339          *                                              ALREADY_DONE if the route already exists
 340          */
 341         status_t (*add_route) (kernel_interface_t *this, chunk_t dst_net,
 342                                                    u_int8_t prefixlen, host_t *gateway, host_t *src_ip,
 343                                                    char *if_name);
 344
 345         /**
 346          * Delete a route.
 347          *
 348          * @param dst_net               destination net
 349          * @param prefixlen             destination net prefix length
 350          * @param gateway               gateway for this route
 351          * @param src_ip                sourc ip of the route
 352          * @param if_name               name of the interface the route is bound to
 353          * @return                              SUCCESS if operation completed
 354          */
 355         status_t (*del_route) (kernel_interface_t *this, chunk_t dst_net,
 356                                                    u_int8_t prefixlen, host_t *gateway, host_t *src_ip,
 357                                                    char *if_name);
 358
 359         /**
 360          * Set up a bypass policy for a given socket.
 361          *
 362          * @param fd                    socket file descriptor to setup policy for
 363          * @param family                protocol family of the socket
 364          * @return                              TRUE if policy set up successfully
 365          */
 366         bool (*bypass_socket)(kernel_interface_t *this, int fd, int family);
 367
 368         /**
 369          * Enable decapsulation of ESP-in-UDP packets for the given port/socket.
 370          *
 371          * @param fd                    socket file descriptor
 372          * @param family                protocol family of the socket
 373          * @param port                  the UDP port
 374          * @return                              TRUE if UDP decapsulation was enabled successfully
 375          */
 376         bool (*enable_udp_decap)(kernel_interface_t *this, int fd, int family,
 377                                                          u_int16_t port);
 378
 379
 380         /**
 381          * manager methods
 382          */
 383
 384         /**
 385          * Tries to find an ip address of a local interface that is included in the
 386          * supplied traffic selector.
 387          *
 388          * @param ts                    traffic selector
 389          * @param ip                    returned ip (has to be destroyed)
 390          * @return                              SUCCESS if address found
 391          */
 392         status_t (*get_address_by_ts)(kernel_interface_t *this,
 393                                                                   traffic_selector_t *ts, host_t **ip);
 394
 395         /**
 396          * Register an ipsec kernel interface constructor on the manager.
 397          *
 398          * @param create                        constructor to register
 399          */
 400         void (*add_ipsec_interface)(kernel_interface_t *this,
 401                                                                 kernel_ipsec_constructor_t create);
 402
 403         /**
 404          * Unregister an ipsec kernel interface constructor.
 405          *
 406          * @param create                        constructor to unregister
 407          */
 408         void (*remove_ipsec_interface)(kernel_interface_t *this,
 409                                                                    kernel_ipsec_constructor_t create);
 410
 411         /**
 412          * Register a network kernel interface constructor on the manager.
 413          *
 414          * @param create                        constructor to register
 415          */
 416         void (*add_net_interface)(kernel_interface_t *this,
 417                                                           kernel_net_constructor_t create);
 418
 419         /**
 420          * Unregister a network kernel interface constructor.
 421          *
 422          * @param create                        constructor to unregister
 423          */
 424         void (*remove_net_interface)(kernel_interface_t *this,
 425                                                                  kernel_net_constructor_t create);
 426
 427         /**
 428          * Add a listener to the kernel interface.
 429          *
 430          * @param listener                      listener to add
 431          */
 432         void (*add_listener)(kernel_interface_t *this,
 433                                                  kernel_listener_t *listener);
 434
 435         /**
 436          * Remove a listener from the kernel interface.
 437          *
 438          * @param listener                      listener to remove
 439          */
 440         void (*remove_listener)(kernel_interface_t *this,
 441                                                         kernel_listener_t *listener);
 442
 443         /**
 444          * Raise an acquire event.
 445          *
 446          * @param reqid                 reqid of the policy to acquire
 447          * @param src_ts                source traffic selector
 448          * @param dst_ts                destination traffic selector
 449          */
 450         void (*acquire)(kernel_interface_t *this, u_int32_t reqid,
 451                                         traffic_selector_t *src_ts, traffic_selector_t *dst_ts);
 452
 453         /**
 454          * Raise an expire event.
 455          *
 456          * @param reqid                 reqid of the expired SA
 457          * @param protocol              protocol of the expired SA
 458          * @param spi                   spi of the expired SA
 459          * @param hard                  TRUE if it is a hard expire, FALSE otherwise
 460          */
 461         void (*expire)(kernel_interface_t *this, u_int32_t reqid,
 462                                    u_int8_t protocol, u_int32_t spi, bool hard);
 463
 464         /**
 465          * Raise a mapping event.
 466          *
 467          * @param reqid                 reqid of the SA
 468          * @param spi                   spi of the SA
 469          * @param remote                new remote host
 470          */
 471         void (*mapping)(kernel_interface_t *this, u_int32_t reqid, u_int32_t spi,
 472                                         host_t *remote);
 473
 474         /**
 475          * Raise a migrate event.
 476          *
 477          * @param reqid                 reqid of the policy
 478          * @param src_ts                source traffic selector
 479          * @param dst_ts                destination traffic selector
 480          * @param direction             direction of the policy (in|out)
 481          * @param local                 local host address to be used in the IKE_SA
 482          * @param remote                remote host address to be used in the IKE_SA
 483          */
 484         void (*migrate)(kernel_interface_t *this, u_int32_t reqid,
 485                                         traffic_selector_t *src_ts, traffic_selector_t *dst_ts,
 486                                         policy_dir_t direction, host_t *local, host_t *remote);
 487
 488         /**
 489          * Raise a roam event.
 490          *
 491          * @param address               TRUE if address list, FALSE if routing changed
 492          */
 493         void (*roam)(kernel_interface_t *this, bool address);
 494
 495         /**
 496          * Destroys a kernel_interface_manager_t object.
 497          */
 498         void (*destroy) (kernel_interface_t *this);
 499 };
 500
 501 /**
 502  * Creates an object of type kernel_interface_t.
 503  */
 504 kernel_interface_t *kernel_interface_create(void);
 505
 506 #endif /** KERNEL_INTERFACE_H_ @}*/