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  * Copyright (c) 2012 Nanoteq Pty Ltd
  21  *
  22  * Permission is hereby granted, free of charge, to any person obtaining a copy
  23  * of this software and associated documentation files (the "Software"), to deal
  24  * in the Software without restriction, including without limitation the rights
  25  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  26  * copies of the Software, and to permit persons to whom the Software is
  27  * furnished to do so, subject to the following conditions:
  28  *
  29  * The above copyright notice and this permission notice shall be included in
  30  * all copies or substantial portions of the Software.
  31  *
  32  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  33  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  34  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  35  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  36  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  37  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  38  * THE SOFTWARE.
  39  */
  40
  41 /**
  42  * @defgroup kernel_interface kernel_interface
  43  * @{ @ingroup hkernel
  44  */
  45
  46 #ifndef KERNEL_INTERFACE_H_
  47 #define KERNEL_INTERFACE_H_
  48
  49 typedef struct kernel_interface_t kernel_interface_t;
  50 typedef enum kernel_feature_t kernel_feature_t;
  51
  52 #include <networking/host.h>
  53 #include <crypto/prf_plus.h>
  54
  55 #include <kernel/kernel_listener.h>
  56 #include <kernel/kernel_ipsec.h>
  57 #include <kernel/kernel_net.h>
  58
  59 /**
  60  * Bitfield of optional features a kernel backend supports.
  61  *
  62  * This feature-set is for both, kernel_ipsec_t and kernel_net_t. Each
  63  * backend returns a subset of these features.
  64  */
  65 enum kernel_feature_t {
  66         /** IPsec can process ESPv3 (RFC 4303) TFC padded packets */
  67         KERNEL_ESP_V3_TFC = (1<<0),
  68 };
  69
  70 /**
  71  * Constructor function for ipsec kernel interface
  72  */
  73 typedef kernel_ipsec_t* (*kernel_ipsec_constructor_t)(void);
  74
  75 /**
  76  * Constructor function for network kernel interface
  77  */
  78 typedef kernel_net_t* (*kernel_net_constructor_t)(void);
  79
  80 /**
  81  * Manager and wrapper for different kernel interfaces.
  82  *
  83  * The kernel interface handles the communication with the kernel
  84  * for SA and policy management and interface and IP address management.
  85  */
  86 struct kernel_interface_t {
  87
  88         /**
  89          * Get the feature set supported by the net and ipsec kernel backends.
  90          *
  91          * @return                              ORed feature-set of backends
  92          */
  93         kernel_feature_t (*get_features)(kernel_interface_t *this);
  94
  95         /**
  96          * Get a SPI from the kernel.
  97          *
  98          * @param src           source address of SA
  99          * @param dst           destination address of SA
 100          * @param protocol      protocol for SA (ESP/AH)
 101          * @param reqid         unique ID for this SA
 102          * @param spi           allocated spi
 103          * @return                              SUCCESS if operation completed
 104          */
 105         status_t (*get_spi)(kernel_interface_t *this, host_t *src, host_t *dst,
 106                                                 u_int8_t protocol, u_int32_t reqid, u_int32_t *spi);
 107
 108         /**
 109          * Get a Compression Parameter Index (CPI) from the kernel.
 110          *
 111          * @param src           source address of SA
 112          * @param dst           destination address of SA
 113          * @param reqid         unique ID for the corresponding SA
 114          * @param cpi           allocated cpi
 115          * @return                              SUCCESS if operation completed
 116          */
 117         status_t (*get_cpi)(kernel_interface_t *this, host_t *src, host_t *dst,
 118                                                 u_int32_t reqid, u_int16_t *cpi);
 119
 120         /**
 121          * Add an SA to the SAD.
 122          *
 123          * add_sa() may update an already allocated
 124          * SPI (via get_spi). In this case, the replace
 125          * flag must be set.
 126          * This function does install a single SA for a
 127          * single protocol in one direction.
 128          *
 129          * @param src                   source address for this SA
 130          * @param dst                   destination address for this SA
 131          * @param spi                   SPI allocated by us or remote peer
 132          * @param protocol              protocol for this SA (ESP/AH)
 133          * @param reqid                 unique ID for this SA
 134          * @param mark                  optional mark for this SA
 135          * @param tfc                   Traffic Flow Confidentiality padding for this SA
 136          * @param lifetime              lifetime_cfg_t for this SA
 137          * @param enc_alg               Algorithm to use for encryption (ESP only)
 138          * @param enc_key               key to use for encryption
 139          * @param int_alg               Algorithm to use for integrity protection
 140          * @param int_key               key to use for integrity protection
 141          * @param mode                  mode of the SA (tunnel, transport)
 142          * @param ipcomp                IPComp transform to use
 143          * @param cpi                   CPI for IPComp
 144          * @param encap                 enable UDP encapsulation for NAT traversal
 145          * @param esn                   TRUE to use Extended Sequence Numbers
 146          * @param inbound               TRUE if this is an inbound SA
 147          * @param src_ts                traffic selector with BEET source address
 148          * @param dst_ts                traffic selector with BEET destination address
 149          * @return                              SUCCESS if operation completed
 150          */
 151         status_t (*add_sa) (kernel_interface_t *this,
 152                                                 host_t *src, host_t *dst, u_int32_t spi,
 153                                                 u_int8_t protocol, u_int32_t reqid, mark_t mark,
 154                                                 u_int32_t tfc, lifetime_cfg_t *lifetime,
 155                                                 u_int16_t enc_alg, chunk_t enc_key,
 156                                                 u_int16_t int_alg, chunk_t int_key,
 157                                                 ipsec_mode_t mode, u_int16_t ipcomp, u_int16_t cpi,
 158                                                 bool encap, bool esn, bool inbound,
 159                                                 traffic_selector_t *src_ts, traffic_selector_t *dst_ts);
 160
 161         /**
 162          * Update the hosts on an installed SA.
 163          *
 164          * We cannot directly update the destination address as the kernel
 165          * requires the spi, the protocol AND the destination address (and family)
 166          * to identify SAs. Therefore if the destination address changed we
 167          * create a new SA and delete the old one.
 168          *
 169          * @param spi                   SPI of the SA
 170          * @param protocol              protocol for this SA (ESP/AH)
 171          * @param cpi                   CPI for IPComp, 0 if no IPComp is used
 172          * @param src                   current source address
 173          * @param dst                   current destination address
 174          * @param new_src               new source address
 175          * @param new_dst               new destination address
 176          * @param encap                 current use of UDP encapsulation
 177          * @param new_encap             new use of UDP encapsulation
 178          * @param mark                  optional mark for this SA
 179          * @return                              SUCCESS if operation completed, NOT_SUPPORTED if
 180          *                                        the kernel interface can't update the SA
 181          */
 182         status_t (*update_sa)(kernel_interface_t *this,
 183                                                   u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 184                                                   host_t *src, host_t *dst,
 185                                                   host_t *new_src, host_t *new_dst,
 186                                                   bool encap, bool new_encap, mark_t mark);
 187
 188         /**
 189          * Query the number of bytes processed by an SA from the SAD.
 190          *
 191          * @param src                   source address for this SA
 192          * @param dst                   destination address for this SA
 193          * @param spi                   SPI allocated by us or remote peer
 194          * @param protocol              protocol for this SA (ESP/AH)
 195          * @param mark                  optional mark for this SA
 196          * @param[out] bytes    the number of bytes processed by SA
 197          * @param[out] packets  number of packets processed by SA
 198          * @return                              SUCCESS if operation completed
 199          */
 200         status_t (*query_sa) (kernel_interface_t *this, host_t *src, host_t *dst,
 201                                                   u_int32_t spi, u_int8_t protocol, mark_t mark,
 202                                                   u_int64_t *bytes, u_int64_t *packets);
 203
 204         /**
 205          * Delete a previously installed SA from the SAD.
 206          *
 207          * @param src                   source address for this SA
 208          * @param dst                   destination address for this SA
 209          * @param spi                   SPI allocated by us or remote peer
 210          * @param protocol              protocol for this SA (ESP/AH)
 211          * @param cpi                   CPI for IPComp or 0
 212          * @param mark                  optional mark for this SA
 213          * @return                              SUCCESS if operation completed
 214          */
 215         status_t (*del_sa) (kernel_interface_t *this, host_t *src, host_t *dst,
 216                                                 u_int32_t spi, u_int8_t protocol, u_int16_t cpi,
 217                                                 mark_t mark);
 218
 219         /**
 220          * Flush all SAs from the SAD.
 221          *
 222          * @return                              SUCCESS if operation completed
 223          */
 224         status_t (*flush_sas) (kernel_interface_t *this);
 225
 226         /**
 227          * Add a policy to the SPD.
 228          *
 229          * A policy is always associated to an SA. Traffic which matches a
 230          * policy is handled by the SA with the same reqid.
 231          *
 232          * @param src                   source address of SA
 233          * @param dst                   dest address of SA
 234          * @param src_ts                traffic selector to match traffic source
 235          * @param dst_ts                traffic selector to match traffic dest
 236          * @param direction             direction of traffic, POLICY_(IN|OUT|FWD)
 237          * @param type                  type of policy, POLICY_(IPSEC|PASS|DROP)
 238          * @param sa                    details about the SA(s) tied to this policy
 239          * @param mark                  mark for this policy
 240          * @param priority              priority of this policy
 241          * @return                              SUCCESS if operation completed
 242          */
 243         status_t (*add_policy) (kernel_interface_t *this,
 244                                                         host_t *src, host_t *dst,
 245                                                         traffic_selector_t *src_ts,
 246                                                         traffic_selector_t *dst_ts,
 247                                                         policy_dir_t direction, policy_type_t type,
 248                                                         ipsec_sa_cfg_t *sa, mark_t mark,
 249                                                         policy_priority_t priority);
 250
 251         /**
 252          * Query the use time of a policy.
 253          *
 254          * The use time of a policy is the time the policy was used
 255          * for the last time.
 256          *
 257          * @param src_ts                traffic selector to match traffic source
 258          * @param dst_ts                traffic selector to match traffic dest
 259          * @param direction             direction of traffic, POLICY_(IN|OUT|FWD)
 260          * @param mark                  optional mark
 261          * @param[out] use_time the time of this SA's last use
 262          * @return                              SUCCESS if operation completed
 263          */
 264         status_t (*query_policy) (kernel_interface_t *this,
 265                                                           traffic_selector_t *src_ts,
 266                                                           traffic_selector_t *dst_ts,
 267                                                           policy_dir_t direction, mark_t mark,
 268                                                           u_int32_t *use_time);
 269
 270         /**
 271          * Remove a policy from the SPD.
 272          *
 273          * The kernel interface implements reference counting for policies.
 274          * If the same policy is installed multiple times (in the case of rekeying),
 275          * the reference counter is increased. del_policy() decreases the ref counter
 276          * and removes the policy only when no more references are available.
 277          *
 278          * @param src_ts                traffic selector to match traffic source
 279          * @param dst_ts                traffic selector to match traffic dest
 280          * @param direction             direction of traffic, POLICY_(IN|OUT|FWD)
 281          * @param reqid                 unique ID of the associated SA
 282          * @param mark                  optional mark
 283          * @param priority              priority of the policy
 284          * @return                              SUCCESS if operation completed
 285          */
 286         status_t (*del_policy) (kernel_interface_t *this,
 287                                                         traffic_selector_t *src_ts,
 288                                                         traffic_selector_t *dst_ts,
 289                                                         policy_dir_t direction, u_int32_t reqid,
 290                                                         mark_t mark, policy_priority_t priority);
 291
 292         /**
 293          * Flush all policies from the SPD.
 294          *
 295          * @return                              SUCCESS if operation completed
 296          */
 297         status_t (*flush_policies) (kernel_interface_t *this);
 298
 299         /**
 300          * Get our outgoing source address for a destination.
 301          *
 302          * Does a route lookup to get the source address used to reach dest.
 303          * The returned host is allocated and must be destroyed.
 304          * An optional src address can be used to check if a route is available
 305          * for the given source to dest.
 306          *
 307          * @param dest                  target destination address
 308          * @param src                   source address to check, or NULL
 309          * @return                              outgoing source address, NULL if unreachable
 310          */
 311         host_t* (*get_source_addr)(kernel_interface_t *this,
 312                                                            host_t *dest, host_t *src);
 313
 314         /**
 315          * Get the next hop for a destination.
 316          *
 317          * Does a route lookup to get the next hop used to reach dest.
 318          * The returned host is allocated and must be destroyed.
 319          * An optional src address can be used to check if a route is available
 320          * for the given source to dest.
 321          *
 322          * @param dest                  target destination address
 323          * @return                              next hop address, NULL if unreachable
 324          */
 325         host_t* (*get_nexthop)(kernel_interface_t *this, host_t *dest, host_t *src);
 326
 327         /**
 328          * Get the interface name of a local address. Interfaces that are down or
 329          * ignored by config are not considered.
 330          *
 331          * @param host                  address to get interface name from
 332          * @param name                  allocated interface name (optional)
 333          * @return                              TRUE if interface found and usable
 334          */
 335         bool (*get_interface)(kernel_interface_t *this, host_t *host, char **name);
 336
 337         /**
 338          * Creates an enumerator over all local addresses.
 339          *
 340          * This function blocks an internal cached address list until the
 341          * enumerator gets destroyed.
 342          * The hosts are read-only, do not modify of free.
 343          *
 344          * @param which                 a combination of address types to enumerate
 345          * @return                              enumerator over host_t's
 346          */
 347         enumerator_t *(*create_address_enumerator) (kernel_interface_t *this,
 348                                                                                                 kernel_address_type_t which);
 349
 350         /**
 351          * Add a virtual IP to an interface.
 352          *
 353          * Virtual IPs are attached to an interface. If an IP is added multiple
 354          * times, the IP is refcounted and not removed until del_ip() was called
 355          * as many times as add_ip().
 356          *
 357          * @param virtual_ip    virtual ip address to assign
 358          * @param prefix                prefix length to install IP with, -1 for auto
 359          * @param iface                 interface to install virtual IP on
 360          * @return                              SUCCESS if operation completed
 361          */
 362         status_t (*add_ip) (kernel_interface_t *this, host_t *virtual_ip, int prefix,
 363                                                 char *iface);
 364
 365         /**
 366          * Remove a virtual IP from an interface.
 367          *
 368          * The kernel interface uses refcounting, see add_ip().
 369          *
 370          * @param virtual_ip    virtual ip address to assign
 371          * @param prefix                prefix length of the IP to uninstall, -1 for auto
 372          * @param wait                  TRUE to wait untily IP is gone
 373          * @return                              SUCCESS if operation completed
 374          */
 375         status_t (*del_ip) (kernel_interface_t *this, host_t *virtual_ip,
 376                                                 int prefix, bool wait);
 377
 378         /**
 379          * Add a route.
 380          *
 381          * @param dst_net               destination net
 382          * @param prefixlen             destination net prefix length
 383          * @param gateway               gateway for this route
 384          * @param src_ip                sourc ip of the route
 385          * @param if_name               name of the interface the route is bound to
 386          * @return                              SUCCESS if operation completed
 387          *                                              ALREADY_DONE if the route already exists
 388          */
 389         status_t (*add_route) (kernel_interface_t *this, chunk_t dst_net,
 390                                                    u_int8_t prefixlen, host_t *gateway, host_t *src_ip,
 391                                                    char *if_name);
 392
 393         /**
 394          * Delete a route.
 395          *
 396          * @param dst_net               destination net
 397          * @param prefixlen             destination net prefix length
 398          * @param gateway               gateway for this route
 399          * @param src_ip                sourc ip of the route
 400          * @param if_name               name of the interface the route is bound to
 401          * @return                              SUCCESS if operation completed
 402          */
 403         status_t (*del_route) (kernel_interface_t *this, chunk_t dst_net,
 404                                                    u_int8_t prefixlen, host_t *gateway, host_t *src_ip,
 405                                                    char *if_name);
 406
 407         /**
 408          * Set up a bypass policy for a given socket.
 409          *
 410          * @param fd                    socket file descriptor to setup policy for
 411          * @param family                protocol family of the socket
 412          * @return                              TRUE if policy set up successfully
 413          */
 414         bool (*bypass_socket)(kernel_interface_t *this, int fd, int family);
 415
 416         /**
 417          * Enable decapsulation of ESP-in-UDP packets for the given port/socket.
 418          *
 419          * @param fd                    socket file descriptor
 420          * @param family                protocol family of the socket
 421          * @param port                  the UDP port
 422          * @return                              TRUE if UDP decapsulation was enabled successfully
 423          */
 424         bool (*enable_udp_decap)(kernel_interface_t *this, int fd, int family,
 425                                                          u_int16_t port);
 426
 427
 428         /**
 429          * manager methods
 430          */
 431
 432         /**
 433          * Verifies that the given interface is usable and not excluded by
 434          * configuration.
 435          *
 436          * @param iface                 interface name
 437          * @return                              TRUE if usable
 438          */
 439         bool (*is_interface_usable)(kernel_interface_t *this, const char *iface);
 440
 441         /**
 442          * Check if interfaces are excluded by config.
 443          *
 444          * @return                              TRUE if no interfaces are exclued by config
 445          */
 446         bool (*all_interfaces_usable)(kernel_interface_t *this);
 447
 448         /**
 449          * Tries to find an IP address of a local interface that is included in the
 450          * supplied traffic selector.
 451          *
 452          * @param ts                    traffic selector
 453          * @param ip                    returned IP address (has to be destroyed)
 454          * @param vip                   set to TRUE if returned address is a virtual IP
 455          * @return                              SUCCESS if address found
 456          */
 457         status_t (*get_address_by_ts)(kernel_interface_t *this,
 458                                                                   traffic_selector_t *ts, host_t **ip, bool *vip);
 459
 460         /**
 461          * Register an ipsec kernel interface constructor on the manager.
 462          *
 463          * @param create                        constructor to register
 464          */
 465         void (*add_ipsec_interface)(kernel_interface_t *this,
 466                                                                 kernel_ipsec_constructor_t create);
 467
 468         /**
 469          * Unregister an ipsec kernel interface constructor.
 470          *
 471          * @param create                        constructor to unregister
 472          */
 473         void (*remove_ipsec_interface)(kernel_interface_t *this,
 474                                                                    kernel_ipsec_constructor_t create);
 475
 476         /**
 477          * Register a network kernel interface constructor on the manager.
 478          *
 479          * @param create                        constructor to register
 480          */
 481         void (*add_net_interface)(kernel_interface_t *this,
 482                                                           kernel_net_constructor_t create);
 483
 484         /**
 485          * Unregister a network kernel interface constructor.
 486          *
 487          * @param create                        constructor to unregister
 488          */
 489         void (*remove_net_interface)(kernel_interface_t *this,
 490                                                                  kernel_net_constructor_t create);
 491
 492         /**
 493          * Add a listener to the kernel interface.
 494          *
 495          * @param listener                      listener to add
 496          */
 497         void (*add_listener)(kernel_interface_t *this,
 498                                                  kernel_listener_t *listener);
 499
 500         /**
 501          * Remove a listener from the kernel interface.
 502          *
 503          * @param listener                      listener to remove
 504          */
 505         void (*remove_listener)(kernel_interface_t *this,
 506                                                         kernel_listener_t *listener);
 507
 508         /**
 509          * Raise an acquire event.
 510          *
 511          * @param reqid                 reqid of the policy to acquire
 512          * @param src_ts                source traffic selector
 513          * @param dst_ts                destination traffic selector
 514          */
 515         void (*acquire)(kernel_interface_t *this, u_int32_t reqid,
 516                                         traffic_selector_t *src_ts, traffic_selector_t *dst_ts);
 517
 518         /**
 519          * Raise an expire event.
 520          *
 521          * @param reqid                 reqid of the expired SA
 522          * @param protocol              protocol of the expired SA
 523          * @param spi                   spi of the expired SA
 524          * @param hard                  TRUE if it is a hard expire, FALSE otherwise
 525          */
 526         void (*expire)(kernel_interface_t *this, u_int32_t reqid,
 527                                    u_int8_t protocol, u_int32_t spi, bool hard);
 528
 529         /**
 530          * Raise a mapping event.
 531          *
 532          * @param reqid                 reqid of the SA
 533          * @param spi                   spi of the SA
 534          * @param remote                new remote host
 535          */
 536         void (*mapping)(kernel_interface_t *this, u_int32_t reqid, u_int32_t spi,
 537                                         host_t *remote);
 538
 539         /**
 540          * Raise a migrate event.
 541          *
 542          * @param reqid                 reqid of the policy
 543          * @param src_ts                source traffic selector
 544          * @param dst_ts                destination traffic selector
 545          * @param direction             direction of the policy (in|out)
 546          * @param local                 local host address to be used in the IKE_SA
 547          * @param remote                remote host address to be used in the IKE_SA
 548          */
 549         void (*migrate)(kernel_interface_t *this, u_int32_t reqid,
 550                                         traffic_selector_t *src_ts, traffic_selector_t *dst_ts,
 551                                         policy_dir_t direction, host_t *local, host_t *remote);
 552
 553         /**
 554          * Raise a roam event.
 555          *
 556          * @param address               TRUE if address list, FALSE if routing changed
 557          */
 558         void (*roam)(kernel_interface_t *this, bool address);
 559
 560         /**
 561          * Register a new algorithm with the kernel interface.
 562          *
 563          * @param alg_id                        the IKE id of the algorithm
 564          * @param type                          the transform type of the algorithm
 565          * @param kernel_id                     the kernel id of the algorithm
 566          * @param kernel_name           the kernel name of the algorithm
 567          */
 568         void (*register_algorithm)(kernel_interface_t *this, u_int16_t alg_id,
 569                                                            transform_type_t type, u_int16_t kernel_id,
 570                                                            char *kernel_name);
 571
 572         /**
 573          * Return the kernel-specific id and/or name for an algorithms depending on
 574          * the arguments specified.
 575          *
 576          * @param alg_id                        the IKE id of the algorithm
 577          * @param type                          the transform type of the algorithm
 578          * @param kernel_id                     the kernel id of the algorithm (optional)
 579          * @param kernel_name           the kernel name of the algorithm (optional)
 580          * @return                                      TRUE if algorithm was found
 581          */
 582         bool (*lookup_algorithm)(kernel_interface_t *this, u_int16_t alg_id,
 583                                                          transform_type_t type, u_int16_t *kernel_id,
 584                                                          char **kernel_name);
 585
 586         /**
 587          * Destroys a kernel_interface_manager_t object.
 588          */
 589         void (*destroy) (kernel_interface_t *this);
 590 };
 591
 592 /**
 593  * Creates an object of type kernel_interface_t.
 594  */
 595 kernel_interface_t *kernel_interface_create(void);
 596
 597 #endif /** KERNEL_INTERFACE_H_ @}*/