Annotation of embedaddon/strongswan/src/libstrongswan/credentials/credential_manager.h, revision 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