programs/charon/charon/config/proposal.h

   1 /**
   2  * @file proposal.h
   3  *
   4  * @brief Interface of proposal_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 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 PROPOSAL_H_
  24 #define PROPOSAL_H_
  25
  26 #include <types.h>
  27 #include <utils/identification.h>
  28 #include <utils/linked_list.h>
  29 #include <utils/host.h>
  30 #include <crypto/crypters/crypter.h>
  31 #include <crypto/signers/signer.h>
  32 #include <crypto/diffie_hellman.h>
  33 #include <config/traffic_selector.h>
  34
  35
  36 typedef enum protocol_id_t protocol_id_t;
  37
  38 /**
  39  * Protocol ID of a proposal.
  40  *
  41  * @ingroup config
  42  */
  43 enum protocol_id_t {
  44         PROTO_NONE = 0,
  45         PROTO_IKE = 1,
  46         PROTO_AH = 2,
  47         PROTO_ESP = 3,
  48 };
  49
  50 /**
  51  * String mappings for protocol_id_t.
  52  *
  53  * @ingroup config
  54  */
  55 extern mapping_t protocol_id_m[];
  56
  57
  58 typedef enum transform_type_t transform_type_t;
  59
  60 /**
  61  * Type of a transform, as in IKEv2 RFC 3.3.2.
  62  *
  63  * @ingroup payloads
  64  */
  65 enum transform_type_t {
  66         UNDEFINED_TRANSFORM_TYPE = 241,
  67         ENCRYPTION_ALGORITHM = 1,
  68         PSEUDO_RANDOM_FUNCTION = 2,
  69         INTEGRITY_ALGORITHM = 3,
  70         DIFFIE_HELLMAN_GROUP = 4,
  71         EXTENDED_SEQUENCE_NUMBERS = 5
  72 };
  73
  74 /**
  75  * String mappings for transform_type_t.
  76  *
  77  * @ingroup payloads
  78  */
  79 extern mapping_t transform_type_m[];
  80
  81
  82 typedef enum extended_sequence_numbers_t extended_sequence_numbers_t;
  83
  84 /**
  85  * Extended sequence numbers, as in IKEv2 RFC 3.3.2.
  86  *
  87  * @ingroup payloads
  88  */
  89 enum extended_sequence_numbers_t {
  90         NO_EXT_SEQ_NUMBERS = 0,
  91         EXT_SEQ_NUMBERS = 1
  92 };
  93
  94 /**
  95  * String mappings for extended_sequence_numbers_t.
  96  *
  97  * @ingroup payloads
  98  */
  99 extern mapping_t extended_sequence_numbers_m[];
 100
 101
 102 typedef struct algorithm_t algorithm_t;
 103
 104 /**
 105  * Struct used to store different kinds of algorithms. The internal
 106  * lists of algorithms contain such structures.
 107  */
 108 struct algorithm_t {
 109         /**
 110          * Value from an encryption_algorithm_t/integrity_algorithm_t/...
 111          */
 112         u_int16_t algorithm;
 113
 114         /**
 115          * the associated key size, or zero if not needed
 116          */
 117         u_int16_t key_size;
 118 };
 119
 120 typedef struct proposal_t proposal_t;
 121
 122 /**
 123  * @brief Stores a set of algorithms used for an SA.
 124  *
 125  * A proposal stores algorithms for a specific
 126  * protocol. It can store algorithms for more than
 127  * one protocol (e.g. AH and ESP). Then the proposal
 128  * means both protocols must be used.
 129  * A proposal may contain more than one algorithm
 130  * of the same kind. ONE of them can be selected.
 131  *
 132  * @warning This class is NOT thread-save!
 133  *
 134  * @b Constructors:
 135  *   - proposal_create()
 136  *
 137  * @ingroup config
 138  */
 139 struct proposal_t {
 140
 141         /**
 142          * @brief Add an algorithm to the proposal.
 143          *
 144          * The algorithms are stored by priority, first added
 145          * is the most preferred.
 146          * Key size is only needed for encryption algorithms
 147          * with variable key size (such as AES). Must be set
 148          * to zero if key size is not specified.
 149          * The alg parameter accepts encryption_algorithm_t,
 150          * integrity_algorithm_t, dh_group_number_t and
 151          * extended_sequence_numbers_t.
 152          *
 153          * @warning Do not add while other threads are reading.
 154          *
 155          * @param this                                  calling object
 156          * @param proto                                 desired protocol
 157          * @param type                                  kind of algorithm
 158          * @param alg                                   identifier for algorithm
 159          * @param key_size                              key size to use
 160          */
 161         void (*add_algorithm) (proposal_t *this, protocol_id_t proto, transform_type_t type, u_int16_t alg, size_t key_size);
 162
 163         /**
 164          * @brief Get an iterator over algorithms for a specifc protocol/algo type.
 165          *
 166          * @param this                                  calling object
 167          * @param proto                                 desired protocol
 168          * @param type                                  kind of algorithm
 169          * @return                                              iterator over algorithms
 170          */
 171         iterator_t *(*create_algorithm_iterator) (proposal_t *this, protocol_id_t proto, transform_type_t type);
 172
 173         /**
 174          * @brief Get the algorithm for a type to use.
 175          *
 176          * If there are multiple algorithms, only the first is returned.
 177          * Result is still owned by proposal, do not modify!
 178          *
 179          * @param this                                  calling object
 180          * @param proto                                 desired protocol
 181          * @param type                                  kind of algorithm
 182          * @param[out] algo                             pointer which receives algorithm and key size
 183          * @return                                              TRUE if algorithm of this kind available
 184          */
 185         bool (*get_algorithm) (proposal_t *this, protocol_id_t proto, transform_type_t type, algorithm_t** algo);
 186
 187         /**
 188          * @brief Compare two proposal, and select a matching subset.
 189          *
 190          * If the proposals are for the same protocols (AH/ESP), they are
 191          * compared. If they have at least one algorithm of each type
 192          * in common, a resulting proposal of this kind is created.
 193          *
 194          * @param this                                  calling object
 195          * @param other                                 proposal to compair agains
 196          * @return
 197          *                                                              - selected proposal, if possible
 198          *                                                              - NULL, if proposals don't match
 199          */
 200         proposal_t *(*select) (proposal_t *this, proposal_t *other);
 201
 202         /**
 203          * @brief Get the number set on construction.
 204          *
 205          * @param this                          calling object
 206          * @return                                      number
 207          */
 208         u_int8_t (*get_number) (proposal_t *this);
 209
 210         /**
 211          * @brief Get the protocol ids in the proposals.
 212          *
 213          * With AH and ESP, there could be two protocols in one
 214          * proposal.
 215          *
 216          * @param this                          calling object
 217          * @param ids                           array of protocol ids,
 218          */
 219         void (*get_protocols) (proposal_t *this, protocol_id_t ids[2]);
 220
 221         /**
 222          * @brief Get the spi for a specific protocol.
 223          *
 224          * @param this                          calling object
 225          * @param proto                         AH/ESP
 226          * @return                                      spi for proto
 227          */
 228         u_int64_t (*get_spi) (proposal_t *this, protocol_id_t proto);
 229
 230         /**
 231          * @brief Set the spi for a specific protocol.
 232          *
 233          * @param this                          calling object
 234          * @param proto                         AH/ESP
 235          * @param spi                           spi to set for proto
 236          */
 237         void (*set_spi) (proposal_t *this, protocol_id_t proto, u_int64_t spi);
 238
 239         /**
 240          * @brief Clone a proposal.
 241          *
 242          * @param this                          proposal to clone
 243          * @return                                      clone of it
 244          */
 245         proposal_t *(*clone) (proposal_t *this);
 246
 247         /**
 248          * @brief Destroys the proposal object.
 249          *
 250          * @param this                          calling object
 251          */
 252         void (*destroy) (proposal_t *this);
 253 };
 254
 255 /**
 256  * @brief Create a child proposal for AH and/or ESP.
 257  *
 258  * Since the order of multiple proposals is important for
 259  * key derivation, we must assign them numbers as they
 260  * appear in the raw payload. Numbering starts at 1.
 261  *
 262  * @param number                        number of the proposal, as in the payload
 263  * @return                                      proposal_t object
 264  *
 265  * @ingroup config
 266  */
 267 proposal_t *proposal_create(u_int8_t number);
 268
 269 #endif /* PROPOSAL_H_ */