2 * Copyright 2001-2006 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 * Methods for encrypting XMLObjects and other data.
23 #if !defined(__xmltooling_encrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
24 #define __xmltooling_encrypter_h__
26 #include <xmltooling/encryption/Encryption.h>
28 #include <xsec/enc/XSECCryptoKey.hpp>
29 #include <xsec/xenc/XENCCipher.hpp>
31 namespace xmlencryption {
34 * Wrapper API for XML Encryption functionality.
35 * Designed to allow both external and internal key generation as follows:
37 * If no keying material is supplied, then the algorithm MAY be recognized
38 * and a key can be generated internally. This is only done if a KeyEncryptionParams
39 * structure is also supplied to the operation (otherwise the key would be lost).
41 * If an XSECCryptoKey is supplied, then it is used directly, but if KeyEncryptionParams
42 * are supplied, an exception will result unless the raw key buffer is also supplied.
44 * If a raw key is provided, then a key object can also be created internally if the
45 * algorithm is recognized.
47 * Summing up, if KeyEncryptionParams are used, a raw key must be available or the
48 * key can be generated when the encryption algorithm itself is a standard one. If
49 * no KeyEncryptionParams are supplied, then the key must be supplied either in raw
52 class XMLTOOL_API Encrypter
57 * Structure to collect encryption requirements.
59 struct XMLTOOL_API EncryptionParams {
63 * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
64 * the structure. The other objects will be destroyed if need be when the structure is destroyed.
66 * @param algorithm the XML Encryption key wrapping or transport algorithm constant
67 * @param keyBuffer buffer containing the raw key information
68 * @param keyBufferSize the size of the raw key buffer in bytes
69 * @param key the key encryption key to use, or NULL
70 * @param keyInfo a KeyInfo object to place within the EncryptedData structure
73 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES256_CBC,
74 const unsigned char* keyBuffer=NULL,
75 unsigned int keyBufferSize=0,
76 XSECCryptoKey* key=NULL,
77 xmlsignature::KeyInfo* keyInfo=NULL
78 ) : m_keyBuffer(keyBuffer), m_keyBufferSize(keyBufferSize), m_key(key), m_keyInfo(keyInfo), m_algorithm(algorithm) {
86 const unsigned char* m_keyBuffer;
87 unsigned int m_keyBufferSize;
89 xmlsignature::KeyInfo* m_keyInfo;
90 const XMLCh* m_algorithm;
92 friend class Encrypter;
96 * Structure to collect key wrapping/transport requirements.
98 struct XMLTOOL_API KeyEncryptionParams {
102 * The algorithm constant <strong>MUST</strong> be accessible for the life of the structure.
103 * Using a static constant suffices for this. The other objects will be destroyed if need be
104 * when the structure is destroyed.
106 * @param algorithm the XML Encryption key wrapping or transport algorithm constant
107 * @param key the key encryption key to use
108 * @param keyInfo a KeyInfo object to place within the EncryptedKey structure that describes the KEK
110 KeyEncryptionParams(const XMLCh* algorithm, XSECCryptoKey* key, xmlsignature::KeyInfo* keyInfo=NULL)
111 : m_key(key), m_keyInfo(keyInfo), m_algorithm(algorithm) {
114 ~KeyEncryptionParams() {
119 XSECCryptoKey* m_key;
120 xmlsignature::KeyInfo* m_keyInfo;
121 const XMLCh* m_algorithm;
123 friend class Encrypter;
126 Encrypter() : m_cipher(NULL) {}
131 * Encrypts the supplied element and returns the resulting object.
132 * The returned object will be unmarshalled around a DOM tree created
133 * using the encrypted element's owning document.
135 * If an encryption algorithm is set, but no key, a random key will be
136 * generated iff keParams is non-NULL and the algorithm is known.
138 * If key encryption parameters are supplied, then the encryption key
139 * is wrapped and the result placed into an EncryptedKey object in the
140 * KeyInfo of the returned EncryptedData.
142 * @param element the DOM element to encrypt
143 * @param keParams key encryption settings, or NULL
145 EncryptedData* encryptElement(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
148 * Encrypts the supplied element's children and returns the resulting object.
149 * The returned object will be unmarshalled around a DOM tree created
150 * using the encrypted content's owning document.
152 * If an encryption algorithm is set, but no key, a random key will be
153 * generated iff keParams is non-NULL and the algorithm is known.
155 * If key encryption parameters are supplied, then the encryption key
156 * is wrapped and the result placed into an EncryptedKey object in the
157 * KeyInfo of the returned EncryptedData.
159 * @param element parent element of children to encrypt
160 * @param keParams key encryption settings, or NULL
162 EncryptedData* encryptElementContent(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
165 * Encrypts the supplied input stream and returns the resulting object.
166 * The returned object will be unmarshalled around a DOM tree created
167 * using the encrypted element's owning document.
169 * If an encryption algorithm is set, but no key, a random key will be
170 * generated iff keParams is non-NULL and the algorithm is known.
172 * If key encryption parameters are supplied, then the encryption key
173 * is wrapped and the result placed into an EncryptedKey object in the
174 * KeyInfo of the returned EncryptedData.
176 * @param input the stream to encrypt
177 * @param keParams key encryption settings, or NULL
179 EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
182 void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
183 EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
185 XENCCipher* m_cipher;
186 unsigned char m_keyBuffer[32];
189 DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLToolingException,Exceptions in encryption processing);
193 #endif /* __xmltooling_encrypter_h__ */