8e952dd4f04937a97663c082263300b6af0d7020
[strongswan.git] / 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 /** Accept algorithms from a private range. */
60 PROPOSAL_ALLOW_PRIVATE = (1<<0),
61 /** Whether to prefer configured (default) or supplied proposals. */
62 PROPOSAL_PREFER_SUPPLIED = (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 * Strip DH groups from proposal to use it without PFS.
136 *
137 * @param keep group to keep (MODP_NONE to remove all)
138 */
139 void (*strip_dh)(proposal_t *this, diffie_hellman_group_t keep);
140
141 /**
142 * Compare two proposal, and select a matching subset.
143 *
144 * If the proposals are for the same protocols (AH/ESP), they are
145 * compared. If they have at least one algorithm of each type
146 * in common, a resulting proposal of this kind is created.
147 *
148 * Unless the flag PROPOSAL_PREFER_SUPPLIED is set, other is expected to be
149 * the remote proposal from which to copy SPI and proposal number to the
150 * result, otherwise copy from this proposal.
151 *
152 * @param other proposal to compare against
153 * @param flags flags to consider during proposal selection
154 * @return selected proposal, NULL if proposals don't match
155 */
156 proposal_t *(*select)(proposal_t *this, proposal_t *other,
157 proposal_selection_flag_t flags);
158
159 /**
160 * Check if the given proposal matches this proposal.
161 *
162 * This is similar to select, but no resulting proposal is selected.
163 *
164 * @param other proposal to compare against
165 * @param flags flags to consider during proposal selection
166 * @return TRUE if the proposals match
167 */
168 bool (*matches)(proposal_t *this, proposal_t *other,
169 proposal_selection_flag_t flags);
170
171 /**
172 * Get the protocol ID of the proposal.
173 *
174 * @return protocol of the proposal
175 */
176 protocol_id_t (*get_protocol) (proposal_t *this);
177
178 /**
179 * Get the SPI of the proposal.
180 *
181 * @return spi for proto
182 */
183 uint64_t (*get_spi) (proposal_t *this);
184
185 /**
186 * Set the SPI of the proposal.
187 *
188 * @param spi spi to set for proto
189 */
190 void (*set_spi) (proposal_t *this, uint64_t spi);
191
192 /**
193 * Get the proposal number, as encoded in SA payload
194 *
195 * @return proposal number
196 */
197 u_int (*get_number)(proposal_t *this);
198
199 /**
200 * Check for the eqality of two proposals.
201 *
202 * @param other other proposal to check for equality
203 * @return TRUE if other equal to this
204 */
205 bool (*equals)(proposal_t *this, proposal_t *other);
206
207 /**
208 * Clone a proposal.
209 *
210 * @return clone of proposal
211 */
212 proposal_t *(*clone) (proposal_t *this);
213
214 /**
215 * Destroys the proposal object.
216 */
217 void (*destroy) (proposal_t *this);
218 };
219
220 /**
221 * Create a child proposal for AH, ESP or IKE.
222 *
223 * @param protocol protocol, such as PROTO_ESP
224 * @param number proposal number, as encoded in SA payload
225 * @return proposal_t object
226 */
227 proposal_t *proposal_create(protocol_id_t protocol, u_int number);
228
229 /**
230 * Create a default proposal if nothing further specified.
231 *
232 * @param protocol protocol, such as PROTO_ESP
233 * @return proposal_t object
234 */
235 proposal_t *proposal_create_default(protocol_id_t protocol);
236
237 /**
238 * Create a default proposal for supported AEAD algorithms
239 *
240 * @param protocol protocol, such as PROTO_ESP
241 * @return proposal_t object, NULL if none supported
242 */
243 proposal_t *proposal_create_default_aead(protocol_id_t protocol);
244
245 /**
246 * Create a proposal from a string identifying the algorithms.
247 *
248 * The string is in the same form as a in the ipsec.conf file.
249 * E.g.: aes128-sha2_256-modp2048
250 * 3des-md5
251 * An additional '!' at the end of the string forces this proposal,
252 * without it the peer may choose another algorithm we support.
253 *
254 * @param protocol protocol, such as PROTO_ESP
255 * @param algs algorithms as string
256 * @return proposal_t object
257 */
258 proposal_t *proposal_create_from_string(protocol_id_t protocol,
259 const char *algs);
260
261 /**
262 * Select a common proposal from the given lists of proposals.
263 *
264 * @param configured list of configured/local proposals
265 * @param supplied list of supplied/remote proposals
266 * @param flags flags to consider during proposal selection
267 * @return selected proposal, or NULL (allocated)
268 */
269 proposal_t *proposal_select(linked_list_t *configured, linked_list_t *supplied,
270 proposal_selection_flag_t flags);
271
272 /**
273 * printf hook function for proposal_t.
274 *
275 * Arguments are:
276 * proposal_t *proposal
277 * With the #-specifier, arguments are:
278 * linked_list_t *list containing proposal_t*
279 */
280 int proposal_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
281 const void *const *args);
282
283 #endif /** PROPOSAL_H_ @}*/