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
  26 #include <utils/identification.h>
  27 #include <utils/enumerator.h>
  28 #include <credentials/auth_cfg.h>
  29 #include <credentials/credential_set.h>
  30 #include <credentials/keys/private_key.h>
  31 #include <credentials/keys/shared_key.h>
  32 #include <credentials/certificates/certificate.h>
  33 #include <credentials/cert_validator.h>
  34
  35 /**
  36  * Manages credentials using credential_sets.
  37  *
  38  * The credential manager is the entry point of the credential framework. It
  39  * uses so called "sets" to access credentials in a modular fashion. These
  40  * are implemented through the credential_set_t interface.
  41  * The manager additionally does trust chain verification and trust status
  42  * caching. A set may call the managers methods if it needs credentials itself.
  43  * The manager uses recursive locking.
  44  *
  45  * @verbatim
  46
  47   +-------+        +----------------+
  48   |   A   |        |                |          +------------------+
  49   |   u   | -----> |                | ------>  |  +------------------+
  50   |   t   |        |   credential-  |          |  |  +------------------+
  51   |   h   | -----> |     manager    | ------>  +--|  |   credential-    | => IPC
  52   |   e   |        |                |             +--|       sets       |
  53   |   n   |   +--> |                | ------>        +------------------+
  54   |   t   |   |    |                |                        |
  55   |   i   |   |    |                |                        |
  56   |   c   |   |    +----------------+                        |
  57   |   a   |   |                                              |
  58   |   t   |   +----------------------------------------------+
  59   |   o   |                    may be recursive
  60   |   r   |
  61   +-------+
  62
  63    @endverbatim
  64  *
  65  * The credential manager uses rwlocks for performance reasons. Credential
  66  * sets must be fully thread-safe.
  67  */
  68 struct credential_manager_t {
  69
  70         /**
  71          * Create an enumerator over all certificates.
  72          *
  73          * @param cert          kind of certificate
  74          * @param key           kind of key in certificate
  75          * @param id            subject this certificate belongs to
  76          * @param trusted       TRUE to list trusted certificates only
  77          * @return                      enumerator over the certificates
  78          */
  79         enumerator_t *(*create_cert_enumerator)(credential_manager_t *this,
  80                                                                 certificate_type_t cert, key_type_t key,
  81                                                                 identification_t *id, bool trusted);
  82         /**
  83          * Create an enumerator over all shared keys.
  84          *
  85          * The enumerator enumerates over:
  86          *  shared_key_t*, id_match_t me, id_match_t other
  87          * But must accept values for the id_matches.
  88          *
  89          * @param type          kind of requested shared key
  90          * @param first         first subject between key is shared
  91          * @param second        second subject between key is shared
  92          * @return                      enumerator over shared keys
  93          */
  94         enumerator_t *(*create_shared_enumerator)(credential_manager_t *this,
  95                                                                 shared_key_type_t type,
  96                                                                 identification_t *first, identification_t *second);
  97         /**
  98          * Create an enumerator over all Certificate Distribution Points.
  99          *
 100          * @param type          kind of certificate the point distributes
 101          * @param id            identification of the distributed certificate
 102          * @return                      enumerator of CDPs as char*
 103          */
 104         enumerator_t *(*create_cdp_enumerator)(credential_manager_t *this,
 105                                                                 certificate_type_t type, identification_t *id);
 106         /**
 107          * Get a trusted or untrusted certificate.
 108          *
 109          * @param cert          kind of certificate
 110          * @param key           kind of key in certificate
 111          * @param id            subject this certificate belongs to
 112          * @param trusted       TRUE to get a trusted certificate only
 113          * @return                      certificate, if found, NULL otherwise
 114          */
 115         certificate_t *(*get_cert)(credential_manager_t *this,
 116                                                            certificate_type_t cert, key_type_t key,
 117                                                            identification_t *id, bool trusted);
 118         /**
 119          * Get the best matching shared key for two IDs.
 120          *
 121          * @param type          kind of requested shared key
 122          * @param me            own identity
 123          * @param other         peer identity
 124          * @return                      shared_key_t, NULL if none found
 125          */
 126         shared_key_t *(*get_shared)(credential_manager_t *this, shared_key_type_t type,
 127                                                                 identification_t *me, identification_t *other);
 128         /**
 129          * Get a private key to create a signature.
 130          *
 131          * The get_private() method gets a secret private key identified by either
 132          * the keyid itself or an id the key belongs to.
 133          * The auth parameter contains additional information, such as recipients
 134          * trusted CA certs. Auth gets filled with subject and CA certificates
 135          * needed to validate a created signature.
 136          *
 137          * @param type          type of the key to get
 138          * @param id            identification the key belongs to
 139          * @param auth          auth config, including trusted CA certificates
 140          * @return                      private_key_t, NULL if none found
 141          */
 142         private_key_t* (*get_private)(credential_manager_t *this, key_type_t type,
 143                                                                   identification_t *id, auth_cfg_t *auth);
 144
 145         /**
 146          * Create an enumerator over trusted certificates.
 147          *
 148          * This method creates an enumerator over trusted certificates. The auth
 149          * parameter (if given) receives the trustchain used to validate
 150          * the certificate. The resulting enumerator enumerates over
 151          * certificate_t*, auth_cfg_t*.
 152          * If online is set, revocations are checked online for the whole
 153          * trustchain.
 154          *
 155          * @param type          type of the key we want a certificate for
 156          * @param id            subject of the certificate
 157          * @param online        whether revocations should be checked online
 158          * @return                      enumerator
 159          */
 160         enumerator_t* (*create_trusted_enumerator)(credential_manager_t *this,
 161                                         key_type_t type, identification_t *id, bool online);
 162
 163         /**
 164          * Create an enumerator over trusted public keys.
 165          *
 166          * This method creates an enumerator over trusted public keys to verify a
 167          * signature created by id. The auth parameter contains additional
 168          * authentication infos, e.g. peer and intermediate certificates.
 169          * The resulting enumerator enumerates over public_key_t *, auth_cfg_t *,
 170          * where the auth config helper contains rules for constraint checks.
 171          * This function is very similar to create_trusted_enumerator(), but
 172          * gets public keys directly.
 173          *
 174          * @param type          type of the key to get
 175          * @param id            owner of the key, signer of the signature
 176          * @param auth          authentication infos
 177          * @return                      enumerator
 178          */
 179         enumerator_t* (*create_public_enumerator)(credential_manager_t *this,
 180                                         key_type_t type, identification_t *id, auth_cfg_t *auth);
 181
 182         /**
 183          * Cache a certificate by invoking cache_cert() on all registered sets.
 184          *
 185          * @param cert          certificate to cache
 186          */
 187         void (*cache_cert)(credential_manager_t *this, certificate_t *cert);
 188
 189         /**
 190          * Flush the certificate cache.
 191          *
 192          * Only the managers local cache is flushed, but not the sets cache filled
 193          * by the cache_cert() method.
 194          *
 195          * @param type          type of certificate to flush, or CERT_ANY
 196          */
 197         void (*flush_cache)(credential_manager_t *this, certificate_type_t type);
 198
 199         /**
 200          * Check if a given subject certificate is issued by an issuer certificate.
 201          *
 202          * This operation does signature verification using the credential
 203          * manager's cache to speed up the operation.
 204          *
 205          * @param subject       subject certificate to check
 206          * @param issuer        issuer certificate that potentially has signed subject
 207          * @return                      TRUE if issuer signed subject
 208          */
 209         bool (*issued_by)(credential_manager_t *this,
 210                                           certificate_t *subject, certificate_t *issuer);
 211
 212         /**
 213          * Register a credential set to the manager.
 214          *
 215          * @param set           set to register
 216          */
 217         void (*add_set)(credential_manager_t *this, credential_set_t *set);
 218
 219         /**
 220          * Unregister a credential set from the manager.
 221          *
 222          * @param set           set to unregister
 223          */
 224         void (*remove_set)(credential_manager_t *this, credential_set_t *set);
 225
 226         /**
 227          * Register a thread local credential set to the manager.
 228          *
 229          * To add a credential set for the current trustchain verification
 230          * operation, sets may be added for the calling thread only. This
 231          * does not require a write lock and is therefore a much cheaper
 232          * operation.
 233          *
 234          * @param set           set to register
 235          */
 236         void (*add_local_set)(credential_manager_t *this, credential_set_t *set);
 237
 238         /**
 239          * Unregister a thread local credential set from the manager.
 240          *
 241          * @param set           set to unregister
 242          */
 243         void (*remove_local_set)(credential_manager_t *this, credential_set_t *set);
 244
 245         /**
 246          * Register a certificate validator to the manager.
 247          *
 248          * @param vdtr          validator to register
 249          */
 250         void (*add_validator)(credential_manager_t *this, cert_validator_t *vdtr);
 251
 252         /**
 253          * Remove a certificate validator from the manager.
 254          *
 255          * @param vdtr          validator to unregister
 256          */
 257         void (*remove_validator)(credential_manager_t *this, cert_validator_t *vdtr);
 258
 259         /**
 260          * Destroy a credential_manager instance.
 261          */
 262         void (*destroy)(credential_manager_t *this);
 263 };
 264
 265 /**
 266  * Create a credential_manager instance.
 267  */
 268 credential_manager_t *credential_manager_create();
 269
 270 #endif /** CREDENTIAL_MANAGER_H_ @}*/