src/libcharon/config/child_cfg.h

   1 /*
   2  * Copyright (C) 2008-2019 Tobias Brunner
   3  * Copyright (C) 2016 Andreas Steffen
   4  * Copyright (C) 2005-2007 Martin Willi
   5  * Copyright (C) 2005 Jan Hutter
   6  *
   7  * Copyright (C) secunet Security Networks AG
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU General Public License as published by the
  11  * Free Software Foundation; either version 2 of the License, or (at your
  12  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  13  *
  14  * This program is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  16  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17  * for more details.
  18  */
  19
  20 /**
  21  * @defgroup child_cfg child_cfg
  22  * @{ @ingroup config
  23  */
  24
  25 #ifndef CHILD_CFG_H_
  26 #define CHILD_CFG_H_
  27
  28 typedef enum action_t action_t;
  29 typedef enum child_cfg_option_t child_cfg_option_t;
  30 typedef struct child_cfg_t child_cfg_t;
  31 typedef struct child_cfg_create_t child_cfg_create_t;
  32
  33 #include <library.h>
  34 #include <selectors/traffic_selector.h>
  35 #include <crypto/proposal/proposal.h>
  36 #include <kernel/kernel_ipsec.h>
  37
  38 /**
  39  * Action to take when connection is loaded, DPD is detected or
  40  * connection gets closed by peer.
  41  */
  42 enum action_t {
  43         /** No action */
  44         ACTION_NONE = 0,
  45         /** Install trap policy to (re-)establish on demand */
  46         ACTION_TRAP = (1<<0),
  47         /** Start or restart immediately */
  48         ACTION_START = (1<<1),
  49 };
  50
  51 /**
  52  * enum names for action_t.
  53  */
  54 extern enum_name_t *action_names;
  55
  56 /**
  57  * A child_cfg_t defines the config template for a CHILD_SA.
  58  *
  59  * After creation, proposals and traffic selectors may be added to the config.
  60  * A child_cfg object is referenced multiple times, and is not thread save.
  61  * Reading from the object is save, adding things is not allowed while other
  62  * threads may access the object.
  63  * A reference counter handles the number of references hold to this config.
  64  *
  65  * @see peer_cfg_t to get an overview over the configurations.
  66  */
  67 struct child_cfg_t {
  68
  69         /**
  70          * Get the name of the child_cfg.
  71          *
  72          * @return                              child_cfg's name
  73          */
  74         char *(*get_name) (child_cfg_t *this);
  75
  76         /**
  77          * Add a proposal to the list.
  78          *
  79          * The proposals are stored by priority, first added
  80          * is the most preferred. It is safe to add NULL as proposal, which has no
  81          * effect. After add, proposal is owned by child_cfg.
  82          *
  83          * @param proposal              proposal to add, or NULL
  84          */
  85         void (*add_proposal) (child_cfg_t *this, proposal_t *proposal);
  86
  87         /**
  88          * Get the list of proposals for the CHILD_SA.
  89          *
  90          * Resulting list and all of its proposals must be freed after use.
  91          *
  92          * @param strip_ke              TRUE strip out key exchange methods
  93          * @return                              list of proposals
  94          */
  95         linked_list_t* (*get_proposals)(child_cfg_t *this, bool strip_ke);
  96
  97         /**
  98          * Select a proposal from a supplied list.
  99          *
 100          * Returned proposal is newly created and must be destroyed after usage.
 101          *
 102          * @param proposals             list from which proposals are selected
 103          * @param flags                 flags to consider during proposal selection
 104          * @return                              selected proposal, or NULL if nothing matches
 105          */
 106         proposal_t* (*select_proposal)(child_cfg_t*this, linked_list_t *proposals,
 107                                                                    proposal_selection_flag_t flags);
 108
 109         /**
 110          * Add a traffic selector to the config.
 111          *
 112          * Use the "local" parameter to add it for the local or the remote side.
 113          * After add, traffic selector is owned by child_cfg.
 114          *
 115          * @param local                 TRUE for local side, FALSE for remote
 116          * @param ts                    traffic_selector to add
 117          */
 118         void (*add_traffic_selector)(child_cfg_t *this, bool local,
 119                                                                  traffic_selector_t *ts);
 120
 121         /**
 122          * Get a list of traffic selectors to use for the CHILD_SA.
 123          *
 124          * The config contains two set of traffic selectors, one for the local
 125          * side, one for the remote side.
 126          * If a list with traffic selectors is supplied, these are used to narrow
 127          * down the traffic selector list to the greatest common divisor.
 128          * Some traffic selector may be "dynamic", meaning they are narrowed down
 129          * to a specific address (host-to-host or virtual-IP setups). Use
 130          * the "host" parameter to narrow such traffic selectors to that address.
 131          * Resulted list and its traffic selectors must be destroyed after use.
 132          *
 133          * @param local                 TRUE for TS on local side, FALSE for remote
 134          * @param supplied              list with TS to select from, or NULL
 135          * @param hosts                 addresses to use for narrowing "dynamic" TS', host_t
 136          * @param log                   FALSE to avoid logging details about the selection
 137          * @return                              list containing the traffic selectors
 138          */
 139         linked_list_t *(*get_traffic_selectors)(child_cfg_t *this, bool local,
 140                                                                                         linked_list_t *supplied,
 141                                                                                         linked_list_t *hosts, bool log);
 142
 143         /**
 144          * Get the updown script to run for the CHILD_SA.
 145          *
 146          * @return                              path to updown script
 147          */
 148         char* (*get_updown)(child_cfg_t *this);
 149
 150         /**
 151          * Get the lifetime configuration of a CHILD_SA.
 152          *
 153          * The rekey limits automatically contain a jitter to avoid simultaneous
 154          * rekeying. These values will change with each call to this function.
 155          *
 156          * @param jitter                subtract jitter value to randomize lifetimes
 157          * @return                              lifetime_cfg_t (has to be freed)
 158          */
 159         lifetime_cfg_t* (*get_lifetime) (child_cfg_t *this, bool jitter);
 160
 161         /**
 162          * Get the mode to use for the CHILD_SA.
 163          *
 164          * The mode is either tunnel, transport or BEET. The peer must agree
 165          * on the method, fallback is tunnel mode.
 166          *
 167          * @return                              ipsec mode
 168          */
 169         ipsec_mode_t (*get_mode) (child_cfg_t *this);
 170
 171         /**
 172          * Action to take to start CHILD_SA.
 173          *
 174          * @return                              start action
 175          */
 176         action_t (*get_start_action) (child_cfg_t *this);
 177
 178         /**
 179          * Action to take on DPD.
 180          *
 181          * @return                              DPD action
 182          */
 183         action_t (*get_dpd_action) (child_cfg_t *this);
 184
 185         /**
 186          * Get the HW offload mode to use for the CHILD_SA.
 187          *
 188          * @return                              hw offload mode
 189          */
 190         hw_offload_t (*get_hw_offload) (child_cfg_t *this);
 191
 192         /**
 193          * Get the copy mode for the DS header field to use for the CHILD_SA.
 194          *
 195          * @return                              IP header copy mode
 196          */
 197         dscp_copy_t (*get_copy_dscp) (child_cfg_t *this);
 198
 199         /**
 200          * Action to take if CHILD_SA gets closed.
 201          *
 202          * @return                              close action
 203          */
 204         action_t (*get_close_action) (child_cfg_t *this);
 205
 206         /**
 207          * Get the first algorithm of a certain transform type that's contained in
 208          * any of the configured proposals.
 209          *
 210          * For instance, use with KEY_EXCHANGE_METHOD to get the KE method to use
 211          * for the CHILD_SA initiation.
 212          *
 213          * @param type                  transform type to look for
 214          * @return                              algorithm identifier (0 for none)
 215          */
 216         uint16_t (*get_algorithm)(child_cfg_t *this, transform_type_t type);
 217
 218         /**
 219          * Get the inactivity timeout value.
 220          *
 221          * @return                              inactivity timeout in s
 222          */
 223         uint32_t (*get_inactivity)(child_cfg_t *this);
 224
 225         /**
 226          * Specific reqid to use for CHILD_SA.
 227          *
 228          * @return                              reqid
 229          */
 230         uint32_t (*get_reqid)(child_cfg_t *this);
 231
 232         /**
 233          * Optional interface ID to set on policies/SAs.
 234          *
 235          * @param inbound               TRUE for inbound, FALSE for outbound
 236          * @return                              interface ID
 237          */
 238         uint32_t (*get_if_id)(child_cfg_t *this, bool inbound);
 239
 240         /**
 241          * Optional mark to set on policies/SAs.
 242          *
 243          * @param inbound               TRUE for inbound, FALSE for outbound
 244          * @return                              mark
 245          */
 246         mark_t (*get_mark)(child_cfg_t *this, bool inbound);
 247
 248         /**
 249          * Optional mark the SAs should apply after processing packets.
 250          *
 251          * @param inbound               TRUE for inbound, FALSE for outbound
 252          * @return                              mark
 253          */
 254         mark_t (*get_set_mark)(child_cfg_t *this, bool inbound);
 255
 256         /**
 257          * Optional security label to be configured on policies.
 258          *
 259          * @return                              label or NULL
 260          */
 261         sec_label_t *(*get_label)(child_cfg_t *this);
 262
 263         /**
 264          * Get the mode in which the security label is used.
 265          *
 266          * @return                              label mode (never SEC_LABEL_MODE_SYSTEM)
 267          */
 268         sec_label_mode_t (*get_label_mode)(child_cfg_t *this);
 269
 270         /**
 271          * Select a security label from the given list that matches the configured
 272          * label.
 273          *
 274          * This fails under the following conditions:
 275          * - a label is configured but no labels are provided
 276          * - no label is configured but at least one label is provided
 277          * - the configured and provided labels don't match
 278          *
 279          * If no label is configured and none are provided, that's considered a
 280          * success and label will be set to NULL.
 281          *
 282          * @param labels                list of labels to match
 283          * @param log                   FALSE to avoid logging details about the selection
 284          * @param[out] label    selected label or NULL if no label necessary
 285          * @param[out] exact    TRUE if there was an exact match
 286          * @return                              FALSE on failure
 287          */
 288         bool (*select_label)(child_cfg_t *this, linked_list_t *labels, bool log,
 289                                                  sec_label_t **label, bool *exact);
 290
 291         /**
 292          * Get the TFC padding value to use for CHILD_SA.
 293          *
 294          * @return                              TFC padding, 0 to disable, -1 for MTU
 295          */
 296         uint32_t (*get_tfc)(child_cfg_t *this);
 297
 298         /**
 299          * Get optional manually-set IPsec policy priority
 300          *
 301          * @return                              manually-set IPsec policy priority (automatic if 0)
 302          */
 303         uint32_t (*get_manual_prio)(child_cfg_t *this);
 304
 305         /**
 306          * Get optional network interface restricting IPsec policy
 307          *
 308          * @return                              network interface)
 309          */
 310         char* (*get_interface)(child_cfg_t *this);
 311
 312         /**
 313          * Get anti-replay window size
 314          *
 315          * @return                              anti-replay window size
 316          */
 317         uint32_t (*get_replay_window)(child_cfg_t *this);
 318
 319         /**
 320          * Set anti-replay window size
 321          *
 322          * @param window        anti-replay window size
 323          */
 324         void (*set_replay_window)(child_cfg_t *this, uint32_t window);
 325
 326         /**
 327          * Check if an option flag is set.
 328          *
 329          * @param option                option flag to check
 330          * @return                              TRUE if option flag set, FALSE otherwise
 331          */
 332         bool (*has_option)(child_cfg_t *this, child_cfg_option_t option);
 333
 334         /**
 335          * Check if two child_cfg objects are equal.
 336          *
 337          * @param other                 candidate to check for equality against this
 338          * @return                              TRUE if equal
 339          */
 340         bool (*equals)(child_cfg_t *this, child_cfg_t *other);
 341
 342         /**
 343          * Increase the reference count.
 344          *
 345          * @return                              reference to this
 346          */
 347         child_cfg_t* (*get_ref) (child_cfg_t *this);
 348
 349         /**
 350          * Destroys the child_cfg object.
 351          *
 352          * Decrements the internal reference counter and
 353          * destroys the child_cfg when it reaches zero.
 354          */
 355         void (*destroy) (child_cfg_t *this);
 356 };
 357
 358 /**
 359  * Option flags that may be set on a child_cfg_t object
 360  */
 361 enum child_cfg_option_t {
 362
 363         /** Use IPsec transport proxy mode */
 364         OPT_PROXY_MODE = (1<<0),
 365
 366         /** Use IPComp, if peer supports it */
 367         OPT_IPCOMP = (1<<1),
 368
 369         /** Allow access to the local host */
 370         OPT_HOSTACCESS = (1<<2),
 371
 372         /** Don't install any IPsec policies */
 373         OPT_NO_POLICIES = (1<<3),
 374
 375         /** Install outbound FWD IPsec policies to bypass drop policies */
 376         OPT_FWD_OUT_POLICIES = (1<<4),
 377
 378         /** Force 96-bit truncation for SHA-256 */
 379         OPT_SHA256_96 = (1<<5),
 380
 381         /** Set mark on inbound SAs */
 382         OPT_MARK_IN_SA = (1<<6),
 383
 384         /** Disable copying the DF bit to the outer IPv4 header in tunnel mode */
 385         OPT_NO_COPY_DF = (1<<7),
 386
 387         /** Disable copying the ECN header field in tunnel mode */
 388         OPT_NO_COPY_ECN = (1<<8),
 389
 390         /** Enable per-CPU CHILD_SAs */
 391         OPT_PER_CPU_SAS = (1<<9),
 392
 393         /** Enable UDP encapsulation for per-CPU CHILD_SAs */
 394         OPT_PER_CPU_SAS_ENCAP = (1<<10),
 395 };
 396
 397 /**
 398  * Data passed to the constructor of a child_cfg_t object.
 399  */
 400 struct child_cfg_create_t {
 401         /** Options set for CHILD_SA */
 402         child_cfg_option_t options;
 403         /** Specific reqid to use for CHILD_SA, 0 for auto assignment */
 404         uint32_t reqid;
 405         /** Optional inbound interface ID */
 406         uint32_t if_id_in;
 407         /** Optional outbound interface ID */
 408         uint32_t if_id_out;
 409         /** Optional inbound mark */
 410         mark_t mark_in;
 411         /** Optional outbound mark */
 412         mark_t mark_out;
 413         /** Optional inbound mark the SA should apply to traffic */
 414         mark_t set_mark_in;
 415         /** Optional outbound mark the SA should apply to traffic */
 416         mark_t set_mark_out;
 417         /** Optional security label configured on policies (cloned) */
 418         sec_label_t *label;
 419         /** Optional security label mode */
 420         sec_label_mode_t label_mode;
 421         /** Mode to propose for CHILD_SA */
 422         ipsec_mode_t mode;
 423         /** TFC padding size, 0 to disable, -1 to pad to PMTU */
 424         uint32_t tfc;
 425         /** Optional manually-set IPsec policy priority */
 426         uint32_t priority;
 427         /** Optional network interface restricting IPsec policy (cloned) */
 428         char *interface;
 429         /** lifetime_cfg_t for this child_cfg */
 430         lifetime_cfg_t lifetime;
 431         /** Inactivity timeout in s before closing a CHILD_SA */
 432         uint32_t inactivity;
 433         /** Start action */
 434         action_t start_action;
 435         /** DPD action */
 436         action_t dpd_action;
 437         /** Close action */
 438         action_t close_action;
 439         /** updown script to execute on up/down event (cloned) */
 440         char *updown;
 441         /** HW offload mode */
 442         hw_offload_t hw_offload;
 443         /** How to handle the DS header field in tunnel mode */
 444         dscp_copy_t copy_dscp;
 445 };
 446
 447 /**
 448  * Create a configuration template for CHILD_SA setup.
 449  *
 450  * After a call to create, a reference is obtained (refcount = 1).
 451  *
 452  * @param name                          name of the child_cfg (cloned)
 453  * @param data                          data for this child_cfg
 454  * @return                                      child_cfg_t object
 455  */
 456 child_cfg_t *child_cfg_create(char *name, child_cfg_create_t *data);
 457
 458 #endif /** CHILD_CFG_H_ @}*/