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          * <p>The final boolean parameter is used to enforce a requirement for an authenticated cipher
  56          * suite such as AES-GCM or similar. These ciphers include an HMAC or equivalent step that
  57          * prevents tampering. Newer applications should set this parameter to true unless the ciphertext
  58          * has been independently authenticated, and even in such a case, it is rarely possible to prevent
  59          * chosen ciphertext attacks by trusted signers.
  60          *
  61          * @param credResolver  locked credential resolver to supply decryption keys
  62          * @param criteria      optional external criteria to use with resolver
  63          * @param EKResolver    locates an EncryptedKey pertaining to the EncryptedData
  64          * @param requireAuthenticatedCipher    true iff the bulk data encryption algorithm must be an authenticated cipher
  65          */
  66         Decrypter(
  67             const xmltooling::CredentialResolver* credResolver=nullptr,
  68             xmltooling::CredentialCriteria* criteria=nullptr,
  69             const EncryptedKeyResolver* EKResolver=nullptr,
  70             bool requireAuthenticatedCipher=false
  71             );
  72
  73         virtual ~Decrypter();
  74
  75         /**
  76          * Replace the current EncryptedKeyResolver interface, if any, with a new one.
  77          *
  78          * @param EKResolver  the EncryptedKeyResolver to attach
  79          */
  80         void setEncryptedKeyResolver(const EncryptedKeyResolver* EKResolver);
  81
  82         /**
  83          * Replace the current CredentialResolver interface, if any, with a new one.
  84          *
  85          * @param resolver  the locked CredentialResolver to attach, or nullptr to clear
  86          * @param criteria  optional external criteria to use with resolver
  87          */
  88         void setKEKResolver(const xmltooling::CredentialResolver* resolver, xmltooling::CredentialCriteria* criteria);
  89
  90         /**
  91          * Decrypts the supplied information using the supplied key, and returns
  92          * the resulting as a DOM fragment owned by the document associated with the
  93          * marshalled EncryptedData object.
  94          *
  95          * Note that the DOM nodes will be invalidated once that document
  96          * is released. The caller should therefore process the DOM fragment as
  97          * required and drop all references to it before that happens. The usual
  98          * approach should be to unmarshall the DOM and then release it, or the
  99          * DOM can also be imported into a separately owned document.
 100          *
 101          * @param encryptedData the data to decrypt
 102          * @param key           the decryption key to use (it will not be freed internally)
 103          * @return  the decrypted DOM fragment
 104          */
 105         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, XSECCryptoKey* key);
 106
 107         /**
 108          * Decrypts the supplied information and returns the resulting as a DOM
 109          * fragment owned by the document associated with the marshalled EncryptedData
 110          * object.
 111          *
 112          * Note that the DOM nodes will be invalidated once that document
 113          * is released. The caller should therefore process the DOM fragment as
 114          * required and drop all references to it before that happens. The usual
 115          * approach should be to unmarshall the DOM and then release it, or the
 116          * DOM can also be imported into a separately owned document.
 117          *
 118          * @param encryptedData the data to decrypt
 119          * @param recipient identifier of decrypting entity for use in identifying multi-cast keys
 120          * @return  the decrypted DOM fragment
 121          */
 122         xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 123
 124         /**
 125          * Decrypts the supplied information to an output stream.
 126          *
 127          * @param out           output stream to receive the decrypted data
 128          * @param encryptedData the data to decrypt
 129          * @param key           the decryption key to use (it will not be freed internally)
 130          */
 131         void decryptData(std::ostream& out, const EncryptedData& encryptedData, XSECCryptoKey* key);
 132
 133         /**
 134          * Decrypts the supplied information to an output stream.
 135          *
 136          * @param out           output stream to receive the decrypted data
 137          * @param encryptedData the data to decrypt
 138          * @param recipient     identifier of decrypting entity for use in identifying multi-cast keys
 139          */
 140         void decryptData(std::ostream& out, const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
 141
 142         /**
 143          * Decrypts the supplied information and returns the resulting key.
 144          * The caller is responsible for deleting the key. The algorithm of the
 145          * key must be supplied by the caller based on knowledge of the associated
 146          * EncryptedData information.
 147          *
 148          * @param encryptedKey  the encrypted/wrapped key to decrypt
 149          * @param algorithm     the algorithm associated with the decrypted key
 150          * @return  the decrypted key
 151          */
 152         XSECCryptoKey* decryptKey(const EncryptedKey& encryptedKey, const XMLCh* algorithm);
 153
 154     private:
 155         XENCCipher* m_cipher;
 156         const xmltooling::CredentialResolver* m_credResolver;
 157         xmltooling::CredentialCriteria* m_criteria;
 158         const EncryptedKeyResolver* m_EKResolver;
 159         bool m_requireAuthenticatedCipher;
 160     };
 161
 162     DECL_XMLTOOLING_EXCEPTION(DecryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLToolingException,Exceptions in decryption processing);
 163
 164 };
 165
 166 #endif /* __xmltooling_decrypter_h__ */