xmltooling/signature/KeyResolver.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file KeyResolver.h
  19  *
  20  * Resolves public keys and certificates based on KeyInfo information or
  21  * external factors.
  22  */
  23
  24 #if !defined(__xmltooling_keyres_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  25 #define __xmltooling_keyres_h__
  26
  27 #include <xmltooling/security/XSECCryptoX509CRL.h>
  28
  29 #include <xsec/dsig/DSIGKeyInfoList.hpp>
  30 #include <xsec/enc/XSECCryptoKey.hpp>
  31 #include <xsec/enc/XSECCryptoX509.hpp>
  32
  33 #include <algorithm>
  34 #include <vector>
  35
  36 namespace xmlsignature {
  37     class XMLTOOL_API KeyInfo;
  38     class XMLTOOL_API Signature;
  39
  40     /**
  41      * An API for resolving keys. The default/simple implementation
  42      * allows a hard-wired key to be supplied. This is mostly
  43      * useful for testing, or to adapt another mechanism for supplying
  44      * keys to this interface.
  45      */
  46     class XMLTOOL_API KeyResolver {
  47         MAKE_NONCOPYABLE(KeyResolver);
  48     public:
  49         /**
  50          * Constructor based on a single externally supplied key.
  51          * The key will be destroyed when the resolver is.
  52          *
  53          * @param key   external key
  54          */
  55         KeyResolver(XSECCryptoKey* key=NULL) : m_key(key) {}
  56
  57         virtual ~KeyResolver() {
  58             delete m_key;
  59         }
  60
  61         /**
  62          * Returns a key based on the supplied KeyInfo information.
  63          * The caller must delete the key when done with it.
  64          *
  65          * @param keyInfo   the key information
  66          * @return  the resolved key
  67          */
  68         virtual XSECCryptoKey* resolveKey(const KeyInfo* keyInfo) const {
  69             return m_key ? m_key->clone() : NULL;
  70         }
  71
  72         /**
  73          * Returns a key based on the supplied KeyInfo information.
  74          * The caller must delete the key when done with it.
  75          *
  76          * @param keyInfo   the key information
  77          * @return  the resolved key
  78          */
  79         virtual XSECCryptoKey* resolveKey(DSIGKeyInfoList* keyInfo) const {
  80             return m_key ? m_key->clone() : NULL;
  81         }
  82
  83         /**
  84          * Returns a key based on the supplied KeyInfo information.
  85          * The caller must delete the key when done with it.
  86          *
  87          * @param sig   signature containing the key information
  88          * @return  the resolved key
  89          */
  90         XSECCryptoKey* resolveKey(const Signature* sig) const;
  91
  92         /**
  93          * A wrapper that handles disposal of certificates when required.
  94          */
  95         class XMLTOOL_API ResolvedCertificates {
  96             MAKE_NONCOPYABLE(ResolvedCertificates);
  97             bool m_owned;
  98             std::vector<XSECCryptoX509*> m_certs;
  99         public:
 100             ResolvedCertificates() : m_owned(false) {}
 101
 102             ~ResolvedCertificates() {
 103                 clear();
 104             }
 105
 106             /**
 107              * Empties the container and frees any held resources.
 108              */
 109             void clear() {
 110                 if (m_owned) {
 111                     std::for_each(m_certs.begin(), m_certs.end(), xmltooling::cleanup<XSECCryptoX509>());
 112                     m_owned = false;
 113                 }
 114                 m_certs.clear();
 115             }
 116
 117             /**
 118              * Transfers ownership of certificates outside wrapper.
 119              *
 120              * @param writeTo   a container into which to move the certificates
 121              * @return  true iff the certificates must be freed by caller
 122              */
 123             bool release(std::vector<XSECCryptoX509*>& writeTo) {
 124                 writeTo.assign(m_certs.begin(),m_certs.end());
 125                 m_certs.clear();
 126                 if (m_owned) {
 127                     m_owned=false;
 128                     return true;
 129                 }
 130                 return false;
 131             }
 132
 133             /**
 134              * Accesses the underlying array of certificates.
 135              *
 136              * @return reference to certificate container
 137              */
 138             const std::vector<XSECCryptoX509*>& v() const {
 139                 return m_certs;
 140             }
 141
 142             friend class XMLTOOL_API KeyResolver;
 143         };
 144
 145         /**
 146          * Returns a set of certificates based on the supplied KeyInfo information.
 147          * The certificates must be cloned if kept beyond the lifetime of the KeyInfo source.
 148          *
 149          * @param keyInfo   the key information
 150          * @param certs     reference to object to hold certificates
 151          * @return  number of certificates returned
 152          */
 153         virtual std::vector<XSECCryptoX509*>::size_type resolveCertificates(
 154             const KeyInfo* keyInfo, ResolvedCertificates& certs
 155             ) const;
 156
 157         /**
 158          * Returns a set of certificates based on the supplied KeyInfo information.
 159          * The certificates must be cloned if kept beyond the lifetime of the KeyInfo source.
 160          *
 161          * @param keyInfo   the key information
 162          * @param certs     reference to object to hold certificates
 163          * @return  number of certificates returned
 164          */
 165         virtual std::vector<XSECCryptoX509*>::size_type resolveCertificates(
 166             DSIGKeyInfoList* keyInfo, ResolvedCertificates& certs
 167             ) const;
 168
 169         /**
 170          * Returns a set of certificates based on the supplied KeyInfo information.
 171          * The certificates must be cloned if kept beyond the lifetime of the KeyInfo source.
 172          *
 173          * @param sig   signature containing the key information
 174          * @param certs     reference to object to hold certificates
 175          * @return  number of certificates returned
 176          */
 177         std::vector<XSECCryptoX509*>::size_type resolveCertificates(
 178             const Signature* sig, ResolvedCertificates& certs
 179             ) const;
 180
 181         /**
 182          * Returns a CRL based on the supplied KeyInfo information.
 183          * The caller must delete the CRL when done with it.
 184          *
 185          * @param keyInfo   the key information
 186          * @return  the resolved CRL
 187          */
 188         virtual xmltooling::XSECCryptoX509CRL* resolveCRL(const KeyInfo* keyInfo) const;
 189
 190         /**
 191          * Returns a CRL based on the supplied KeyInfo information.
 192          * The caller must delete the CRL when done with it.
 193          *
 194          * @param keyInfo   the key information
 195          * @return  the resolved CRL
 196          */
 197         virtual xmltooling::XSECCryptoX509CRL* resolveCRL(DSIGKeyInfoList* keyInfo) const;
 198
 199         /**
 200          * Returns a CRL based on the supplied KeyInfo information.
 201          * The caller must delete the CRL when done with it.
 202          *
 203          * @param sig   signature containing the key information
 204          * @return  the resolved CRL
 205          */
 206         xmltooling::XSECCryptoX509CRL* resolveCRL(const Signature* sig) const;
 207
 208     protected:
 209         /** Stores an explicit key. */
 210         XSECCryptoKey* m_key;
 211
 212         /**
 213          * Accessor for certificate vector from derived KeyResolver classes.
 214          *
 215          * @param certs certificate wrapper to access
 216          * @return modifiable reference to vector inside wrapper
 217          */
 218         std::vector<XSECCryptoX509*>& accessCertificates(ResolvedCertificates& certs) const {
 219             return certs.m_certs;
 220         }
 221
 222         /**
 223          * Accessor for certificate ownership flag from derived KeyResolver classes.
 224          *
 225          * @param certs certificate wrapper to access
 226          * @return modifiable reference to ownership flag inside wrapper
 227          */
 228         bool& accessOwned(ResolvedCertificates& certs) const {
 229             return certs.m_owned;
 230         }
 231     };
 232
 233     /**
 234      * Registers KeyResolver classes into the runtime.
 235      */
 236     void XMLTOOL_API registerKeyResolvers();
 237
 238     /** KeyResolver based on hard-wired key */
 239     #define FILESYSTEM_KEY_RESOLVER  "org.opensaml.xmlooling.FilesystemKeyResolver"
 240
 241     /** KeyResolver based on extracting information directly out of a KeyInfo */
 242     #define INLINE_KEY_RESOLVER  "org.opensaml.xmlooling.InlineKeyResolver"
 243 };
 244
 245 #endif /* __xmltooling_keyres_h__ */