- some logging improvements and cosmetics
[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 * - DESTROY_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 * - DESTROY_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 Get the id of the SA.
108 *
109 * Returned ike_sa_id_t object is not getting cloned!
110 *
111 * @param this calling object
112 * @return ike_sa's ike_sa_id_t
113 */
114 ike_sa_id_t* (*get_id) (ike_sa_t *this);
115
116 /**
117 * @brief Get local peer address of the IKE_SA.
118 *
119 * @param this calling object
120 * @return local host_t
121 */
122 host_t* (*get_my_host) (ike_sa_t *this);
123
124 /**
125 * @brief Get remote peer address of the IKE_SA.
126 *
127 * @param this calling object
128 * @return remote host_t
129 */
130 host_t* (*get_other_host) (ike_sa_t *this);
131
132 /**
133 * @brief Get own ID of the IKE_SA.
134 *
135 * @param this calling object
136 * @return local identification_t
137 */
138 identification_t* (*get_my_id) (ike_sa_t *this);
139
140 /**
141 * @brief Get remote ID the IKE_SA.
142 *
143 * @param this calling object
144 * @return remote identification_t
145 */
146 identification_t* (*get_other_id) (ike_sa_t *this);
147
148 /**
149 * @brief Get the connection of the IKE_SA.
150 *
151 * The internal used connection specification
152 * can be queried to get some data of an IKE_SA.
153 * The connection is still owned to the IKE_SA
154 * and must not be manipulated.
155 *
156 * @param this calling object
157 * @return connection_t
158 */
159 connection_t* (*get_connection) (ike_sa_t *this);
160
161 /**
162 * @brief Get the state of type of associated state object.
163 *
164 * @param this calling object
165 * @return state of IKE_SA
166 */
167 ike_sa_state_t (*get_state) (ike_sa_t *this);
168
169 /**
170 * @brief Log the status of a the ike sa to a logger.
171 *
172 * The status of the IKE SA and all child SAs is logged.
173 * Supplying NULL as logger uses the internal child_sa logger
174 * to do the logging. The log is only done if the supplied
175 * connection name is NULL or matches the connections name.
176 *
177 * @param this calling object
178 * @param logger logger to use for logging
179 * @param name name of the connection
180 */
181 void (*log_status) (ike_sa_t *this, logger_t *logger, char *name);
182
183 /**
184 * @brief Initiates the deletion of an IKE_SA.
185 *
186 * Sends a delete message to the remote peer and waits for
187 * its response. If the response comes in, or a timeout occur,
188 * the IKE SA gets deleted.
189 *
190 * @param this calling object
191 * @return
192 * - SUCCESS if deletion is initialized
193 * - INVALID_STATE, if the IKE_SA is not in
194 * an established state and can not be
195 * delete (but destroyed).
196 */
197 status_t (*delete) (ike_sa_t *this);
198
199 /**
200 * @brief Destroys a ike_sa_t object.
201 *
202 * @param this calling object
203 */
204 void (*destroy) (ike_sa_t *this);
205 };
206
207
208 typedef struct protected_ike_sa_t protected_ike_sa_t;
209
210 /**
211 * @brief Protected functions of an ike_sa_t object.
212 *
213 * This members are only accessed out from
214 * the various state_t implementations.
215 *
216 * @ingroup sa
217 */
218 struct protected_ike_sa_t {
219
220 /**
221 * Public interface of an ike_sa_t object.
222 */
223 ike_sa_t public;
224
225 /**
226 * @brief Build an empty IKEv2-Message and fills in default informations.
227 *
228 * Depending on the type of message (request or response), the message id is
229 * either message_id_out or message_id_in.
230 *
231 * Used in state_t Implementation to build an empty IKEv2-Message.
232 *
233 * @param this calling object
234 * @param type exchange type of new message
235 * @param request TRUE, if message has to be a request
236 * @param message new message is stored at this location
237 */
238 void (*build_message) (protected_ike_sa_t *this, exchange_type_t type, bool request, message_t **message);
239
240 /**
241 * @brief Get the internal stored connection_t object.
242 *
243 * @param this calling object
244 * @return pointer to the internal stored connection_t object
245 */
246 connection_t *(*get_connection) (protected_ike_sa_t *this);
247
248 /**
249 * @brief Set the internal connection object.
250 *
251 * @param this calling object
252 * @param connection object of type connection_t
253 */
254 void (*set_connection) (protected_ike_sa_t *this, connection_t *connection);
255
256 /**
257 * @brief Get the internal stored policy object.
258 *
259 * @param this calling object
260 * @return pointer to the internal stored policy_t object
261 */
262 policy_t *(*get_policy) (protected_ike_sa_t *this);
263
264 /**
265 * @brief Set the internal policy_t object.
266 *
267 * @param this calling object
268 * @param policy object of type policy_t
269 */
270 void (*set_policy) (protected_ike_sa_t *this,policy_t *policy);
271
272 /**
273 * @brief Derive all keys and create the transforms for IKE communication.
274 *
275 * Keys are derived using the diffie hellman secret, nonces and internal
276 * stored SPIs.
277 * Already existing objects get destroyed.
278 *
279 * @param this calling object
280 * @param proposal proposal which contains algorithms to use
281 * @param dh diffie hellman object with shared secret
282 * @param nonce_i initiators nonce
283 * @param nonce_r responders nonce
284 */
285 status_t (*build_transforms) (protected_ike_sa_t *this, proposal_t* proposal,
286 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
287
288 /**
289 * @brief Send the next request message.
290 *
291 * Also the first retransmit job is created.
292 *
293 * Last stored requested message gets destroyed. Object gets not cloned!
294 *
295 * @param this calling object
296 * @param message pointer to the message which should be sent
297 * @return
298 * - SUCCESS
299 * - FAILED if message id is not next expected one
300 */
301 status_t (*send_request) (protected_ike_sa_t *this,message_t * message);
302
303 /**
304 * @brief Send the next response message.
305 *
306 * Last stored responded message gets destroyed. Object gets not cloned!
307 *
308 * @param this calling object
309 * @param message pointer to the message which should be sent
310 * return
311 * - SUCCESS
312 * - FAILED if message id is not next expected one
313 */
314 status_t (*send_response) (protected_ike_sa_t *this,message_t * message);
315
316 /**
317 * @brief Send a notify reply message.
318 *
319 * @param this calling object
320 * @param exchange_type type of exchange in which the notify should be wrapped
321 * @param type type of the notify message to send
322 * @param data notification data
323 */
324 void (*send_notify) (protected_ike_sa_t *this, exchange_type_t exchange_type, notify_message_type_t type, chunk_t data);
325
326 /**
327 * @brief Get the internal stored randomizer_t object.
328 *
329 * @param this calling object
330 * @return pointer to the internal randomizer_t object
331 */
332 randomizer_t *(*get_randomizer) (protected_ike_sa_t *this);
333
334 /**
335 * @brief Set the new state_t object of the IKE_SA object.
336 *
337 * The old state_t object gets not destroyed. It's the callers duty to
338 * make sure old state is destroyed (Normally the old state is the caller).
339 *
340 * @param this calling object
341 * @param state pointer to the new state_t object
342 */
343 void (*set_new_state) (protected_ike_sa_t *this,state_t *state);
344
345 /**
346 * @brief Set the last replied message id.
347 *
348 * @param this calling object
349 * @param message_id message id
350 */
351 void (*set_last_replied_message_id) (protected_ike_sa_t *this,u_int32_t message_id);
352
353 /**
354 * @brief Get the internal stored initiator crypter_t object.
355 *
356 * @param this calling object
357 * @return pointer to crypter_t object
358 */
359 crypter_t *(*get_crypter_initiator) (protected_ike_sa_t *this);
360
361 /**
362 * @brief Get the internal stored initiator signer_t object.
363 *
364 * @param this calling object
365 * @return pointer to signer_t object
366 */
367 signer_t *(*get_signer_initiator) (protected_ike_sa_t *this);
368
369 /**
370 * @brief Get the internal stored responder crypter_t object.
371 *
372 * @param this calling object
373 * @return pointer to crypter_t object
374 */
375 crypter_t *(*get_crypter_responder) (protected_ike_sa_t *this);
376
377 /**
378 * @brief Get the internal stored responder signer object.
379 *
380 * @param this calling object
381 * @return pointer to signer_t object
382 */
383 signer_t *(*get_signer_responder) (protected_ike_sa_t *this);
384
385 /**
386 * @brief Get the multi purpose prf.
387 *
388 * @param this calling object
389 * @return pointer to prf_t object
390 */
391 prf_t *(*get_prf) (protected_ike_sa_t *this);
392
393 /**
394 * @brief Get the prf-object, which is used to derive keys for child SAs.
395 *
396 * @param this calling object
397 * @return pointer to prf_t object
398 */
399 prf_t *(*get_child_prf) (protected_ike_sa_t *this);
400
401 /**
402 * @brief Get the prf used for authentication of initiator.
403 *
404 * @param this calling object
405 * @return pointer to prf_t object
406 */
407 prf_t *(*get_prf_auth_i) (protected_ike_sa_t *this);
408
409 /**
410 * @brief Get the prf used for authentication of responder.
411 *
412 * @param this calling object
413 * @return pointer to prf_t object
414 */
415 prf_t *(*get_prf_auth_r) (protected_ike_sa_t *this);
416
417 /**
418 * @brief Associates a child SA to this IKE SA
419 *
420 * @param this calling object
421 * @param child_sa child_sa to add
422 */
423 void (*add_child_sa) (protected_ike_sa_t *this, child_sa_t *child_sa);
424
425 /**
426 * @brief Get the last responded message.
427 *
428 * @param this calling object
429 * @return
430 * - last received as message_t object
431 * - NULL if no last request available
432 */
433 message_t *(*get_last_responded_message) (protected_ike_sa_t *this);
434
435 /**
436 * @brief Get the last requested message.
437 *
438 * @param this calling object
439 * @return
440 * - last sent as message_t object
441 * - NULL if no last request available
442 */
443 message_t *(*get_last_requested_message) (protected_ike_sa_t *this);
444
445 /**
446 * @brief Resets message counters and does destroy stored received and sent messages.
447 *
448 * @param this calling object
449 */
450 void (*reset_message_buffers) (protected_ike_sa_t *this);
451 };
452
453
454 /**
455 * @brief Creates an ike_sa_t object with a specific ID.
456 *
457 * @warning the Content of internal ike_sa_id_t object can change over time
458 * e.g. when a IKE_SA_INIT has been finished.
459 *
460 * @param[in] ike_sa_id ike_sa_id_t object to associate with new IKE_SA.
461 * The object is internal getting cloned
462 * and so has to be destroyed by the caller.
463 * @return ike_sa_t object
464 *
465 * @ingroup sa
466 */
467 ike_sa_t * ike_sa_create(ike_sa_id_t *ike_sa_id);
468
469 #endif /*IKE_SA_H_*/