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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file xmltooling/encryption/Decrypter.h
24 * Wrapper API for XML Decryption functionality.
27 #if !defined(__xmltooling_decrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
28 #define __xmltooling_decrypter_h__
30 #include <xmltooling/exceptions.h>
35 namespace xmltooling {
36 class XMLTOOL_API CredentialCriteria;
37 class XMLTOOL_API CredentialResolver;
40 namespace xmlencryption {
42 class XMLTOOL_API EncryptedData;
43 class XMLTOOL_API EncryptedKey;
44 class XMLTOOL_API EncryptedKeyResolver;
47 * Wrapper API for XML Decryption functionality.
49 class XMLTOOL_API Decrypter
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.
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
67 const xmltooling::CredentialResolver* credResolver=nullptr,
68 xmltooling::CredentialCriteria* criteria=nullptr,
69 const EncryptedKeyResolver* EKResolver=nullptr,
70 bool requireAuthenticatedCipher=false
76 * Replace the current EncryptedKeyResolver interface, if any, with a new one.
78 * @param EKResolver the EncryptedKeyResolver to attach
80 void setEncryptedKeyResolver(const EncryptedKeyResolver* EKResolver);
83 * Replace the current CredentialResolver interface, if any, with a new one.
85 * @param resolver the locked CredentialResolver to attach, or nullptr to clear
86 * @param criteria optional external criteria to use with resolver
88 void setKEKResolver(const xmltooling::CredentialResolver* resolver, xmltooling::CredentialCriteria* criteria);
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.
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.
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
105 xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, XSECCryptoKey* key);
108 * Decrypts the supplied information and returns the resulting as a DOM
109 * fragment owned by the document associated with the marshalled EncryptedData
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.
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
122 xercesc::DOMDocumentFragment* decryptData(const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
125 * Decrypts the supplied information to an output stream.
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)
131 void decryptData(std::ostream& out, const EncryptedData& encryptedData, XSECCryptoKey* key);
134 * Decrypts the supplied information to an output stream.
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
140 void decryptData(std::ostream& out, const EncryptedData& encryptedData, const XMLCh* recipient=nullptr);
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.
148 * @param encryptedKey the encrypted/wrapped key to decrypt
149 * @param algorithm the algorithm associated with the decrypted key
150 * @return the decrypted key
152 XSECCryptoKey* decryptKey(const EncryptedKey& encryptedKey, const XMLCh* algorithm);
155 XENCCipher* m_cipher;
156 const xmltooling::CredentialResolver* m_credResolver;
157 xmltooling::CredentialCriteria* m_criteria;
158 const EncryptedKeyResolver* m_EKResolver;
159 bool m_requireAuthenticatedCipher;
162 DECL_XMLTOOLING_EXCEPTION(DecryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLToolingException,Exceptions in decryption processing);
166 #endif /* __xmltooling_decrypter_h__ */