programs/charon/charon/config/traffic_selector.h

   1 /**
   2  * @file traffic_selector.h
   3  *
   4  * @brief Interface of traffic_selector_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef TRAFFIC_SELECTOR_H_
  24 #define TRAFFIC_SELECTOR_H_
  25
  26 #include <types.h>
  27 #include <utils/host.h>
  28
  29 typedef enum ts_type_t ts_type_t;
  30
  31 /**
  32  * Traffic selector types.
  33  *
  34  * @ingroup config
  35  */
  36 enum ts_type_t {
  37
  38         /**
  39          * A range of IPv4 addresses, represented by two four (4) octet
  40      * values.  The first value is the beginning IPv4 address
  41      * (inclusive) and the second value is the ending IPv4 address
  42      * (inclusive). All addresses falling between the two specified
  43      * addresses are considered to be within the list.
  44      */
  45         TS_IPV4_ADDR_RANGE = 7,
  46
  47         /**
  48          * A range of IPv6 addresses, represented by two sixteen (16)
  49      * octet values.  The first value is the beginning IPv6 address
  50      * (inclusive) and the second value is the ending IPv6 address
  51      * (inclusive). All addresses falling between the two specified
  52      *  addresses are considered to be within the list.
  53          */
  54         TS_IPV6_ADDR_RANGE = 8
  55 };
  56
  57 /**
  58  * string mappings for ts_type_t
  59  */
  60 extern mapping_t ts_type_m[];
  61
  62
  63 typedef struct traffic_selector_t traffic_selector_t;
  64
  65 /**
  66  * @brief Object representing a traffic selector entry.
  67  *
  68  * A traffic selector defines an range of addresses
  69  * and a range of ports. IPv6 is not fully supported yet.
  70  *
  71  * @b Constructors:
  72  * - traffic_selector_create_from_bytes()
  73  * - traffic_selector_create_from_string()
  74  *
  75  * @todo Add IPv6 support
  76  *
  77  * @ingroup config
  78  */
  79 struct traffic_selector_t {
  80
  81         /**
  82          * @brief Compare two traffic selectors, and create a new one
  83          * which is the largest subset of both (subnet & port).
  84          *
  85          * Resulting traffic_selector is newly created and must be destroyed.
  86          *
  87          * @param this          first to compare
  88          * @param other         second to compare
  89          * @return
  90          *                                      - created subset of them
  91          *                                      - or NULL if no match between this and other
  92          */
  93         traffic_selector_t *(*get_subset) (traffic_selector_t *this, traffic_selector_t *other);
  94
  95         /**
  96          * @brief Clone a traffic selector.
  97          *
  98          * @param this          traffic selector to clone
  99          * @return                      clone of it
 100          */
 101         traffic_selector_t *(*clone) (traffic_selector_t *this);
 102
 103         /**
 104          * @brief Get starting address of this ts as a chunk.
 105          *
 106          * Data is in network order and represents the address.
 107          * Size depends on protocol.
 108          *
 109          * Resulting chunk data is allocated and must be freed!
 110          *
 111          * @param this          calling object
 112          * @return                      chunk containing the address
 113          */
 114         chunk_t (*get_from_address) (traffic_selector_t *this);
 115
 116         /**
 117          * @brief Get ending address of this ts as a chunk.
 118          *
 119          * Data is in network order and represents the address.
 120          * Size depends on protocol.
 121          *
 122          * Resulting chunk data is allocated and must be freed!
 123          *
 124          * @param this          calling object
 125          * @return                      chunk containing the address
 126          */
 127         chunk_t (*get_to_address) (traffic_selector_t *this);
 128
 129         /**
 130          * @brief Get starting port of this ts.
 131          *
 132          * Port is in host order, since the parser converts it.
 133          * Size depends on protocol.
 134          *
 135          * @param this          calling object
 136          * @return                      port
 137          */
 138         u_int16_t (*get_from_port) (traffic_selector_t *this);
 139
 140         /**
 141          * @brief Get ending port of this ts.
 142          *
 143          * Port is in host order, since the parser converts it.
 144          * Size depends on protocol.
 145          *
 146          * @param this          calling object
 147          * @return                      port
 148          */
 149         u_int16_t (*get_to_port) (traffic_selector_t *this);
 150
 151         /**
 152          * @brief Get the type of the traffic selector.
 153          *
 154          * @param this          calling obect
 155          * @return                      ts_type_t specifying the type
 156          */
 157         ts_type_t (*get_type) (traffic_selector_t *this);
 158
 159         /**
 160          * @brief Get the protocol id of this ts.
 161          *
 162          * @param this          calling obect
 163          * @return                      protocol id
 164          */
 165         u_int8_t (*get_protocol) (traffic_selector_t *this);
 166
 167         /**
 168          * @brief Get the netmask of the address range.
 169          *
 170          * Returns the number of bits associated to the subnet.
 171          * (As the "24" in "192.168.0.0/24"). This is approximated
 172          * if the address range is not a complete subnet! Since Linux
 173          * does not support full IP address ranges (yet), we can't do this
 174          * (much) better.
 175          *
 176          * @param this          calling obect
 177          * @return                      netmask as "bits for subnet"
 178          */
 179         u_int8_t (*get_netmask) (traffic_selector_t *this);
 180
 181         /**
 182          * @brief Update the address of a traffic selector.
 183          *
 184          * Update the address range of a traffic selector,
 185          * if the current address is 0.0.0.0. The new address range
 186          * starts from the supplied address and also ends there
 187          * (which means it is a one-host-address-range ;-).
 188          *
 189          * @param this          calling obect
 190          * @param host          host_t specifying the address range
 191          */
 192         void (*update_address_range) (traffic_selector_t *this, host_t* host);
 193
 194         /**
 195          * @brief Destroys the ts object
 196          *
 197          * @param this          calling object
 198          */
 199         void (*destroy) (traffic_selector_t *this);
 200 };
 201
 202 /**
 203  * @brief Create a new traffic selector using human readable params.
 204  *
 205  * @param protocol              protocol for this ts, such as TCP or UDP
 206  * @param type                  type of following addresses, such as TS_IPV4_ADDR_RANGE
 207  * @param from_addr             start of address range as string
 208  * @param from_port             port number in host order
 209  * @param to_addr               end of address range as string
 210  * @param to_port               port number in host order
 211  * @return
 212  *                                              - traffic_selector_t object
 213  *                                              - NULL if invalid address strings/protocol
 214  *
 215  * @ingroup config
 216  */
 217 traffic_selector_t *traffic_selector_create_from_string(u_int8_t protocol, ts_type_t type, char *from_addr, u_int16_t from_port, char *to_addr, u_int16_t to_port);
 218
 219 /**
 220  * @brief Create a new traffic selector using data read from the net.
 221  *
 222  * There exists a mix of network and host order in the params.
 223  * But the parser gives us this data in this format, so we
 224  * don't have to convert twice.
 225  *
 226  * @param protocol              protocol for this ts, such as TCP or UDP
 227  * @param type                  type of following addresses, such as TS_IPV4_ADDR_RANGE
 228  * @param from_address  start of address range, network order
 229  * @param from_port             port number, host order
 230  * @param to_address    end of address range as string, network
 231  * @param to_port               port number, host order
 232  * @return
 233  *                                              - traffic_selector_t object
 234  *                                              - NULL if invalid address input/protocol
 235  *
 236  * @ingroup config
 237  */
 238 traffic_selector_t *traffic_selector_create_from_bytes(u_int8_t protocol, ts_type_t type, chunk_t from_address, int16_t from_port, chunk_t to_address, u_int16_t to_port);
 239
 240 /**
 241  * @brief Create a new traffic selector defining a whole subnet.
 242  *
 243  * In most cases, definition of a traffic selector for full subnets
 244  * is sufficient. This constructor creates a traffic selector for
 245  * all protocols, all ports and the address range specified by the
 246  * subnet.
 247  *
 248  * @param net                   subnet to use
 249  * @param netbits               size of the subnet, as used in e.g. 192.168.0.0/24 notation
 250  * @return
 251  *                                              - traffic_selector_t object
 252  *                                              - NULL if address family of net not supported
 253  *
 254  * @ingroup config
 255  */
 256 traffic_selector_t *traffic_selector_create_from_subnet(host_t *net, u_int8_t netbits);
 257
 258 #endif /* TRAFFIC_SELECTOR_H_ */