xmltooling/encryption/Decrypter.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file xmltooling/encryption/Decrypter.h
  23  *
  24  * Wrapper API for XML Decryption functionality.
  25  */
  26
  27 #if !defined(__xmltooling_decrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  28 #define __xmltooling_decrypter_h__
  29
  30 #include <xmltooling/exceptions.h>
  31
  32 class XENCCipher;
  33 class XSECCryptoKey;
  34
  35 namespace xmltooling {
  36     class XMLTOOL_API CredentialCriteria;
  37     class XMLTOOL_API CredentialResolver;
  38 };
  39
  40 namespace xmlencryption {
  41
  42     class XMLTOOL_API EncryptedData;
  43     class XMLTOOL_API EncryptedKey;
  44     class XMLTOOL_API EncryptedKeyResolver;
  45
  46     /**
  47      * Wrapper API for XML Decryption functionality.
  48      */
  49     class XMLTOOL_API Decrypter
  50     {
  51     public:
  52         /**
  53          * Constructor.
  54          *
  55          * @param credResolver  locked credential resolver to supply decryption keys
  56          * @param criteria      optional external criteria to use with resolver
  57          * @param EKResolver    locates an EncryptedKey pertaining to the EncryptedData
  58          */
  59         Decrypter(
  60             const xmltooling::CredentialResolver* credResolver=nullptr,
  61             xmltooling::CredentialCriteria* criteria=nullptr,
  62             const EncryptedKeyResolver* EKResolver=nullptr
  63             );
  64
  65         virtual ~Decrypter();
  66
  67         /**
  68          * Replace the current EncryptedKeyResolver interface, if any, with a new one.
  69          *
  70          * @param EKResolver  the EncryptedKeyResolver to attach
  71          */
  72         void setEncryptedKeyResolver(const EncryptedKeyResolver* EKResolver);
  73
  74         /**
  75          * Replace the current CredentialResolver interface, if any, with a new one.
  76          *
  77          * @param resolver  the locked CredentialResolver to attach, or nullptr to clear
  78          * @param criteria  optional external criteria to use with resolver
  79          */
  80         void setKEKResolver(const xmltooling::CredentialResolver* resolver, xmltooling::CredentialCriteria* criteria);
  81
  82         /**
  83          * Decrypts the supplied information using the supplied key, and returns
  84          * the resulting as a DOM fragment owned by the document associated with the
  85          * marshalled EncryptedData object.
  86          *
  87          * Note that the DOM nodes will be invalidated once that document
  88          * is released. The caller should therefore process the DOM fragment as
  89          * required and drop all references to it before that happens. The usual
  90          * approach should be to unmarshall the DOM and then release it, or the
  91          * DOM can also be imported into a separately owned document.
  92          *
  93          * @param encryptedData the data to decrypt
  94          * @param key           the decryption key to use (it will not be freed internally)
  95          * @return  the decrypted DOM fragment
  96          */
  97         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, XSECCryptoKey* key);
  98
  99         /**
 100          * Decrypts the supplied information and returns the resulting as a DOM
 101          * fragment owned by the document associated with the marshalled EncryptedData
 102          * object.
 103          *
 104          * Note that the DOM nodes will be invalidated once that document
 105          * is released. The caller should therefore process the DOM fragment as
 106          * required and drop all references to it before that happens. The usual
 107          * approach should be to unmarshall the DOM and then release it, or the
 108          * DOM can also be imported into a separately owned document.
 109          *
 110          * @param encryptedData the data to decrypt
 111          * @param recipient identifier of decrypting entity for use in identifying multi-cast keys
 112          * @return  the decrypted DOM fragment
 113          */
 114         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 115
 116         /**
 117          * Decrypts the supplied information to an output stream.
 118          *
 119          * @param out           output stream to receive the decrypted data
 120          * @param encryptedData the data to decrypt
 121          * @param key           the decryption key to use (it will not be freed internally)
 122          */
 123         void decryptData(std::ostream& out, const EncryptedData& encryptedData, XSECCryptoKey* key);
 124
 125         /**
 126          * Decrypts the supplied information to an output stream.
 127          *
 128          * @param out           output stream to receive the decrypted data
 129          * @param encryptedData the data to decrypt
 130          * @param recipient     identifier of decrypting entity for use in identifying multi-cast keys
 131          */
 132         void decryptData(std::ostream& out, const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 133
 134         /**
 135          * Decrypts the supplied information and returns the resulting key.
 136          * The caller is responsible for deleting the key. The algorithm of the
 137          * key must be supplied by the caller based on knowledge of the associated
 138          * EncryptedData information.
 139          *
 140          * @param encryptedKey  the encrypted/wrapped key to decrypt
 141          * @param algorithm     the algorithm associated with the decrypted key
 142          * @return  the decrypted key
 143          */
 144         XSECCryptoKey* decryptKey(const EncryptedKey& encryptedKey, const XMLCh* algorithm);
 145
 146     private:
 147         XENCCipher* m_cipher;
 148         const xmltooling::CredentialResolver* m_credResolver;
 149         xmltooling::CredentialCriteria* m_criteria;
 150         const EncryptedKeyResolver* m_EKResolver;
 151     };
 152
 153     DECL_XMLTOOLING_EXCEPTION(DecryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLToolingException,Exceptions in decryption processing);
 154
 155 };
 156
 157 #endif /* __xmltooling_decrypter_h__ */