saml/security/AbstractPKIXTrustEngine.h

   1 /*\r
   2  *  Copyright 2001-2006 Internet2\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *     http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 /**\r
  18  * @file saml/security/AbstractPKIXTrustEngine.h\r
  19  * \r
  20  * A trust engine that uses X.509 trust anchors and CRLs associated with a role\r
  21  * to perform PKIX validation of signatures and certificates.\r
  22  */\r
  23 \r
  24 #ifndef __saml_pkixtrust_h__\r
  25 #define __saml_pkixtrust_h__\r
  26 \r
  27 #include <saml/security/X509TrustEngine.h>\r
  28 #include <xmltooling/security/XSECCryptoX509CRL.h>\r
  29 \r
  30 namespace opensaml {\r
  31 \r
  32     /**\r
  33      * A trust engine that uses X.509 trust anchors and CRLs associated with a role\r
  34      * to perform PKIX validation of signatures and certificates.\r
  35      */\r
  36     class SAML_API AbstractPKIXTrustEngine : public X509TrustEngine\r
  37     {\r
  38     protected:\r
  39         /**\r
  40          * Constructor.\r
  41          * \r
  42          * If a DOM is supplied, the following XML content is supported:\r
  43          * \r
  44          * <ul>\r
  45          *  <li>&lt;KeyResolver&gt; elements with a type attribute\r
  46          * </ul>\r
  47          * \r
  48          * XML namespaces are ignored in the processing of this content.\r
  49          * \r
  50          * @param e DOM to supply configuration for provider\r
  51          */\r
  52         AbstractPKIXTrustEngine(const DOMElement* e=NULL);\r
  53         \r
  54         /**\r
  55          * Checks that either the ID for the entity with the given role or the key names\r
  56          * for the given role match the subject or subject alternate names\r
  57          * of the entity's certificate.\r
  58          * \r
  59          * @param certEE    the credential for the entity to validate\r
  60          * @param role      the descriptor of the role the entity is supposed to be acting in\r
  61          * \r
  62          * @return true the name check succeeds, false if not\r
  63          */\r
  64         bool checkEntityNames(XSECCryptoX509* certEE, const saml2md::RoleDescriptor& role) const;\r
  65         \r
  66         /** An inline KeyResolver for extracting certificates out of a signature. */\r
  67         xmlsignature::KeyResolver* m_inlineResolver;\r
  68         \r
  69     public:\r
  70         virtual ~AbstractPKIXTrustEngine();\r
  71 \r
  72         virtual bool validate(\r
  73             xmlsignature::Signature& sig,\r
  74             const saml2md::RoleDescriptor& role,\r
  75             const xmlsignature::KeyResolver* keyResolver=NULL\r
  76             );\r
  77 \r
  78         virtual bool validate(\r
  79             XSECCryptoX509* certEE,\r
  80             const std::vector<XSECCryptoX509*>& certChain,\r
  81             const saml2md::RoleDescriptor& role,\r
  82             bool checkName=true,\r
  83             const xmlsignature::KeyResolver* keyResolver=NULL\r
  84             );\r
  85 \r
  86         /**\r
  87          * Stateful interface that supplies PKIX validation data to the trust engine.\r
  88          * Applications can adapt this TrustEngine to their environment by returning\r
  89          * implementations of this interface from the getPKIXValidationInfoIterator\r
  90          * method.\r
  91          */\r
  92         class SAML_API PKIXValidationInfoIterator {\r
  93             MAKE_NONCOPYABLE(PKIXValidationInfoIterator);\r
  94         protected:\r
  95             PKIXValidationInfoIterator() {}\r
  96         public:\r
  97             virtual ~PKIXValidationInfoIterator() {}\r
  98             \r
  99             /**\r
 100              * Advances to the next set of information, if any.\r
 101              * \r
 102              * @return true iff another set of information is available\r
 103              */\r
 104             virtual bool next()=0;\r
 105             \r
 106             /**\r
 107              * Returns the allowable trust chain verification depth for the\r
 108              * validation data in the current position.\r
 109              * \r
 110              * @return  allowable trust chain verification depth\r
 111              */\r
 112             virtual int getVerificationDepth() const=0;\r
 113             \r
 114             /**\r
 115              * Returns the set of trust anchors for the validation data in the\r
 116              * current position. Keeping the certificates beyond the lifetime\r
 117              * of the iterator or after advancing to the next position requires\r
 118              * copying them.\r
 119              * \r
 120              * @return  set of trust anchors\r
 121              */\r
 122             virtual const std::vector<XSECCryptoX509*>& getTrustAnchors() const=0;\r
 123 \r
 124             /**\r
 125              * Returns the set of CRLs for the validation data in the\r
 126              * current position. Keeping the CRLs beyond the lifetime\r
 127              * of the iterator or after advancing to the next position requires\r
 128              * copying them.\r
 129              * \r
 130              * @return  set of CRLs\r
 131              */\r
 132             virtual const std::vector<xmltooling::XSECCryptoX509CRL*>& getCRLs() const=0;\r
 133         };\r
 134         \r
 135         /**\r
 136          * Provides access to the information necessary, for the given role, for\r
 137          * PKIX validation of credentials. Each set of validation information returned\r
 138          * will be tried, in turn, until one succeeds or no more remain.\r
 139          * The caller must free the returned interface when finished with it.\r
 140          * \r
 141          * @return interface for obtaining validation data  \r
 142          */\r
 143         virtual PKIXValidationInfoIterator* getPKIXValidationInfoIterator(const saml2md::RoleDescriptor& role) const=0;\r
 144     };\r
 145 };\r
 146 \r
 147 #endif /* __saml_pkixtrust_h__ */\r