2 * Copyright 2001-2006 Internet2
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * @file xmltooling/security/TrustEngine.h
20 * Evaluates the trustworthiness and validity of XML Signatures against
21 * implementation-specific requirements.
24 #if !defined(__xmltooling_trust_h__) && !defined(XMLTOOLING_NO_XMLSEC)
25 #define __xmltooling_trust_h__
27 #include <xmltooling/signature/KeyResolver.h>
28 #include <xmltooling/signature/Signature.h>
30 namespace xmltooling {
33 * Evaluates the trustworthiness and validity of XML or raw Signatures against
34 * implementation-specific requirements.
36 class XMLTOOL_API TrustEngine {
37 MAKE_NONCOPYABLE(TrustEngine);
42 * If a DOM is supplied, the following XML content is supported:
45 * <li><KeyResolver> elements with a type attribute
48 * XML namespaces are ignored in the processing of this content.
50 * @param e DOM to supply configuration for provider
52 TrustEngine(const DOMElement* e=NULL);
54 /** Default KeyResolver instance. */
55 xmlsignature::KeyResolver* m_keyResolver;
58 virtual ~TrustEngine();
61 * Callback interface to supply KeyInfo objects to a TrustEngine.
62 * Applications can adapt TrustEngines to their environment by supplying
63 * implementations of this interface, or create specialized TrustEngine APIs
64 * by combining a KeyInfoIterator with a delegated TrustEngine.
66 class XMLTOOL_API KeyInfoIterator {
67 MAKE_NONCOPYABLE(KeyInfoIterator);
71 virtual ~KeyInfoIterator() {}
74 * Indicates whether additional KeyInfo objects are available.
76 * @return true iff another KeyInfo object can be fetched
78 virtual bool hasNext() const=0;
81 * Returns the next KeyInfo object available.
83 * @return the next KeyInfo object, or NULL if none are left
85 virtual const xmlsignature::KeyInfo* next()=0;
89 * Determines whether an XML signature is correct and valid with respect to
90 * the KeyInfo data supplied. It is the responsibility of the application to
91 * ensure that the KeyInfo information supplied is in fact associated with
92 * the peer who created the signature.
94 * <p>A custom KeyResolver can be supplied from outside the TrustEngine.
95 * Alternatively, one may be specified to the plugin constructor.
96 * A non-caching, inline resolver will be used as a fallback.
98 * @param sig reference to a signature object to validate
99 * @param keyInfoSource supplies KeyInfo objects to the TrustEngine
100 * @param keyResolver optional externally supplied KeyResolver, or NULL
101 * @return true iff the signature validates
103 virtual bool validate(
104 xmlsignature::Signature& sig,
105 KeyInfoIterator& keyInfoSource,
106 const xmlsignature::KeyResolver* keyResolver=NULL
110 * Determines whether a raw signature is correct and valid with respect to
111 * the KeyInfo data supplied. It is the responsibility of the application to
112 * ensure that the KeyInfo information supplied is in fact associated with
113 * the peer who created the signature.
115 * <p>A custom KeyResolver can be supplied from outside the TrustEngine.
116 * Alternatively, one may be specified to the plugin constructor.
117 * A non-caching, inline resolver will be used as a fallback.
119 * <p>Note that the keyInfo parameter is not part of the implicitly trusted
120 * set of key information supplied via the iterator, but rather advisory data
121 * that may have accompanied the signature itself.
123 * @param sigAlgorithm XML Signature identifier for the algorithm used
124 * @param sig null-terminated base64-encoded signature value
125 * @param keyInfo KeyInfo object accompanying the signature, if any
126 * @param in the input data over which the signature was created
127 * @param in_len size of input data in bytes
128 * @param keyInfoSource supplies KeyInfo objects to the TrustEngine
129 * @param keyResolver optional externally supplied KeyResolver, or NULL
130 * @return true iff the signature validates
132 virtual bool validate(
133 const XMLCh* sigAlgorithm,
135 xmlsignature::KeyInfo* keyInfo,
138 KeyInfoIterator& keyInfoSource,
139 const xmlsignature::KeyResolver* keyResolver=NULL
144 * Registers TrustEngine classes into the runtime.
146 void XMLTOOL_API registerTrustEngines();
148 /** TrustEngine based on explicit knowledge of peer key information. */
149 #define EXPLICIT_KEY_TRUSTENGINE "org.opensaml.xmlooling.security.ExplicitKeyTrustEngine"
152 #endif /* __xmltooling_trust_h__ */