xmltooling/security/TrustEngine.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 xmltooling/security/TrustEngine.h\r
  19  * \r
  20  * Evaluates the trustworthiness and validity of XML Signatures against\r
  21  * implementation-specific requirements.\r
  22  */\r
  23 \r
  24 #if !defined(__xmltooling_trust_h__) && !defined(XMLTOOLING_NO_XMLSEC)\r
  25 #define __xmltooling_trust_h__\r
  26 \r
  27 #include <xmltooling/signature/KeyResolver.h>\r
  28 #include <xmltooling/signature/Signature.h>\r
  29 \r
  30 namespace xmltooling {\r
  31 \r
  32     /**\r
  33      * Evaluates the trustworthiness and validity of XML Signatures against\r
  34      * implementation-specific requirements.\r
  35      */\r
  36     class XMLTOOL_API TrustEngine {\r
  37         MAKE_NONCOPYABLE(TrustEngine);\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         TrustEngine(const DOMElement* e=NULL);\r
  53         \r
  54         /** Default KeyResolver instance. */\r
  55         xmlsignature::KeyResolver* m_keyResolver;\r
  56         \r
  57     public:\r
  58         virtual ~TrustEngine();\r
  59         \r
  60         /**\r
  61          * Callback interface to supply KeyInfo objects to a TrustEngine.\r
  62          * Applications can adapt TrustEngines to their environment by supplying\r
  63          * implementations of this interface, or create specialized TrustEngine APIs\r
  64          * by combining a KeyInfoIterator with a delegated TrustEngine. \r
  65          */\r
  66         class XMLTOOL_API KeyInfoIterator {\r
  67             MAKE_NONCOPYABLE(KeyInfoIterator);\r
  68         protected:\r
  69             KeyInfoIterator() {}\r
  70         public:\r
  71             virtual ~KeyInfoIterator() {}\r
  72             \r
  73             /**\r
  74              * Indicates whether additional KeyInfo objects are available.\r
  75              * \r
  76              * @return true iff another KeyInfo object can be fetched\r
  77              */\r
  78             virtual bool hasNext() const=0;\r
  79             \r
  80             /**\r
  81              * Returns the next KeyInfo object available.\r
  82              * \r
  83              * @return the next KeyInfo object, or NULL if none are left\r
  84              */\r
  85             virtual const xmlsignature::KeyInfo* next()=0;\r
  86         };\r
  87         \r
  88         /**\r
  89          * Determines whether a signature is correct and valid with respect to the\r
  90          * KeyInfo data supplied. It is the responsibility of the application to\r
  91          * ensure that the KeyInfo information supplied is in fact associated with\r
  92          * the peer who created the signature. \r
  93          * \r
  94          * A custom KeyResolver can be supplied from outside the TrustEngine.\r
  95          * Alternatively, one may be specified to the plugin constructor.\r
  96          * A non-caching, inline resolver will be used as a fallback.\r
  97          * \r
  98          * @param sig           reference to a signature object to validate\r
  99          * @param keyInfoSource supplies KeyInfo objects to the TrustEngine\r
 100          * @param keyResolver   optional externally supplied KeyResolver, or NULL\r
 101          */\r
 102         virtual bool validate(\r
 103             xmlsignature::Signature& sig,\r
 104             KeyInfoIterator& keyInfoSource,\r
 105             const xmlsignature::KeyResolver* keyResolver=NULL\r
 106             ) const=0;\r
 107     };\r
 108 \r
 109     /**\r
 110      * Registers TrustEngine classes into the runtime.\r
 111      */\r
 112     void XMLTOOL_API registerTrustEngines();\r
 113 \r
 114     /** TrustEngine based on explicit knowledge of peer key information. */\r
 115     #define EXPLICIT_KEY_TRUSTENGINE  "org.opensaml.xmlooling.security.ExplicitKeyTrustEngine"\r
 116 };\r
 117 \r
 118 #endif /* __xmltooling_trust_h__ */\r