- applied patch from the NAT-T team fixing several typos
[strongswan.git] / src / charon / sa / ike_sa.h
1 /**
2 * @file ike_sa.h
3 *
4 * @brief Interface of ike_sa_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005 Jan Hutter, 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 IKE_SA_H_
24 #define IKE_SA_H_
25
26 #include <types.h>
27 #include <encoding/message.h>
28 #include <encoding/payloads/proposal_substructure.h>
29 #include <sa/ike_sa_id.h>
30 #include <sa/child_sa.h>
31 #include <sa/states/state.h>
32 #include <config/configuration.h>
33 #include <utils/logger.h>
34 #include <utils/randomizer.h>
35 #include <crypto/prfs/prf.h>
36 #include <crypto/crypters/crypter.h>
37 #include <crypto/signers/signer.h>
38 #include <config/connections/connection.h>
39 #include <config/policies/policy.h>
40 #include <utils/logger.h>
41
42 /**
43 * Nonce size in bytes for nonces sending to other peer.
44 *
45 * @warning Nonce size MUST be between 16 and 256 bytes.
46 *
47 * @ingroup sa
48 */
49 #define NONCE_SIZE 16
50
51
52 typedef struct ike_sa_t ike_sa_t;
53
54 /**
55 * @brief Class ike_sa_t representing an IKE_SA.
56 *
57 * An object of this type is managed by an ike_sa_manager_t object
58 * and represents an IKE_SA. Message processing is split up in different states.
59 * They will handle all related things for the state they represent.
60 *
61 * @b Constructors:
62 * - ike_sa_create()
63 *
64 * @ingroup sa
65 */
66 struct ike_sa_t {
67
68 /**
69 * @brief Processes a incoming IKEv2-Message of type message_t.
70 *
71 * @param this ike_sa_t object object
72 * @param[in] message message_t object to process
73 * @return
74 * - SUCCESS
75 * - FAILED
76 * - DELETE_ME if this IKE_SA MUST be deleted
77 */
78 status_t (*process_message) (ike_sa_t *this,message_t *message);
79
80 /**
81 * @brief Initiate a new connection with given connection_t object.
82 *
83 * The connection_t object is owned by the IKE_SA after the call, so
84 * do not modify or destroy it.
85 *
86 * @param this calling object
87 * @param connection connection to initiate
88 * @return
89 * - SUCCESS if initialization started
90 * - FAILED if in wrong state
91 * - DELETE_ME if initialization failed and IKE_SA MUST be deleted
92 */
93 status_t (*initiate_connection) (ike_sa_t *this, connection_t *connection);
94
95 /**
96 * @brief Retransmits a request.
97 *
98 * @param this calling object
99 * @param message_id ID of the request to retransmit
100 * @return
101 * - SUCCESS
102 * - NOT_FOUND if request doesn't have to be retransmited
103 */
104 status_t (*retransmit_request) (ike_sa_t *this, u_int32_t message_id);
105
106 /**
107 * @brief Sends a request to delete IKE_SA.
108 *
109 * Only supported in state IKE_SA_ESTABLISHED
110 *
111 * @param this calling object
112 */
113 void (*send_delete_ike_sa_request) (ike_sa_t *this);
114
115 /**
116 * @brief Get the id of the SA.
117 *
118 * Returned ike_sa_id_t object is not getting cloned!
119 *
120 * @param this calling object
121 * @return ike_sa's ike_sa_id_t
122 */
123 ike_sa_id_t* (*get_id) (ike_sa_t *this);
124
125 /**
126 * @brief Get local peer address of the IKE_SA.
127 *
128 * @param this calling object
129 * @return local host_t
130 */
131 host_t* (*get_my_host) (ike_sa_t *this);
132
133 /**
134 * @brief Get remote peer address of the IKE_SA.
135 *
136 * @param this calling object
137 * @return remote host_t
138 */
139 host_t* (*get_other_host) (ike_sa_t *this);
140
141 /**
142 * @brief Get own ID of the IKE_SA.
143 *
144 * @param this calling object
145 * @return local identification_t
146 */
147 identification_t* (*get_my_id) (ike_sa_t *this);
148
149 /**
150 * @brief Get remote ID the IKE_SA.
151 *
152 * @param this calling object
153 * @return remote identification_t
154 */
155 identification_t* (*get_other_id) (ike_sa_t *this);
156
157 /**
158 * @brief Get the connection of the IKE_SA.
159 *
160 * The internal used connection specification
161 * can be queried to get some data of an IKE_SA.
162 * The connection is still owned to the IKE_SA
163 * and must not be manipulated.
164 *
165 * @param this calling object
166 * @return connection_t
167 */
168 connection_t* (*get_connection) (ike_sa_t *this);
169
170 /**
171 * @brief Get the state of type of associated state object.
172 *
173 * @param this calling object
174 * @return state of IKE_SA
175 */
176 ike_sa_state_t (*get_state) (ike_sa_t *this);
177
178 /**
179 * @brief Log the status of a the ike sa to a logger.
180 *
181 * The status of the IKE SA and all child SAs is logged.
182 * Supplying NULL as logger uses the internal child_sa logger
183 * to do the logging. The log is only done if the supplied
184 * connection name is NULL or matches the connections name.
185 *
186 * @param this calling object
187 * @param logger logger to use for logging
188 * @param name name of the connection
189 */
190 void (*log_status) (ike_sa_t *this, logger_t *logger, char *name);
191
192 /**
193 * @brief Destroys a ike_sa_t object.
194 *
195 * @param this calling object
196 */
197 void (*destroy) (ike_sa_t *this);
198 };
199
200
201 typedef struct protected_ike_sa_t protected_ike_sa_t;
202
203 /**
204 * @brief Protected functions of an ike_sa_t object.
205 *
206 * This members are only accessed out from
207 * the various state_t implementations.
208 *
209 * @ingroup sa
210 */
211 struct protected_ike_sa_t {
212
213 /**
214 * Public interface of an ike_sa_t object.
215 */
216 ike_sa_t public;
217
218 /**
219 * @brief Build an empty IKEv2-Message and fills in default informations.
220 *
221 * Depending on the type of message (request or response), the message id is
222 * either message_id_out or message_id_in.
223 *
224 * Used in state_t Implementation to build an empty IKEv2-Message.
225 *
226 * @param this calling object
227 * @param type exchange type of new message
228 * @param request TRUE, if message has to be a request
229 * @param message new message is stored at this location
230 */
231 void (*build_message) (protected_ike_sa_t *this, exchange_type_t type, bool request, message_t **message);
232
233 /**
234 * @brief Get the internal stored connection_t object.
235 *
236 * @param this calling object
237 * @return pointer to the internal stored connection_t object
238 */
239 connection_t *(*get_connection) (protected_ike_sa_t *this);
240
241 /**
242 * @brief Set the internal connection object.
243 *
244 * @param this calling object
245 * @param connection object of type connection_t
246 */
247 void (*set_connection) (protected_ike_sa_t *this, connection_t *connection);
248
249 /**
250 * @brief Get the internal stored policy object.
251 *
252 * @param this calling object
253 * @return pointer to the internal stored policy_t object
254 */
255 policy_t *(*get_policy) (protected_ike_sa_t *this);
256
257 /**
258 * @brief Set the internal policy_t object.
259 *
260 * @param this calling object
261 * @param policy object of type policy_t
262 */
263 void (*set_policy) (protected_ike_sa_t *this,policy_t *policy);
264
265 /**
266 * @brief Derive all keys and create the transforms for IKE communication.
267 *
268 * Keys are derived using the diffie hellman secret, nonces and internal
269 * stored SPIs.
270 * Already existing objects get destroyed.
271 *
272 * @param this calling object
273 * @param proposal proposal which contains algorithms to use
274 * @param dh diffie hellman object with shared secret
275 * @param nonce_i initiators nonce
276 * @param nonce_r responders nonce
277 */
278 status_t (*build_transforms) (protected_ike_sa_t *this, proposal_t* proposal,
279 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
280
281 /**
282 * @brief Send the next request message.
283 *
284 * Also the first retransmit job is created.
285 *
286 * Last stored requested message gets destroyed. Object gets not cloned!
287 *
288 * @param this calling object
289 * @param message pointer to the message which should be sent
290 * @return
291 * - SUCCESS
292 * - FAILED if message id is not next expected one
293 */
294 status_t (*send_request) (protected_ike_sa_t *this,message_t * message);
295
296 /**
297 * @brief Send the next response message.
298 *
299 * Last stored responded message gets destroyed. Object gets not cloned!
300 *
301 * @param this calling object
302 * @param message pointer to the message which should be sent
303 * return
304 * - SUCCESS
305 * - FAILED if message id is not next expected one
306 */
307 status_t (*send_response) (protected_ike_sa_t *this,message_t * message);
308
309 /**
310 * @brief Send a notify reply message.
311 *
312 * @param this calling object
313 * @param exchange_type type of exchange in which the notify should be wrapped
314 * @param type type of the notify message to send
315 * @param data notification data
316 */
317 void (*send_notify) (protected_ike_sa_t *this, exchange_type_t exchange_type, notify_message_type_t type, chunk_t data);
318
319 /**
320 * @brief Get the internal stored randomizer_t object.
321 *
322 * @param this calling object
323 * @return pointer to the internal randomizer_t object
324 */
325 randomizer_t *(*get_randomizer) (protected_ike_sa_t *this);
326
327 /**
328 * @brief Set the new state_t object of the IKE_SA object.
329 *
330 * The old state_t object gets not destroyed. It's the callers duty to
331 * make sure old state is destroyed (Normally the old state is the caller).
332 *
333 * @param this calling object
334 * @param state pointer to the new state_t object
335 */
336 void (*set_new_state) (protected_ike_sa_t *this,state_t *state);
337
338 /**
339 * @brief Set the last replied message id.
340 *
341 * @param this calling object
342 * @param message_id message id
343 */
344 void (*set_last_replied_message_id) (protected_ike_sa_t *this,u_int32_t message_id);
345
346 /**
347 * @brief Get the internal stored initiator crypter_t object.
348 *
349 * @param this calling object
350 * @return pointer to crypter_t object
351 */
352 crypter_t *(*get_crypter_initiator) (protected_ike_sa_t *this);
353
354 /**
355 * @brief Get the internal stored initiator signer_t object.
356 *
357 * @param this calling object
358 * @return pointer to signer_t object
359 */
360 signer_t *(*get_signer_initiator) (protected_ike_sa_t *this);
361
362 /**
363 * @brief Get the internal stored responder crypter_t object.
364 *
365 * @param this calling object
366 * @return pointer to crypter_t object
367 */
368 crypter_t *(*get_crypter_responder) (protected_ike_sa_t *this);
369
370 /**
371 * @brief Get the internal stored responder signer object.
372 *
373 * @param this calling object
374 * @return pointer to signer_t object
375 */
376 signer_t *(*get_signer_responder) (protected_ike_sa_t *this);
377
378 /**
379 * @brief Get the multi purpose prf.
380 *
381 * @param this calling object
382 * @return pointer to prf_t object
383 */
384 prf_t *(*get_prf) (protected_ike_sa_t *this);
385
386 /**
387 * @brief Get the prf-object, which is used to derive keys for child SAs.
388 *
389 * @param this calling object
390 * @return pointer to prf_t object
391 */
392 prf_t *(*get_child_prf) (protected_ike_sa_t *this);
393
394 /**
395 * @brief Get the prf used for authentication of initiator.
396 *
397 * @param this calling object
398 * @return pointer to prf_t object
399 */
400 prf_t *(*get_prf_auth_i) (protected_ike_sa_t *this);
401
402 /**
403 * @brief Get the prf used for authentication of responder.
404 *
405 * @param this calling object
406 * @return pointer to prf_t object
407 */
408 prf_t *(*get_prf_auth_r) (protected_ike_sa_t *this);
409
410 /**
411 * @brief Associates a child SA to this IKE SA
412 *
413 * @param this calling object
414 * @param child_sa child_sa to add
415 */
416 void (*add_child_sa) (protected_ike_sa_t *this, child_sa_t *child_sa);
417
418 /**
419 * @brief Get the last responded message.
420 *
421 * @param this calling object
422 * @return
423 * - last received as message_t object
424 * - NULL if no last request available
425 */
426 message_t *(*get_last_responded_message) (protected_ike_sa_t *this);
427
428 /**
429 * @brief Get the last requested message.
430 *
431 * @param this calling object
432 * @return
433 * - last sent as message_t object
434 * - NULL if no last request available
435 */
436 message_t *(*get_last_requested_message) (protected_ike_sa_t *this);
437
438 /**
439 * @brief Resets message counters and does destroy stored received and sent messages.
440 *
441 * @param this calling object
442 */
443 void (*reset_message_buffers) (protected_ike_sa_t *this);
444 };
445
446
447 /**
448 * @brief Creates an ike_sa_t object with a specific ID.
449 *
450 * @warning the Content of internal ike_sa_id_t object can change over time
451 * e.g. when a IKE_SA_INIT has been finished.
452 *
453 * @param[in] ike_sa_id ike_sa_id_t object to associate with new IKE_SA.
454 * The object is internal getting cloned
455 * and so has to be destroyed by the caller.
456 * @return ike_sa_t object
457 *
458 * @ingroup sa
459 */
460 ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id);
461
462 #endif /*IKE_SA_H_*/