- fixed doxygen build
[strongswan.git] / Source / charon / config / connection.h
1 /**
2 * @file connection.h
3 *
4 * @brief Interface of connection_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 CONNECTION_H_
24 #define CONNECTION_H_
25
26 #include <types.h>
27 #include <utils/host.h>
28 #include <utils/linked_list.h>
29 #include <utils/identification.h>
30 #include <config/proposal.h>
31 #include <crypto/diffie_hellman.h>
32
33
34 typedef enum auth_method_t auth_method_t;
35
36 /**
37 * AUTH Method to use.
38 *
39 * @ingroup config
40 */
41 enum auth_method_t {
42 /**
43 * Computed as specified in section 2.15 of RFC using
44 * an RSA private key over a PKCS#1 padded hash.
45 */
46 RSA_DIGITAL_SIGNATURE = 1,
47
48 /**
49 * Computed as specified in section 2.15 of RFC using the
50 * shared key associated with the identity in the ID payload
51 * and the negotiated prf function
52 */
53 SHARED_KEY_MESSAGE_INTEGRITY_CODE = 2,
54
55 /**
56 * Computed as specified in section 2.15 of RFC using a
57 * DSS private key over a SHA-1 hash.
58 */
59 DSS_DIGITAL_SIGNATURE = 3,
60 };
61
62 /**
63 * string mappings for auth method.
64 *
65 * @ingroup config
66 */
67 extern mapping_t auth_method_m[];
68
69
70 typedef struct connection_t connection_t;
71
72 /**
73 * @brief A connection_t defines the rules to set up an IKE_SA.
74 *
75 *
76 * @b Constructors:
77 * - connection_create()
78 *
79 * @ingroup config
80 */
81 struct connection_t {
82
83 /**
84 * @brief Get my ID for this connection.
85 *
86 * Object is NOT getting cloned.
87 *
88 * @param this calling object
89 * @return host information as identification_t object
90 */
91 identification_t *(*get_my_id) (connection_t *this);
92
93 /**
94 * @brief Get others ID for this connection.
95 *
96 * Object is NOT getting cloned.
97 *
98 * @param this calling object
99 * @return host information as identification_t object
100 */
101 identification_t *(*get_other_id) (connection_t *this);
102
103 /**
104 * @brief Get my address as host_t object.
105 *
106 * Object is NOT getting cloned.
107 *
108 * @param this calling object
109 * @return host information as host_t object
110 */
111 host_t *(*get_my_host) (connection_t *this);
112
113 /**
114 * @brief Get others address as host_t object.
115 *
116 * Object is NOT getting cloned.
117 *
118 * @param this calling object
119 * @return host information as host_t object
120 */
121 host_t *(*get_other_host) (connection_t *this);
122
123 /**
124 * @brief Update address of my host.
125 *
126 * It may be necessary to uptdate own address, as it
127 * is set to the default route (0.0.0.0) in some cases.
128 * Old host is destroyed, new one NOT cloned.
129 *
130 * @param this calling object
131 * @param my_host new host to set as my_host
132 */
133 void (*update_my_host) (connection_t *this, host_t *my_host);
134
135 /**
136 * @brief Update address of remote host.
137 *
138 * It may be necessary to uptdate remote address, as a
139 * connection may define %any (0.0.0.0) or a subnet.
140 * Old host is destroyed, new one NOT cloned.
141 *
142 * @param this calling object
143 * @param my_host new host to set as other_host
144 */
145 void (*update_other_host) (connection_t *this, host_t *other_host);
146
147 /**
148 * @brief Returns a list of all supported proposals.
149 *
150 * Returned list is still owned by connection and MUST NOT
151 * modified or destroyed.
152 *
153 * @param this calling object
154 * @return list containing all the proposals
155 */
156 linked_list_t *(*get_proposals) (connection_t *this);
157
158 /**
159 * @brief Adds a proposal to the list.
160 *
161 * The first added proposal has the highest priority, the last
162 * added the lowest.
163 *
164 * @param this calling object
165 * @param proposal proposal to add
166 */
167 void (*add_proposal) (connection_t *this, proposal_t *proposal);
168
169 /**
170 * @brief Select a proposed from suggested proposals.
171 *
172 * Returned proposal must be destroyed after usage.
173 *
174 * @param this calling object
175 * @param proposals list of proposals to select from
176 * @return selected proposal, or NULL if none matches.
177 */
178 proposal_t *(*select_proposal) (connection_t *this, linked_list_t *proposals);
179
180 /**
181 * @brief Get the authentication method to use
182 *
183 * @param this calling object
184 * @return authentication method
185 */
186 auth_method_t (*get_auth_method) (connection_t *this);
187
188 /**
189 * @brief Get the DH group to use for connection initialization.
190 *
191 * @param this calling object
192 * @return dh group to use for initialization
193 */
194 diffie_hellman_group_t (*get_dh_group) (connection_t *this);
195
196 /**
197 * @brief Check if a suggested dh group is acceptable.
198 *
199 * If we guess a wrong DH group for IKE_SA_INIT, the other
200 * peer will send us a offer. But is this acceptable for us?
201 *
202 * @param this calling object
203 * @return TRUE if group acceptable
204 */
205 bool (*check_dh_group) (connection_t *this, diffie_hellman_group_t dh_group);
206
207 /**
208 * @brief Clone a connection_t object.
209 *
210 * @param this connection to clone
211 * @return clone of it
212 */
213 connection_t *(*clone) (connection_t *this);
214
215 /**
216 * @brief Destroys a connection_t object.
217 *
218 * @param this calling object
219 */
220 void (*destroy) (connection_t *this);
221 };
222
223 /**
224 * @brief Creates a connection_t object.
225 *
226 * Supplied hosts/IDs become owned by connection, so
227 * do not modify or destroy them after a call to
228 * connection_create().
229 *
230 * @param my_host host_t representing local address
231 * @param other_host host_t representing remote address
232 * @param my_id identification_t for me
233 * @param other_id identification_t for other
234 * @param auth_method Authentication method to use for our(!) auth data
235 * @return connection_t object.
236 *
237 * @ingroup config
238 */
239 connection_t * connection_create(host_t *my_host, host_t *other_host,
240 identification_t *my_id,
241 identification_t *other_id,
242 auth_method_t auth_method);
243
244 #endif /* CONNECTION_H_ */