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