xmltooling/encryption/Decrypter.h

   1 /*
   2  *  Copyright 2001-2010 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/encryption/Decrypter.h
  19  *
  20  * Wrapper API for XML Decryption functionality.
  21  */
  22
  23 #if !defined(__xmltooling_decrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  24 #define __xmltooling_decrypter_h__
  25
  26 #include <xmltooling/exceptions.h>
  27
  28 class XENCCipher;
  29 class XSECCryptoKey;
  30
  31 namespace xmltooling {
  32     class XMLTOOL_API CredentialCriteria;
  33     class XMLTOOL_API CredentialResolver;
  34 };
  35
  36 namespace xmlencryption {
  37
  38     class XMLTOOL_API EncryptedData;
  39     class XMLTOOL_API EncryptedKey;
  40     class XMLTOOL_API EncryptedKeyResolver;
  41
  42     /**
  43      * Wrapper API for XML Decryption functionality.
  44      */
  45     class XMLTOOL_API Decrypter
  46     {
  47     public:
  48         /**
  49          * Constructor.
  50          *
  51          * @param credResolver  locked credential resolver to supply decryption keys
  52          * @param criteria      optional external criteria to use with resolver
  53          * @param EKResolver    locates an EncryptedKey pertaining to the EncryptedData
  54          */
  55         Decrypter(
  56             const xmltooling::CredentialResolver* credResolver=nullptr,
  57             xmltooling::CredentialCriteria* criteria=nullptr,
  58             const EncryptedKeyResolver* EKResolver=nullptr
  59             );
  60
  61         virtual ~Decrypter();
  62
  63         /**
  64          * Replace the current EncryptedKeyResolver interface, if any, with a new one.
  65          *
  66          * @param EKResolver  the EncryptedKeyResolver to attach
  67          */
  68         void setEncryptedKeyResolver(const EncryptedKeyResolver* EKResolver);
  69
  70         /**
  71          * Replace the current CredentialResolver interface, if any, with a new one.
  72          *
  73          * @param resolver  the locked CredentialResolver to attach, or nullptr to clear
  74          * @param criteria  optional external criteria to use with resolver
  75          */
  76         void setKEKResolver(const xmltooling::CredentialResolver* resolver, xmltooling::CredentialCriteria* criteria);
  77
  78         /**
  79          * Decrypts the supplied information using the supplied key, and returns
  80          * the resulting as a DOM fragment owned by the document associated with the
  81          * marshalled EncryptedData object.
  82          *
  83          * Note that the DOM nodes will be invalidated once that document
  84          * is released. The caller should therefore process the DOM fragment as
  85          * required and drop all references to it before that happens. The usual
  86          * approach should be to unmarshall the DOM and then release it, or the
  87          * DOM can also be imported into a separately owned document.
  88          *
  89          * @param encryptedData the data to decrypt
  90          * @param key           the decryption key to use (it will not be freed internally)
  91          * @return  the decrypted DOM fragment
  92          */
  93         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, XSECCryptoKey* key);
  94
  95         /**
  96          * Decrypts the supplied information and returns the resulting as a DOM
  97          * fragment owned by the document associated with the marshalled EncryptedData
  98          * object.
  99          *
 100          * Note that the DOM nodes will be invalidated once that document
 101          * is released. The caller should therefore process the DOM fragment as
 102          * required and drop all references to it before that happens. The usual
 103          * approach should be to unmarshall the DOM and then release it, or the
 104          * DOM can also be imported into a separately owned document.
 105          *
 106          * @param encryptedData the data to decrypt
 107          * @param recipient identifier of decrypting entity for use in identifying multi-cast keys
 108          * @return  the decrypted DOM fragment
 109          */
 110         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 111
 112         /**
 113          * Decrypts the supplied information to an output stream.
 114          *
 115          * @param out           output stream to receive the decrypted data
 116          * @param encryptedData the data to decrypt
 117          * @param key           the decryption key to use (it will not be freed internally)
 118          */
 119         void decryptData(std::ostream& out, const EncryptedData& encryptedData, XSECCryptoKey* key);
 120
 121         /**
 122          * Decrypts the supplied information to an output stream.
 123          *
 124          * @param out           output stream to receive the decrypted data
 125          * @param encryptedData the data to decrypt
 126          * @param recipient     identifier of decrypting entity for use in identifying multi-cast keys
 127          */
 128         void decryptData(std::ostream& out, const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 129
 130         /**
 131          * Decrypts the supplied information and returns the resulting key.
 132          * The caller is responsible for deleting the key. The algorithm of the
 133          * key must be supplied by the caller based on knowledge of the associated
 134          * EncryptedData information.
 135          *
 136          * @param encryptedKey  the encrypted/wrapped key to decrypt
 137          * @param algorithm     the algorithm associated with the decrypted key
 138          * @return  the decrypted key
 139          */
 140         XSECCryptoKey* decryptKey(const EncryptedKey& encryptedKey, const XMLCh* algorithm);
 141
 142     private:
 143         XENCCipher* m_cipher;
 144         const xmltooling::CredentialResolver* m_credResolver;
 145         xmltooling::CredentialCriteria* m_criteria;
 146         const EncryptedKeyResolver* m_EKResolver;
 147     };
 148
 149     DECL_XMLTOOLING_EXCEPTION(DecryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLToolingException,Exceptions in decryption processing);
 150
 151 };
 152
 153 #endif /* __xmltooling_decrypter_h__ */