src/charon/config/connections/connection.h

   1 /**
   2  * @file connection.h
   3  *
   4  * @brief Interface of connection_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 CONNECTION_H_
  25 #define CONNECTION_H_
  26
  27 typedef enum cert_policy_t cert_policy_t;
  28 typedef struct connection_t connection_t;
  29
  30 #include <library.h>
  31 #include <utils/host.h>
  32 #include <utils/linked_list.h>
  33 #include <utils/identification.h>
  34 #include <config/proposal.h>
  35 #include <crypto/diffie_hellman.h>
  36
  37
  38 /**
  39  * Certificate sending policy. This is also used for certificate
  40  * requests when using this definition for the other peer. If
  41  * it is CERT_NEVER_SEND, a certreq is omitted, otherwise its
  42  * included.
  43  *
  44  * @ingroup config
  45  *
  46  * @warning These definitions must be the same as in pluto/starter,
  47  * as they are sent over the stroke socket.
  48  */
  49 enum cert_policy_t {
  50         /** always send certificates, even when not requested */
  51         CERT_ALWAYS_SEND   = 0,
  52         /** send certificate upon cert request */
  53         CERT_SEND_IF_ASKED = 1,
  54         /** never send a certificate, even when requested */
  55         CERT_NEVER_SEND    = 2,
  56 };
  57
  58 /**
  59  * enum strings for cert_policy_t
  60  *
  61  * @ingroup config
  62  */
  63 extern enum_name_t *cert_policy_names;
  64
  65 /**
  66  * @brief A connection_t defines the rules to set up an IKE_SA.
  67  *
  68  * @b Constructors:
  69  *  - connection_create()
  70  *
  71  * @ingroup config
  72  */
  73 struct connection_t {
  74
  75         /**
  76          * @brief Get my address as host_t object.
  77          *
  78          * Object is NOT getting cloned.
  79          *
  80          * @param this  calling object
  81          * @return              host information as host_t object
  82          */
  83         host_t *(*get_my_host) (connection_t *this);
  84
  85         /**
  86          * @brief Get others address as host_t object.
  87          *
  88          * Object is NOT getting cloned.
  89          *
  90          * @param this  calling object
  91          * @return              host information as host_t object
  92          */
  93         host_t *(*get_other_host) (connection_t *this);
  94
  95         /**
  96          * @brief Returns a list of all supported proposals.
  97          *
  98          * Returned list and its proposals  must be destroyed after usage.
  99          *
 100          * @param this          calling object
 101          * @return                      list containing all the proposals
 102          */
 103         linked_list_t *(*get_proposals) (connection_t *this);
 104
 105         /**
 106          * @brief Adds a proposal to the list.
 107          *
 108          * The first added proposal has the highest priority, the last
 109          * added the lowest.
 110          *
 111          * @param this          calling object
 112          * @param proposal      proposal to add
 113          */
 114         void (*add_proposal) (connection_t *this, proposal_t *proposal);
 115
 116         /**
 117          * @brief Select a proposed from suggested proposals.
 118          *
 119          * Returned proposal must be destroyed after usage.
 120          *
 121          * @param this          calling object
 122          * @param proposals     list of proposals to select from
 123          * @return                      selected proposal, or NULL if none matches.
 124          */
 125         proposal_t *(*select_proposal) (connection_t *this, linked_list_t *proposals);
 126
 127         /**
 128          * @brief Get the DPD check interval.
 129          *
 130          * @param this          calling object
 131          * @return                      dpd_delay in seconds
 132          */
 133         u_int32_t (*get_dpd_delay) (connection_t *this);
 134
 135         /**
 136          * @brief Should a full reauthentication be done instead of rekeying?
 137          *
 138          * @param this          calling object
 139          * @return                      TRUE to use full reauthentication
 140          */
 141         bool (*get_reauth) (connection_t *this);
 142
 143         /**
 144          * @brief Get the max number of retransmission sequences.
 145          *
 146          * After this number of sequences, a not responding peer is considered
 147          * dead.
 148          *
 149          * @param this          calling object
 150          * @return                      max number of retransmission sequences
 151          */
 152         u_int32_t (*get_retrans_seq) (connection_t *this);
 153
 154         /**
 155          * @brief Get the connection name.
 156          *
 157          * Name must not be freed, since it points to
 158          * internal data.
 159          *
 160          * @param this          calling object
 161          * @return                      name of the connection
 162          */
 163         char* (*get_name) (connection_t *this);
 164
 165         /**
 166          * @brief Check if the connection is marked as an IKEv2 connection.
 167          *
 168          * Since all connections (IKEv1+2) are loaded, but charon handles
 169          * only those marked with IKEv2, this flag can tell us if we must
 170          * ignore a connection on initiaton. Then pluto will do it for us.
 171          *
 172          * @param this          calling object
 173          * @return                      - TRUE, if this is an IKEv2 connection
 174          */
 175         bool (*is_ikev2) (connection_t *this);
 176
 177         /**
 178          * @brief Should be sent a certificate request for this connection?
 179          *
 180          * A certificate request contains serials of our trusted CA certificates.
 181          * This flag says if such a request is sent on connection setup to
 182          * the peer. It should be omitted when CERT_SEND_NEVER, sended otherwise.
 183          *
 184          * @param this          calling object
 185          * @return                      certificate request sending policy
 186          */
 187         cert_policy_t (*get_certreq_policy) (connection_t *this);
 188
 189         /**
 190          * @brief Should be sent a certificate for this connection?
 191          *
 192          * Return the policy used to send the certificate.
 193          *
 194          * @param this          calling object
 195          * @return                      certificate sending policy
 196          */
 197         cert_policy_t (*get_cert_policy) (connection_t *this);
 198
 199         /**
 200          * @brief Get the DH group to use for connection initialization.
 201          *
 202          * @param this          calling object
 203          * @return                      dh group to use for initialization
 204          */
 205         diffie_hellman_group_t (*get_dh_group) (connection_t *this);
 206
 207         /**
 208          * @brief Check if a suggested dh group is acceptable.
 209          *
 210          * If we guess a wrong DH group for IKE_SA_INIT, the other
 211          * peer will send us a offer. But is this acceptable for us?
 212          *
 213          * @param this          calling object
 214          * @return                      TRUE if group acceptable
 215          */
 216         bool (*check_dh_group) (connection_t *this, diffie_hellman_group_t dh_group);
 217
 218         /**
 219          * @brief Get the lifetime of a connection, before IKE_SA rekeying starts.
 220          *
 221          * A call to this function automatically adds a jitter to
 222          * avoid simultanous rekeying.
 223          *
 224          * @param this          calling object
 225          * @return                      lifetime in seconds
 226          */
 227         u_int32_t (*get_soft_lifetime) (connection_t *this);
 228
 229         /**
 230          * @brief Get the lifetime of a connection, before IKE_SA gets deleted.
 231          *
 232          * @param this          calling object
 233          * @return                      lifetime in seconds
 234          */
 235         u_int32_t (*get_hard_lifetime) (connection_t *this);
 236
 237         /**
 238          * @brief Get a new reference to this connection.
 239          *
 240          * Get a new reference to this connection by increasing
 241          * it's internal reference counter.
 242          * Do not call get_ref or any other function until you
 243          * already have a reference. Otherwise the object may get
 244          * destroyed while calling get_ref(),
 245          *
 246          * @param this          calling object
 247          */
 248         void (*get_ref) (connection_t *this);
 249
 250         /**
 251          * @brief Destroys a connection_t object.
 252          *
 253          * Decrements the internal reference counter and
 254          * destroys the connection when it reaches zero.
 255          *
 256          * @param this          calling object
 257          */
 258         void (*destroy) (connection_t *this);
 259 };
 260
 261 /**
 262  * @brief Creates a connection_t object.
 263  *
 264  * Supplied hosts become owned by connection, so
 265  * do not modify or destroy them after a call to
 266  * connection_create(). Name gets cloned internally.
 267  * The retrasmit sequence number says how fast we give up when the peer
 268  * does not respond. A high value may bridge-over temporary connection
 269  * problems, a small value can detect dead peers faster.
 270  *
 271  * @param name                          connection identifier
 272  * @param ikev2                         TRUE if this is an IKEv2 connection
 273  * @param cert_policy           certificate send policy
 274  * @param cert_req_policy       certificate request send policy
 275  * @param my_host                       host_t representing local address
 276  * @param other_host            host_t representing remote address
 277  * @param dpd_delay                     interval of DPD liveness checks
 278  * @param reauth                        use full reauthentication instead of rekeying
 279  * @param retrans_sequences     number of retransmit sequences to use
 280  * @param hard_lifetime         lifetime before deleting an IKE_SA
 281  * @param soft_lifetime         lifetime before rekeying an IKE_SA
 282  * @param jitter                        range of randomization time
 283  * @return                                      connection_t object.
 284  *
 285  * @ingroup config
 286  */
 287 connection_t * connection_create(char *name, bool ikev2,
 288                                                                  cert_policy_t cert_pol, cert_policy_t req_pol,
 289                                                                  host_t *my_host, host_t *other_host,
 290                                                                  u_int32_t dpd_delay, bool reauth,
 291                                                                  u_int32_t retrans_sequences,
 292                                                                  u_int32_t hard_lifetime, u_int32_t soft_lifetime,
 293                                                                  u_int32_t jitter);
 294
 295 #endif /* CONNECTION_H_ */