c001afb14f823545165ad0b8cf1d6327fb84ffeb
[strongswan.git] / Source / 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 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_MANAGER_H_
24 #define IKE_SA_MANAGER_H_
25
26 #include <types.h>
27 #include <sa/ike_sa.h>
28
29
30 typedef struct ike_sa_manager_t ike_sa_manager_t;
31
32 /**
33 * @brief The IKE_SA-Manager manages the IKE_SAs ;-).
34 *
35 * To avoid access from multiple threads, IKE_SAs must be checked out from
36 * the manager, and checked in after usage.
37 * The manager also handles deletion of SAs.
38 *
39 * @todo checking of double-checkouts from the same threads would be nice.
40 * This could be by comparing thread-ids via pthread_self()...
41 *
42 * @ingroup sa
43 */
44 struct ike_sa_manager_t {
45 /**
46 * @brief Checkout an IKE_SA, create it when necesarry
47 *
48 * Checks out a SA by its ID. An SA will be created, when:
49 * - Responder SPI is not set (when received an IKE_SA_INIT from initiator)
50 * Management of SPIs is the managers job, he will set it.
51 * This function blocks until SA is available for checkout.
52 *
53 * @warning checking out two times without checking in will
54 * result in a deadlock!
55 *
56 * @param ike_sa_manager the manager object
57 * @param ike_sa_id[in/out] the SA identifier, will be updated
58 * @param ike_sa[out] checked out SA
59 * @returns
60 * - SUCCESS if checkout successful
61 * - NOT_FOUND when no such SA is available
62 * - CREATED if a new IKE_SA got created
63 */
64 status_t (*checkout) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
65
66 /**
67 * @brief Create and checkout an IKE_SA as original initator.
68 *
69 * Creates and checks out a SA as initiator. An SA will be created, when:
70 * Management of SPIs is the managers job, he will set it.
71 *
72 * @warning checking out two times without checking in will
73 * result in a deadlock!
74 *
75 * @param ike_sa_manager the manager object
76 * @param ike_sa[out] checked out SA
77 */
78 void (*create_and_checkout) (ike_sa_manager_t* ike_sa_manager,ike_sa_t **ike_sa);
79
80 /**
81 * @brief Checkin the SA after usage
82 *
83 * @warning the SA pointer MUST NOT be used after checkin!
84 * The SA must be checked out again!
85 *
86 * @param ike_sa_manager the manager object
87 * @param ike_sa_id[in/out] the SA identifier, will be updated
88 * @param ike_sa[out] checked out SA
89 * @returns
90 * - SUCCESS if checked in
91 * - NOT_FOUND when not found (shouldn't happen!)
92 */
93 status_t (*checkin) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
94 /**
95 * @brief delete a SA, wich was not checked out
96 *
97 * @warning do not use this when the SA is already checked out, this will
98 * deadlock!
99 *
100 * @param ike_sa_manager the manager object
101 * @param ike_sa_id[in/out] the SA identifier
102 * @returns
103 * - SUCCESS if found
104 * - NOT_FOUND when no such SA is available
105 */
106 status_t (*delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *ike_sa_id);
107
108 /**
109 * @brief delete a checked out SA
110 *
111 * @param ike_sa_manager the manager object
112 * @param ike_sa SA to delete
113 * @returns
114 * - SUCCESS if found
115 * - NOT_FOUND when no such SA is available
116 */
117 status_t (*checkin_and_delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
118
119 /**
120 * @brief Destroys the manager with all associated SAs
121 *
122 * Threads will be driven out, so all SAs can be deleted cleanly
123 *
124 * @param ike_sa_manager the manager object
125 */
126 void (*destroy) (ike_sa_manager_t *ike_sa_manager);
127 };
128
129 /**
130 * @brief Create a manager
131 *
132 * @returns the created manager
133 *
134 * @ingroup sa
135 */
136 ike_sa_manager_t *ike_sa_manager_create();
137
138 #endif /*IKE_SA_MANAGER_H_*/