src/charon/config/policies/policy.h

   1 /**
   2  * @file policy.h
   3  *
   4  * @brief Interface of policy_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005-2006 Martin Willi
  10  * Copyright (C) 2005 Jan Hutter
  11  * Hochschule fuer Technik Rapperswil
  12  *
  13  * This program is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by the
  15  * Free Software Foundation; either version 2 of the License, or (at your
  16  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  17  *
  18  * This program is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  20  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21  * for more details.
  22  */
  23
  24 #ifndef POLICY_H_
  25 #define POLICY_H_
  26
  27 typedef enum dpd_action_t dpd_action_t;
  28 typedef struct policy_t policy_t;
  29
  30 #include <library.h>
  31 #include <utils/identification.h>
  32 #include <config/traffic_selector.h>
  33 #include <config/proposal.h>
  34 #include <sa/authenticators/authenticator.h>
  35 #include <sa/authenticators/eap/eap_method.h>
  36
  37
  38 /**
  39  * @brief Actions to take when a peer does not respond (dead peer detected).
  40  *
  41  * These values are the same as in pluto/starter, so do not modify them!
  42  *
  43  * @ingroup config
  44  */
  45 enum dpd_action_t {
  46         /** DPD disabled */
  47         DPD_NONE,
  48         /** remove CHILD_SA without replacement */
  49         DPD_CLEAR,
  50         /** route the CHILD_SA to resetup when needed */
  51         DPD_ROUTE,
  52         /** restart CHILD_SA in a new IKE_SA, immediately */
  53         DPD_RESTART,
  54 };
  55
  56 /**
  57  * enum names for dpd_action_t.
  58  */
  59 extern enum_name_t *dpd_action_names;
  60
  61 /**
  62  * @brief Mode of an IPsec SA.
  63  *
  64  * These are equal to those defined in XFRM, so don't change.
  65  *
  66  * @ingroup config
  67  */
  68 enum mode_t {
  69         /** transport mode, no inner address */
  70         MODE_TRANSPORT = 0,
  71         /** tunnel mode, inner and outer addresses */
  72         MODE_TUNNEL = 1,
  73         /** BEET mode, tunnel mode but fixed, bound inner addresses */
  74         MODE_BEET = 4,
  75 };
  76
  77 /**
  78  * enum names for mode_t.
  79  */
  80 extern enum_name_t *mode_names;
  81
  82 /**
  83  * @brief A policy_t defines the policies to apply to CHILD_SAs.
  84  *
  85  * The given two IDs identify a policy. These rules define how
  86  * child SAs may be set up and which traffic may be IPsec'ed.
  87  *
  88  * @b Constructors:
  89  *   - policy_create()
  90  *
  91  * @ingroup config
  92  */
  93 struct policy_t {
  94
  95         /**
  96          * @brief Get the name of the policy.
  97          *
  98          * Returned object is not getting cloned.
  99          *
 100          * @param this                  calling object
 101          * @return                              policy's name
 102          */
 103         char *(*get_name) (policy_t *this);
 104
 105         /**
 106          * @brief Get own id.
 107          *
 108          * Returned object is not getting cloned.
 109          *
 110          * @param this                  calling object
 111          * @return                              own id
 112          */
 113         identification_t *(*get_my_id) (policy_t *this);
 114
 115         /**
 116          * @brief Get peer id.
 117          *
 118          * Returned object is not getting cloned.
 119          *
 120          * @param this                  calling object
 121          * @return                              other id
 122          */
 123         identification_t *(*get_other_id) (policy_t *this);
 124
 125         /**
 126          * @brief Get own ca.
 127          *
 128          * Returned object is not getting cloned.
 129          *
 130          * @param this                  calling object
 131          * @return                              own ca
 132          */
 133         identification_t *(*get_my_ca) (policy_t *this);
 134
 135         /**
 136          * @brief Get peer ca.
 137          *
 138          * Returned object is not getting cloned.
 139          *
 140          * @param this                  calling object
 141          * @return                              other ca
 142          */
 143         identification_t *(*get_other_ca) (policy_t *this);
 144
 145         /**
 146          * @brief Get the authentication method to use.
 147          *
 148          * @param this          calling object
 149          * @return                      authentication method
 150          */
 151         auth_method_t (*get_auth_method) (policy_t *this);
 152
 153         /**
 154          * @brief Get the EAP type to use for peer authentication.
 155          *
 156          * @param this          calling object
 157          * @return                      authentication method
 158          */
 159         eap_type_t (*get_eap_type) (policy_t *this);
 160
 161         /**
 162          * @brief Get configured traffic selectors for our site.
 163          *
 164          * Returns a list with all traffic selectors for the local
 165          * site. List and items must be destroyed after usage.
 166          *
 167          * @param this                  calling object
 168          * @return                              list with traffic selectors
 169          */
 170         linked_list_t *(*get_my_traffic_selectors) (policy_t *this, host_t *me);
 171
 172         /**
 173          * @brief Get configured traffic selectors for others site.
 174          *
 175          * Returns a list with all traffic selectors for the remote
 176          * site. List and items must be destroyed after usage.
 177          *
 178          * @param this                  calling object
 179          * @return                              list with traffic selectors
 180          */
 181         linked_list_t *(*get_other_traffic_selectors) (policy_t *this, host_t* other);
 182
 183         /**
 184          * @brief Select traffic selectors from a supplied list for local site.
 185          *
 186          * Resulted list and traffic selectors must be destroyed after usage.
 187          * As the traffic selectors may contain a wildcard address (0.0.0.0) for
 188          * addresses we don't know in previous, an address may be supplied to
 189          * replace these 0.0.0.0 addresses on-the-fly.
 190          *
 191          * @param this                  calling object
 192          * @param supplied              linked list with traffic selectors
 193          * @param me                    host address used by us
 194          * @return                              list containing the selected traffic selectors
 195          */
 196         linked_list_t *(*select_my_traffic_selectors) (policy_t *this,
 197                                                                                                    linked_list_t *supplied,
 198                                                                                                    host_t *me);
 199
 200         /**
 201          * @brief Select traffic selectors from a supplied list for remote site.
 202          *
 203          * Resulted list and traffic selectors must be destroyed after usage.
 204          * As the traffic selectors may contain a wildcard address (0.0.0.0) for
 205          * addresses we don't know in previous, an address may be supplied to
 206          * replace these 0.0.0.0 addresses on-the-fly.
 207          *
 208          * @param this                  calling object
 209          * @param supplied              linked list with traffic selectors
 210          * @return                              list containing the selected traffic selectors
 211          */
 212         linked_list_t *(*select_other_traffic_selectors) (policy_t *this,
 213                                                                                                           linked_list_t *supplied,
 214                                                                                                           host_t *other);
 215
 216         /**
 217          * @brief Get the list of internally stored proposals.
 218          *
 219          * policy_t does store proposals for AH/ESP, IKE proposals are in
 220          * the connection_t.
 221          * Resulting list and all of its proposals must be freed after usage.
 222          *
 223          * @param this                  calling object
 224          * @return                              lists with proposals
 225          */
 226         linked_list_t *(*get_proposals) (policy_t *this);
 227
 228         /**
 229          * @brief Select a proposal from a supplied list.
 230          *
 231          * Returned propsal is newly created and must be destroyed after usage.
 232          *
 233          * @param this                  calling object
 234          * @param proposals             list from from wich proposals are selected
 235          * @return                              selected proposal, or NULL if nothing matches
 236          */
 237         proposal_t *(*select_proposal) (policy_t *this, linked_list_t *proposals);
 238
 239         /**
 240          * @brief Add a traffic selector to the list for local site.
 241          *
 242          * After add, traffic selector is owned by policy.
 243          *
 244          * @param this                          calling object
 245          * @param traffic_selector      traffic_selector to add
 246          */
 247         void (*add_my_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector);
 248
 249         /**
 250          * @brief Add a traffic selector to the list for remote site.
 251          *
 252          * After add, traffic selector is owned by policy.
 253          *
 254          * @param this                          calling object
 255          * @param traffic_selector      traffic_selector to add
 256          */
 257         void (*add_other_traffic_selector) (policy_t *this, traffic_selector_t *traffic_selector);
 258
 259         /**
 260          * @brief Add a proposal to the list.
 261          *
 262          * The proposals are stored by priority, first added
 263          * is the most prefered.
 264          * After add, proposal is owned by policy.
 265          *
 266          * @param this                  calling object
 267          * @param proposal              proposal to add
 268          */
 269         void (*add_proposal) (policy_t *this, proposal_t *proposal);
 270
 271         /**
 272          * @brief Add certification authorities.
 273          *
 274          * @param this                  calling object
 275          * @param my_ca                 issuer of my certificate
 276          * @param other_ca              required issuer of the peer's certificate
 277          */
 278         void (*add_authorities) (policy_t *this, identification_t *my_ca, identification_t *other_ca);
 279
 280         /**
 281          * @brief Get updown script
 282          *
 283          * @param this                  calling object
 284          * @return                              path to updown script
 285          */
 286         char* (*get_updown) (policy_t *this);
 287
 288         /**
 289          * @brief Get hostaccess flag
 290          *
 291          * @param this                  calling object
 292          * @return                              value of hostaccess flag
 293          */
 294         bool (*get_hostaccess) (policy_t *this);
 295
 296         /**
 297          * @brief What should be done with a CHILD_SA, when other peer does not respond.
 298          *
 299          * @param this          calling object
 300          * @return                      dpd action
 301          */
 302         dpd_action_t (*get_dpd_action) (policy_t *this);
 303
 304         /**
 305          * @brief Get the lifetime of a policy, before rekeying starts.
 306          *
 307          * A call to this function automatically adds a jitter to
 308          * avoid simultanous rekeying.
 309          *
 310          * @param this                  policy
 311          * @return                              lifetime in seconds
 312          */
 313         u_int32_t (*get_soft_lifetime) (policy_t *this);
 314
 315         /**
 316          * @brief Get the lifetime of a policy, before SA gets deleted.
 317          *
 318          * @param this                  policy
 319          * @return                              lifetime in seconds
 320          */
 321         u_int32_t (*get_hard_lifetime) (policy_t *this);
 322
 323         /**
 324          * @brief Get the mode to use for the CHILD_SA, tunnel, transport or BEET.
 325          *
 326          * @param this                  policy
 327          * @return                              lifetime in seconds
 328          */
 329         mode_t (*get_mode) (policy_t *this);
 330
 331         /**
 332          * @brief Get a virtual IP for the local or the remote host.
 333          *
 334          * By supplying NULL as IP, an IP for the local host is requested. It
 335          * may be %any or specific.
 336          * By supplying %any as host, an IP from the pool is selected to be
 337          * served to the peer.
 338          * If a specified host is supplied, it is checked if this address
 339          * is acceptable to serve to the peer. If so, it is returned. Otherwise,
 340          * an alternative IP is returned.
 341          * In any mode, this call may return NULL indicating virtual IP should
 342          * not be used.
 343          *
 344          * @param this                  policy
 345          * @param suggestion    NULL, %any or specific, see description
 346          * @return                              clone of an IP to use, or NULL
 347          */
 348         host_t* (*get_virtual_ip) (policy_t *this, host_t *suggestion);
 349
 350         /**
 351          * @brief Get a new reference.
 352          *
 353          * Get a new reference to this policy by increasing
 354          * it's internal reference counter.
 355          * Do not call get_ref or any other function until you
 356          * already have a reference. Otherwise the object may get
 357          * destroyed while calling get_ref(),
 358          *
 359          * @param this                          calling object
 360          */
 361         void (*get_ref) (policy_t *this);
 362
 363         /**
 364          * @brief Destroys the policy object.
 365          *
 366          * Decrements the internal reference counter and
 367          * destroys the policy when it reaches zero.
 368          *
 369          * @param this                          calling object
 370          */
 371         void (*destroy) (policy_t *this);
 372 };
 373
 374 /**
 375  * @brief Create a configuration object for IKE_AUTH and later.
 376  *
 377  * name-string gets cloned, ID's not.
 378  * Virtual IPs are used if they are != NULL. A %any host means the virtual
 379  * IP should be obtained from the other peer.
 380  * Lifetimes are in seconds. To prevent to peers to start rekeying at the
 381  * same time, a jitter may be specified. Rekeying of an SA starts at
 382  * (soft_lifetime - random(0, jitter)). After a successful rekeying,
 383  * the hard_lifetime limit counter is reset. You should specify
 384  * hard_lifetime > soft_lifetime > jitter.
 385  * After a call to create, a reference is obtained (refcount = 1).
 386  *
 387  * @param name                          name of the policy
 388  * @param my_id                         identification_t for ourselves
 389  * @param other_id                      identification_t for the remote guy
 390  * @param my_virtual_ip         virtual IP for local host, or NULL
 391  * @param other_virtual_ip      virtual IP for remote host, or NULL
 392  * @param auth_method           Authentication method to use for our(!) auth data
 393  * @param eap_type                      EAP type to use for peer authentication
 394  * @param hard_lifetime         lifetime before deleting an SA
 395  * @param soft_lifetime         lifetime before rekeying an SA
 396  * @param jitter                        range of randomization time
 397  * @param updown                        updown script to execute on up/down event
 398  * @param hostaccess            allow access to the host itself (used by the updown script)
 399  * @param mode                          mode to propose for CHILD_SA, transport, tunnel or BEET
 400  * @param dpd_action            what to to with a CHILD_SA when other peer does not respond
 401  * @return                                      policy_t object
 402  *
 403  * @ingroup config
 404  */
 405 policy_t *policy_create(char *name,
 406                                                 identification_t *my_id, identification_t *other_id,
 407                                                 host_t *my_virtual_ip, host_t *other_virtual_ip,
 408                                                 auth_method_t auth_method, eap_type_t eap_type,
 409                                                 u_int32_t hard_lifetime, u_int32_t soft_lifetime,
 410                                                 u_int32_t jitter, char *updown, bool hostaccess,
 411                                                 mode_t mode, dpd_action_t dpd_action);
 412
 413 #endif /* POLICY_H_ */