src/libstrongswan/crypto/proposal/proposal.h

   1 /*
   2  * Copyright (C) 2009-2018 Tobias Brunner
   3  * Copyright (C) 2006 Martin Willi
   4  * HSR Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup proposal proposal
  19  * @{ @ingroup crypto
  20  */
  21
  22 #ifndef PROPOSAL_H_
  23 #define PROPOSAL_H_
  24
  25 typedef enum protocol_id_t protocol_id_t;
  26 typedef enum proposal_selection_flag_t proposal_selection_flag_t;
  27 typedef enum extended_sequence_numbers_t extended_sequence_numbers_t;
  28 typedef struct proposal_t proposal_t;
  29
  30 #include <library.h>
  31 #include <utils/identification.h>
  32 #include <collections/linked_list.h>
  33 #include <networking/host.h>
  34 #include <crypto/transform.h>
  35 #include <crypto/crypters/crypter.h>
  36 #include <crypto/signers/signer.h>
  37 #include <crypto/diffie_hellman.h>
  38
  39 /**
  40  * Protocol ID of a proposal.
  41  */
  42 enum protocol_id_t {
  43         PROTO_NONE = 0,
  44         PROTO_IKE = 1,
  45         PROTO_AH = 2,
  46         PROTO_ESP = 3,
  47         PROTO_IPCOMP = 4, /* IKEv1 only */
  48 };
  49
  50 /**
  51  * enum names for protocol_id_t
  52  */
  53 extern enum_name_t *protocol_id_names;
  54
  55 /**
  56  * Flags for selecting proposals
  57  */
  58 enum proposal_selection_flag_t {
  59         /** Whether to prefer configured (default) or supplied proposals. */
  60         PROPOSAL_PREFER_SUPPLIED = (1<<0),
  61         /** Whether to skip and ignore algorithms from a private range. */
  62         PROPOSAL_SKIP_PRIVATE = (1<<1),
  63         /** Whether to skip and ignore diffie hellman groups. */
  64         PROPOSAL_SKIP_DH = (1<<2),
  65 };
  66
  67 /**
  68  * Stores a set of algorithms used for an SA.
  69  *
  70  * A proposal stores algorithms for a specific
  71  * protocol. It can store algorithms for one protocol.
  72  * Proposals with multiple protocols are not supported,
  73  * as it's not specified in RFC4301 anymore.
  74  */
  75 struct proposal_t {
  76
  77         /**
  78          * Add an algorithm to the proposal.
  79          *
  80          * The algorithms are stored by priority, first added
  81          * is the most preferred.
  82          * Key size is only needed for encryption algorithms
  83          * with variable key size (such as AES). Must be set
  84          * to zero if key size is not specified.
  85          * The alg parameter accepts encryption_algorithm_t,
  86          * integrity_algorithm_t, dh_group_number_t and
  87          * extended_sequence_numbers_t.
  88          *
  89          * @param type                  kind of algorithm
  90          * @param alg                   identifier for algorithm
  91          * @param key_size              key size to use
  92          */
  93         void (*add_algorithm) (proposal_t *this, transform_type_t type,
  94                                                    uint16_t alg, uint16_t key_size);
  95
  96         /**
  97          * Get an enumerator over algorithms for a specific algo type.
  98          *
  99          * @param type                  kind of algorithm
 100          * @return                              enumerator over uint16_t alg, uint16_t key_size
 101          */
 102         enumerator_t *(*create_enumerator) (proposal_t *this, transform_type_t type);
 103
 104         /**
 105          * Get the algorithm for a type to use.
 106          *
 107          * If there are multiple algorithms, only the first is returned.
 108          *
 109          * @param type                  kind of algorithm
 110          * @param alg                   pointer which receives algorithm
 111          * @param key_size              pointer which receives the key size
 112          * @return                              TRUE if algorithm of this kind available
 113          */
 114         bool (*get_algorithm) (proposal_t *this, transform_type_t type,
 115                                                    uint16_t *alg, uint16_t *key_size);
 116
 117         /**
 118          * Check if the proposal has a specific DH group.
 119          *
 120          * @param group                 group to check for
 121          * @return                              TRUE if algorithm included
 122          */
 123         bool (*has_dh_group)(proposal_t *this, diffie_hellman_group_t group);
 124
 125         /**
 126          * Move the given DH group to the front of the list if it was contained in
 127          * the proposal.
 128          *
 129          * @param group                 group to promote
 130          * @return                              TRUE if algorithm included
 131          */
 132         bool (*promote_dh_group)(proposal_t *this, diffie_hellman_group_t group);
 133
 134         /**
 135          * Compare two proposal, and select a matching subset.
 136          *
 137          * If the proposals are for the same protocols (AH/ESP), they are
 138          * compared. If they have at least one algorithm of each type
 139          * in common, a resulting proposal of this kind is created.
 140          *
 141          * Unless the flag PROPOSAL_PREFER_SUPPLIED is set, other is expected to be
 142          * the remote proposal from which to copy SPI and proposal number to the
 143          * result, otherwise copy from this proposal.
 144          *
 145          * @param other                 proposal to compare against
 146          * @param flags                 flags to consider during proposal selection
 147          * @return                              selected proposal, NULL if proposals don't match
 148          */
 149         proposal_t *(*select)(proposal_t *this, proposal_t *other,
 150                                                   proposal_selection_flag_t flags);
 151
 152         /**
 153          * Check if the given proposal matches this proposal.
 154          *
 155          * This is similar to select, but no resulting proposal is selected.
 156          *
 157          * @param other                 proposal to compare against
 158          * @param flags                 flags to consider during proposal selection
 159          * @return                              TRUE if the proposals match
 160          */
 161         bool (*matches)(proposal_t *this, proposal_t *other,
 162                                         proposal_selection_flag_t flags);
 163
 164         /**
 165          * Get the protocol ID of the proposal.
 166          *
 167          * @return                              protocol of the proposal
 168          */
 169         protocol_id_t (*get_protocol) (proposal_t *this);
 170
 171         /**
 172          * Get the SPI of the proposal.
 173          *
 174          * @return                              spi for proto
 175          */
 176         uint64_t (*get_spi) (proposal_t *this);
 177
 178         /**
 179          * Set the SPI of the proposal.
 180          *
 181          * @param spi                   spi to set for proto
 182          */
 183         void (*set_spi) (proposal_t *this, uint64_t spi);
 184
 185         /**
 186          * Get the proposal number, as encoded in SA payload
 187          *
 188          * @return                              proposal number
 189          */
 190         u_int (*get_number)(proposal_t *this);
 191
 192         /**
 193          * Check for the eqality of two proposals.
 194          *
 195          * @param other                 other proposal to check for equality
 196          * @return                              TRUE if other equal to this
 197          */
 198         bool (*equals)(proposal_t *this, proposal_t *other);
 199
 200         /**
 201          * Clone a proposal.
 202          *
 203          * @param flags                 flags to consider during cloning
 204          * @return                              clone of proposal
 205          */
 206         proposal_t *(*clone)(proposal_t *this, proposal_selection_flag_t flags);
 207
 208         /**
 209          * Destroys the proposal object.
 210          */
 211         void (*destroy) (proposal_t *this);
 212 };
 213
 214 /**
 215  * Create a child proposal for AH, ESP or IKE.
 216  *
 217  * @param protocol                      protocol, such as PROTO_ESP
 218  * @param number                        proposal number, as encoded in SA payload
 219  * @return                                      proposal_t object
 220  */
 221 proposal_t *proposal_create(protocol_id_t protocol, u_int number);
 222
 223 /**
 224  * Create a default proposal if nothing further specified.
 225  *
 226  * @param protocol                      protocol, such as PROTO_ESP
 227  * @return                                      proposal_t object
 228  */
 229 proposal_t *proposal_create_default(protocol_id_t protocol);
 230
 231 /**
 232  * Create a default proposal for supported AEAD algorithms
 233  *
 234  * @param protocol                      protocol, such as PROTO_ESP
 235  * @return                                      proposal_t object, NULL if none supported
 236  */
 237 proposal_t *proposal_create_default_aead(protocol_id_t protocol);
 238
 239 /**
 240  * Create a proposal from a string identifying the algorithms.
 241  *
 242  * The string is in the same form as a in the ipsec.conf file.
 243  * E.g.:        aes128-sha2_256-modp2048
 244  *                3des-md5
 245  * An additional '!' at the end of the string forces this proposal,
 246  * without it the peer may choose another algorithm we support.
 247  *
 248  * @param protocol                      protocol, such as PROTO_ESP
 249  * @param algs                          algorithms as string
 250  * @return                                      proposal_t object
 251  */
 252 proposal_t *proposal_create_from_string(protocol_id_t protocol,
 253                                                                                 const char *algs);
 254
 255 /**
 256  * Select a common proposal from the given lists of proposals.
 257  *
 258  * @param configured            list of configured/local proposals
 259  * @param supplied                      list of supplied/remote proposals
 260  * @param flags                         flags to consider during proposal selection
 261  * @return                                      selected proposal, or NULL (allocated)
 262  */
 263 proposal_t *proposal_select(linked_list_t *configured, linked_list_t *supplied,
 264                                                         proposal_selection_flag_t flags);
 265
 266 /**
 267  * printf hook function for proposal_t.
 268  *
 269  * Arguments are:
 270  *      proposal_t *proposal
 271  * With the #-specifier, arguments are:
 272  *      linked_list_t *list containing proposal_t*
 273  */
 274 int proposal_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
 275                                                  const void *const *args);
 276
 277 #endif /** PROPOSAL_H_ @}*/