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