Some documentation corrections
[strongswan.git] / src / libstrongswan / credentials / credential_manager.h
index aa0c488..8e8f04b 100644 (file)
@@ -30,16 +30,17 @@ typedef struct credential_manager_t credential_manager_t;
 #include <credentials/keys/private_key.h>
 #include <credentials/keys/shared_key.h>
 #include <credentials/certificates/certificate.h>
+#include <credentials/cert_validator.h>
 
 /**
  * Manages credentials using credential_sets.
  *
  * The credential manager is the entry point of the credential framework. It
- * uses so called "sets" to access credentials in a modular fashion, these
+ * uses so called "sets" to access credentials in a modular fashion. These
  * are implemented through the credential_set_t interface.
  * The manager additionally does trust chain verification and trust status
- * chaching. A set may call the managers methods if it needs credentials itself,
- * the manager uses recursive locking.
+ * caching. A set may call the managers methods if it needs credentials itself.
+ * The manager uses recursive locking.
  *
  * @verbatim
 
@@ -61,8 +62,8 @@ typedef struct credential_manager_t credential_manager_t;
 
    @endverbatim
  *
- * The credential manager uses rwlocks for performance reasons, credential
- * sets must be fully thread save.
+ * The credential manager uses rwlocks for performance reasons. Credential
+ * sets must be fully thread-safe.
  */
 struct credential_manager_t {
 
@@ -83,7 +84,7 @@ struct credential_manager_t {
         *
         * The enumerator enumerates over:
         *  shared_key_t*, id_match_t me, id_match_t other
-        * But must accepts values for the id_matches.
+        * But must accept values for the id_matches.
         *
         * @param type          kind of requested shared key
         * @param first         first subject between key is shared
@@ -119,7 +120,7 @@ struct credential_manager_t {
         *
         * @param type          kind of requested shared key
         * @param me            own identity
-        * @param other         peers identity
+        * @param other         peer identity
         * @return                      shared_key_t, NULL if none found
         */
        shared_key_t *(*get_shared)(credential_manager_t *this, shared_key_type_t type,
@@ -129,7 +130,7 @@ struct credential_manager_t {
         *
         * The get_private() method gets a secret private key identified by either
         * the keyid itself or an id the key belongs to.
-        * The auth parameter contains additional information, such as receipients
+        * The auth parameter contains additional information, such as recipients
         * trusted CA certs. Auth gets filled with subject and CA certificates
         * needed to validate a created signature.
         *
@@ -142,13 +143,33 @@ struct credential_manager_t {
                                                                  identification_t *id, auth_cfg_t *auth);
 
        /**
+        * Create an enumerator over trusted certificates.
+        *
+        * This method creates an enumerator over trusted certificates. The auth
+        * parameter (if given) receives the trustchain used to validate
+        * the certificate. The resulting enumerator enumerates over
+        * certificate_t*, auth_cfg_t*.
+        * If online is set, revocations are checked online for the whole
+        * trustchain.
+        *
+        * @param type          type of the key we want a certificate for
+        * @param id            subject of the certificate
+        * @param online        whether revocations should be checked online
+        * @return                      enumerator
+        */
+       enumerator_t* (*create_trusted_enumerator)(credential_manager_t *this,
+                                       key_type_t type, identification_t *id, bool online);
+
+       /**
         * Create an enumerator over trusted public keys.
         *
-        * This method gets a an enumerator over trusted public keys to verify a
+        * This method creates an enumerator over trusted public keys to verify a
         * signature created by id. The auth parameter contains additional
         * authentication infos, e.g. peer and intermediate certificates.
         * The resulting enumerator enumerates over public_key_t *, auth_cfg_t *,
         * where the auth config helper contains rules for constraint checks.
+        * This function is very similar to create_trusted_enumerator(), but
+        * gets public keys directly.
         *
         * @param type          type of the key to get
         * @param id            owner of the key, signer of the signature
@@ -159,7 +180,7 @@ struct credential_manager_t {
                                        key_type_t type, identification_t *id, auth_cfg_t *auth);
 
        /**
-        * Cache a certificate by invoking cache_cert() on all registerd sets.
+        * Cache a certificate by invoking cache_cert() on all registered sets.
         *
         * @param cert          certificate to cache
         */
@@ -176,6 +197,19 @@ struct credential_manager_t {
        void (*flush_cache)(credential_manager_t *this, certificate_type_t type);
 
        /**
+        * Check if a given subject certificate is issued by an issuer certificate.
+        *
+        * This operation does signature verification using the credential
+        * manager's cache to speed up the operation.
+        *
+        * @param subject       subject certificate to check
+        * @param issuer        issuer certificate that potentially has signed subject
+        * @return                      TRUE if issuer signed subject
+        */
+       bool (*issued_by)(credential_manager_t *this,
+                                         certificate_t *subject, certificate_t *issuer);
+
+       /**
         * Register a credential set to the manager.
         *
         * @param set           set to register
@@ -190,6 +224,39 @@ struct credential_manager_t {
        void (*remove_set)(credential_manager_t *this, credential_set_t *set);
 
        /**
+        * Register a thread local credential set to the manager.
+        *
+        * To add a credential set for the current trustchain verification
+        * operation, sets may be added for the calling thread only. This
+        * does not require a write lock and is therefore a much cheaper
+        * operation.
+        *
+        * @param set           set to register
+        */
+       void (*add_local_set)(credential_manager_t *this, credential_set_t *set);
+
+       /**
+        * Unregister a thread local credential set from the manager.
+        *
+        * @param set           set to unregister
+        */
+       void (*remove_local_set)(credential_manager_t *this, credential_set_t *set);
+
+       /**
+        * Register a certificate validator to the manager.
+        *
+        * @param vdtr          validator to register
+        */
+       void (*add_validator)(credential_manager_t *this, cert_validator_t *vdtr);
+
+       /**
+        * Remove a certificate validator from the manager.
+        *
+        * @param vdtr          validator to unregister
+        */
+       void (*remove_validator)(credential_manager_t *this, cert_validator_t *vdtr);
+
+       /**
         * Destroy a credential_manager instance.
         */
        void (*destroy)(credential_manager_t *this);