daemon: Flush shunts before unloading plugins
[strongswan.git] / src / libstrongswan / credentials / credential_manager.h
1 /*
2 * Copyright (C) 2007-2009 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup credential_manager credential_manager
18 * @{ @ingroup credentials
19 */
20
21 #ifndef CREDENTIAL_MANAGER_H_
22 #define CREDENTIAL_MANAGER_H_
23
24 typedef struct credential_manager_t credential_manager_t;
25 typedef enum credential_hook_type_t credential_hook_type_t;
26
27 #include <utils/identification.h>
28 #include <collections/enumerator.h>
29 #include <credentials/auth_cfg.h>
30 #include <credentials/credential_set.h>
31 #include <credentials/keys/private_key.h>
32 #include <credentials/keys/shared_key.h>
33 #include <credentials/certificates/certificate.h>
34 #include <credentials/cert_validator.h>
35
36 /**
37 * Type of a credential hook error/event.
38 */
39 enum credential_hook_type_t {
40 /** The certificate has expired (or is not yet valid) */
41 CRED_HOOK_EXPIRED,
42 /** The certificate has been revoked */
43 CRED_HOOK_REVOKED,
44 /** Checking certificate revocation failed. This does not necessarily mean
45 * the certificate is rejected, just that revocation checking failed. */
46 CRED_HOOK_VALIDATION_FAILED,
47 /** No trusted issuer certificate has been found for this certificate */
48 CRED_HOOK_NO_ISSUER,
49 /** Encountered a self-signed (root) certificate, but it is not trusted */
50 CRED_HOOK_UNTRUSTED_ROOT,
51 /** Maximum trust chain length exceeded for certificate */
52 CRED_HOOK_EXCEEDED_PATH_LEN,
53 /** The certificate violates some other kind of policy and gets rejected */
54 CRED_HOOK_POLICY_VIOLATION,
55 };
56
57 /**
58 * Hook function to invoke on certificate validation errors.
59 *
60 * @param data user data supplied during hook registration
61 * @param type type of validation error/event
62 * @param cert associated certificate
63 */
64 typedef void (*credential_hook_t)(void *data, credential_hook_type_t type,
65 certificate_t *cert);
66
67 /**
68 * Manages credentials using credential_sets.
69 *
70 * The credential manager is the entry point of the credential framework. It
71 * uses so called "sets" to access credentials in a modular fashion. These
72 * are implemented through the credential_set_t interface.
73 * The manager additionally does trust chain verification and trust status
74 * caching. A set may call the managers methods if it needs credentials itself.
75 * The manager uses recursive locking.
76 *
77 * @verbatim
78
79 +-------+ +----------------+
80 | A | | | +------------------+
81 | u | -----> | | ------> | +------------------+
82 | t | | credential- | | | +------------------+
83 | h | -----> | manager | ------> +--| | credential- | => IPC
84 | e | | | +--| sets |
85 | n | +--> | | ------> +------------------+
86 | t | | | | |
87 | i | | | | |
88 | c | | +----------------+ |
89 | a | | |
90 | t | +----------------------------------------------+
91 | o | may be recursive
92 | r |
93 +-------+
94
95 @endverbatim
96 *
97 * The credential manager uses rwlocks for performance reasons. Credential
98 * sets must be fully thread-safe.
99 */
100 struct credential_manager_t {
101
102 /**
103 * Create an enumerator over all certificates.
104 *
105 * @param cert kind of certificate
106 * @param key kind of key in certificate
107 * @param id subject this certificate belongs to
108 * @param trusted TRUE to list trusted certificates only
109 * @return enumerator over the certificates
110 */
111 enumerator_t *(*create_cert_enumerator)(credential_manager_t *this,
112 certificate_type_t cert, key_type_t key,
113 identification_t *id, bool trusted);
114 /**
115 * Create an enumerator over all shared keys.
116 *
117 * The enumerator enumerates over:
118 * shared_key_t*, id_match_t me, id_match_t other
119 * But must accept values for the id_matches.
120 *
121 * @param type kind of requested shared key
122 * @param first first subject between key is shared
123 * @param second second subject between key is shared
124 * @return enumerator over (shared_key_t*,id_match_t,id_match_t)
125 */
126 enumerator_t *(*create_shared_enumerator)(credential_manager_t *this,
127 shared_key_type_t type,
128 identification_t *first, identification_t *second);
129 /**
130 * Create an enumerator over all Certificate Distribution Points.
131 *
132 * @param type kind of certificate the point distributes
133 * @param id identification of the distributed certificate
134 * @return enumerator of CDPs as char*
135 */
136 enumerator_t *(*create_cdp_enumerator)(credential_manager_t *this,
137 certificate_type_t type, identification_t *id);
138 /**
139 * Get a trusted or untrusted certificate.
140 *
141 * @param cert kind of certificate
142 * @param key kind of key in certificate
143 * @param id subject this certificate belongs to
144 * @param trusted TRUE to get a trusted certificate only
145 * @return certificate, if found, NULL otherwise
146 */
147 certificate_t *(*get_cert)(credential_manager_t *this,
148 certificate_type_t cert, key_type_t key,
149 identification_t *id, bool trusted);
150 /**
151 * Get the best matching shared key for two IDs.
152 *
153 * @param type kind of requested shared key
154 * @param me own identity
155 * @param other peer identity
156 * @return shared_key_t, NULL if none found
157 */
158 shared_key_t *(*get_shared)(credential_manager_t *this, shared_key_type_t type,
159 identification_t *me, identification_t *other);
160 /**
161 * Get a private key to create a signature.
162 *
163 * The get_private() method gets a secret private key identified by either
164 * the keyid itself or an id the key belongs to.
165 * The auth parameter contains additional information, such as recipients
166 * trusted CA certs. Auth gets filled with subject and CA certificates
167 * needed to validate a created signature.
168 *
169 * @param type type of the key to get
170 * @param id identification the key belongs to
171 * @param auth auth config, including trusted CA certificates
172 * @return private_key_t, NULL if none found
173 */
174 private_key_t* (*get_private)(credential_manager_t *this, key_type_t type,
175 identification_t *id, auth_cfg_t *auth);
176
177 /**
178 * Create an enumerator over trusted certificates.
179 *
180 * This method creates an enumerator over trusted certificates. The auth
181 * parameter (if given) receives the trustchain used to validate
182 * the certificate. The resulting enumerator enumerates over
183 * certificate_t*, auth_cfg_t*.
184 * If online is set, revocations are checked online for the whole
185 * trustchain.
186 *
187 * @param type type of the key we want a certificate for
188 * @param id subject of the certificate
189 * @param online whether revocations should be checked online
190 * @return enumerator
191 */
192 enumerator_t* (*create_trusted_enumerator)(credential_manager_t *this,
193 key_type_t type, identification_t *id, bool online);
194
195 /**
196 * Create an enumerator over trusted public keys.
197 *
198 * This method creates an enumerator over trusted public keys to verify a
199 * signature created by id. The auth parameter contains additional
200 * authentication infos, e.g. peer and intermediate certificates.
201 * The resulting enumerator enumerates over public_key_t *, auth_cfg_t *,
202 * where the auth config helper contains rules for constraint checks.
203 * This function is very similar to create_trusted_enumerator(), but
204 * gets public keys directly.
205 *
206 * @param type type of the key to get
207 * @param id owner of the key, signer of the signature
208 * @param auth authentication infos
209 * @return enumerator
210 */
211 enumerator_t* (*create_public_enumerator)(credential_manager_t *this,
212 key_type_t type, identification_t *id, auth_cfg_t *auth);
213
214 /**
215 * Cache a certificate by invoking cache_cert() on all registered sets.
216 *
217 * @param cert certificate to cache
218 */
219 void (*cache_cert)(credential_manager_t *this, certificate_t *cert);
220
221 /**
222 * Flush the certificate cache.
223 *
224 * Only the managers local cache is flushed, but not the sets cache filled
225 * by the cache_cert() method.
226 *
227 * @param type type of certificate to flush, or CERT_ANY
228 */
229 void (*flush_cache)(credential_manager_t *this, certificate_type_t type);
230
231 /**
232 * Check if a given subject certificate is issued by an issuer certificate.
233 *
234 * This operation does signature verification using the credential
235 * manager's cache to speed up the operation.
236 *
237 * @param subject subject certificate to check
238 * @param issuer issuer certificate that potentially has signed subject
239 * @param scheme receives used signature scheme, if given
240 * @return TRUE if issuer signed subject
241 */
242 bool (*issued_by)(credential_manager_t *this,
243 certificate_t *subject, certificate_t *issuer,
244 signature_scheme_t *scheme);
245
246 /**
247 * Register a credential set to the manager.
248 *
249 * @param set set to register
250 */
251 void (*add_set)(credential_manager_t *this, credential_set_t *set);
252
253 /**
254 * Unregister a credential set from the manager.
255 *
256 * @param set set to unregister
257 */
258 void (*remove_set)(credential_manager_t *this, credential_set_t *set);
259
260 /**
261 * Register a thread local credential set to the manager.
262 *
263 * To add a credential set for the current trustchain verification
264 * operation, sets may be added for the calling thread only. This
265 * does not require a write lock and is therefore a much cheaper
266 * operation.
267 * The exclusive option allows to disable all other credential sets
268 * until the set is deregistered.
269 *
270 * @param set set to register
271 * @param exclusive TRUE to disable all other sets for this thread
272 */
273 void (*add_local_set)(credential_manager_t *this, credential_set_t *set,
274 bool exclusive);
275
276 /**
277 * Unregister a thread local credential set from the manager.
278 *
279 * @param set set to unregister
280 */
281 void (*remove_local_set)(credential_manager_t *this, credential_set_t *set);
282
283 /**
284 * Register a certificate validator to the manager.
285 *
286 * @param vdtr validator to register
287 */
288 void (*add_validator)(credential_manager_t *this, cert_validator_t *vdtr);
289
290 /**
291 * Remove a certificate validator from the manager.
292 *
293 * @param vdtr validator to unregister
294 */
295 void (*remove_validator)(credential_manager_t *this, cert_validator_t *vdtr);
296
297 /**
298 * Set a hook to call on certain credential validation errors.
299 *
300 * @param hook hook to register, NULL to unregister
301 * @param data data to pass to hook
302 */
303 void (*set_hook)(credential_manager_t *this, credential_hook_t hook,
304 void *data);
305
306 /**
307 * Call the registered credential hook, if any.
308 *
309 * While hooks are usually called by the credential manager itself, some
310 * validator plugins might raise hooks as well if they consider certificates
311 * invalid.
312 *
313 * @param type type of the event
314 * @param cert associated certificate
315 */
316 void (*call_hook)(credential_manager_t *this, credential_hook_type_t type,
317 certificate_t *cert);
318
319 /**
320 * Destroy a credential_manager instance.
321 */
322 void (*destroy)(credential_manager_t *this);
323 };
324
325 /**
326 * Create a credential_manager instance.
327 */
328 credential_manager_t *credential_manager_create();
329
330 #endif /** CREDENTIAL_MANAGER_H_ @}*/