reuse an existing IKE_SA to set up additional CHILD_SAs
[strongswan.git] / src / charon / sa / ike_sa_manager.h
1 /**
2 * @file ike_sa_manager.h
3 *
4 * @brief Interface of ike_sa_manager_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef IKE_SA_MANAGER_H_
25 #define IKE_SA_MANAGER_H_
26
27 #include <types.h>
28 #include <sa/ike_sa.h>
29 #include <utils/logger.h>
30
31
32 typedef struct ike_sa_manager_t ike_sa_manager_t;
33
34 /**
35 * @brief The IKE_SA-Manager is responsible for managing all initiated and responded IKE_SA's.
36 *
37 * To avoid access from multiple threads, IKE_SAs must be checked out from
38 * the manager, and checked in after usage.
39 * The manager also handles deletion of SAs.
40 *
41 * @todo checking of double-checkouts from the same threads would be nice.
42 * This could be done by comparing thread-ids via pthread_self()...
43 *
44 * @todo Managing of ike_sa_t objects in a hash table instead of linked list.
45 *
46 * @b Constructors:
47 * - ike_sa_manager_create()
48 *
49 * @ingroup sa
50 */
51 struct ike_sa_manager_t {
52 /**
53 * @brief Checkout an IKE_SA, create it when necesarry.
54 *
55 * Checks out a SA by its ID. An SA will be created, when the responder
56 * SPI is not set (when received an IKE_SA_INIT from initiator).
57 * Management of SPIs is the managers job, he will set it.
58 * This function blocks until SA is available for checkout.
59 *
60 * @warning checking out two times without checking in will
61 * result in a deadlock!
62 *
63 * @param this the manager object
64 * @param[in/out] ike_sa_id the SA identifier, will be updated
65 * @returns
66 * - checked out IKE_SA if found
67 * - NULL, if no such IKE_SA available
68 */
69 ike_sa_t* (*checkout) (ike_sa_manager_t* this, ike_sa_id_t *sa_id);
70
71 /**
72 * @brief Checkout an IKE_SA by two identifications.
73 *
74 * Allows the lookup of an IKE_SA by two user IDs. It returns the
75 * first found occurence, if there are multiple canddates. Supplied IDs
76 * may contain wildcards. If no IKE_SA is found, a new one is created.
77 *
78 * @param this the manager object
79 * @param my_id ID used by us
80 * @param other_id ID used by other
81 * @return checked out/created IKE_SA
82 */
83 ike_sa_t* (*checkout_by_ids) (ike_sa_manager_t* this,
84 identification_t *my_id,
85 identification_t *other_id);
86
87 /**
88 * @brief Check out an IKE_SA by protocol and SPI of one of its CHILD_SA.
89 *
90 * The kernel sends us expire messages for IPsec SAs. To fullfill
91 * this request, we must check out the IKE SA which contains the
92 * CHILD_SA the kernel wants to modify.
93 *
94 * @param this the manager object
95 * @param protocol protocol of the CHILD_SA
96 * @param spi SPI of the CHILD_SA
97 * @param[out] ike_sa checked out SA
98 * @return
99 * - NOT_FOUND, if no IKE SA with such a child found
100 * - SUCCESS, if ike_sa set
101 */
102 status_t (*checkout_by_child) (ike_sa_manager_t* this, protocol_id_t protocol,
103 u_int32_t spi, ike_sa_t **ike_sa);
104
105 /**
106 * @brief Get a list of all IKE_SA SAs currently set up.
107 *
108 * The resulting list with all IDs must be destroyed by
109 * the caller. There is no guarantee an ike_sa with the
110 * corrensponding ID really exists, since it may be deleted
111 * in the meantime by another thread.
112 *
113 * @param this the manager object
114 * @return a list with ike_sa_id_t s
115 */
116 linked_list_t *(*get_ike_sa_list) (ike_sa_manager_t* this);
117
118 /**
119 * @brief Get a list of all IKE_SA SAs currently set up specified
120 * by the connections name.
121 *
122 * @param this the manager object
123 * @return a list with ike_sa_id_t s
124 */
125 linked_list_t *(*get_ike_sa_list_by_name) (ike_sa_manager_t* this, const char *name);
126
127 /**
128 * @brief Log the status of the IKE_SA's in the manager.
129 *
130 * A informational log is done to the supplied logger. If logger is
131 * NULL, an internal logger is used. If a name is supplied,
132 * only connections with the matching name will be logged.
133 *
134 * @param this the manager object
135 * @param logger logger to do the log, or NULL
136 * @param name name of a connection, or NULL
137 */
138 void (*log_status) (ike_sa_manager_t* this, logger_t* logger, char* name);
139
140 /**
141 * @brief Checkin the SA after usage.
142 *
143 * @warning the SA pointer MUST NOT be used after checkin!
144 * The SA must be checked out again!
145 *
146 * @param this the manager object
147 * @param[in/out] ike_sa_id the SA identifier, will be updated
148 * @param[out] ike_sa checked out SA
149 * @returns
150 * - SUCCESS if checked in
151 * - NOT_FOUND when not found (shouldn't happen!)
152 */
153 status_t (*checkin) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
154
155 /**
156 * @brief Delete a SA, which was not checked out.
157 *
158 * If the state allows it, the IKE SA is destroyed immediately. If it is
159 * in the state ESTABLSIHED, a delete message
160 * is sent to the remote peer, which has to be acknowledged.
161 *
162 * @warning do not use this when the SA is already checked out, this will
163 * deadlock!
164 *
165 * @param this the manager object
166 * @param[in/out] ike_sa_id the SA identifier
167 * @returns
168 * - SUCCESS if found
169 * - NOT_FOUND when no such SA is available
170 */
171 status_t (*delete) (ike_sa_manager_t* this, ike_sa_id_t *ike_sa_id);
172
173 /**
174 * @brief Destroy a checked out SA.
175 *
176 * The IKE SA is destroyed without notification of the remote peer.
177 * Use this only if the other peer doesn't respond or behaves not
178 * as predicted.
179 * Checking in and destruction is an atomic operation (for the IKE_SA),
180 * so this can be called if the SA is in a "unclean" state, without the
181 * risk that another thread can get the SA.
182 *
183 * @param this the manager object
184 * @param ike_sa SA to delete
185 * @returns
186 * - SUCCESS if found
187 * - NOT_FOUND when no such SA is available
188 */
189 status_t (*checkin_and_destroy) (ike_sa_manager_t* this, ike_sa_t *ike_sa);
190
191 /**
192 * @brief Destroys the manager with all associated SAs.
193 *
194 * Threads will be driven out, so all SAs can be deleted cleanly.
195 *
196 * @param this the manager object
197 */
198 void (*destroy) (ike_sa_manager_t *this);
199 };
200
201 /**
202 * @brief Create a manager.
203 *
204 * @returns ike_sa_manager_t object
205 *
206 * @ingroup sa
207 */
208 ike_sa_manager_t *ike_sa_manager_create(void);
209
210 #endif /*IKE_SA_MANAGER_H_*/