2 * Copyright 2001-2010 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.
18 * @file xmltooling/encryption/Encrypter.h
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/exceptions.h>
28 #include <xsec/dsig/DSIGConstants.hpp>
32 namespace xmltooling {
33 class XMLTOOL_API Credential;
36 namespace xmlencryption {
38 class XMLTOOL_API EncryptedData;
39 class XMLTOOL_API EncryptedKey;
42 * Wrapper API for XML Encryption functionality.
43 * Designed to allow both external and internal key generation as follows:
45 * If no keying material is supplied, then the algorithm MAY be recognized
46 * and a key can be generated internally. This is only done if a KeyEncryptionParams
47 * structure is also supplied to the operation (otherwise the key would be lost).
49 * If an XSECCryptoKey is supplied, then it is used directly, but if KeyEncryptionParams
50 * are supplied, an exception will result unless the raw key buffer is also supplied.
52 * If a raw key is provided, then a key object can also be created internally if the
53 * algorithm is recognized.
55 * Summing up, if KeyEncryptionParams are used, a raw key must be available or the
56 * key can be generated when the encryption algorithm itself is a standard one. If
57 * no KeyEncryptionParams are supplied, then the key must be supplied either in raw
60 * Finally, when encrypting data, the key transport algorithm can be left blank to
61 * derive it from the data encryption algorithm.
63 class XMLTOOL_API Encrypter
68 * Structure to collect encryption requirements.
70 struct XMLTOOL_API EncryptionParams {
74 * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
77 * @param algorithm the XML Encryption algorithm constant
78 * @param keyBuffer buffer containing the raw key information
79 * @param keyBufferSize the size of the raw key buffer in bytes
80 * @param credential optional Credential supplying the encryption key
81 * @param compact true iff the encrypted representation should be made as small as possible
84 #ifdef XSEC_OPENSSL_HAVE_AES
85 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES128_CBC,
87 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURI3DES_CBC,
89 const unsigned char* keyBuffer=nullptr,
90 unsigned int keyBufferSize=0,
91 const xmltooling::Credential* credential=nullptr,
97 /** Data encryption algorithm. */
98 const XMLCh* m_algorithm;
100 /** Buffer containing encryption key. */
101 const unsigned char* m_keyBuffer;
103 /** Size of buffer. */
104 unsigned int m_keyBufferSize;
106 /** Credential containing the encryption key. */
107 const xmltooling::Credential* m_credential;
109 /** Flag limiting the size of the encrypted XML representation. */
114 * Structure to collect key wrapping/transport requirements.
116 struct XMLTOOL_API KeyEncryptionParams {
120 * @param credential a Credential supplying the key encryption key
121 * @param algorithm XML Encryption key wrapping or transport algorithm constant
122 * @param recipient optional name of recipient of encrypted key
125 const xmltooling::Credential& credential, const XMLCh* algorithm=nullptr, const XMLCh* recipient=nullptr
128 ~KeyEncryptionParams();
130 /** Credential containing key encryption key. */
131 const xmltooling::Credential& m_credential;
133 /** Key transport or wrapping algorithm. */
134 const XMLCh* m_algorithm;
136 /** Name of recipient that owns the key encryption key. */
137 const XMLCh* m_recipient;
142 virtual ~Encrypter();
145 * Encrypts the supplied element and returns the resulting object.
147 * If an encryption algorithm is set, but no key, a random key will be
148 * generated iff kencParams is non-NULL and the algorithm is known.
150 * If key encryption parameters are supplied, then the encryption key
151 * is wrapped and the result placed into an EncryptedKey object in the
152 * KeyInfo of the returned EncryptedData.
154 * @param element the DOM element to encrypt
155 * @param encParams primary encryption settings
156 * @param kencParams key encryption settings, or nullptr
157 * @return a stand-alone EncryptedData object, unconnected to the source DOM
159 EncryptedData* encryptElement(
160 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
164 * Encrypts the supplied element's children and returns the resulting object.
166 * If an encryption algorithm is set, but no key, a random key will be
167 * generated iff kencParams is non-NULL and the algorithm is known.
169 * If key encryption parameters are supplied, then the encryption key
170 * is wrapped and the result placed into an EncryptedKey object in the
171 * KeyInfo of the returned EncryptedData.
173 * @param element parent element of children to encrypt
174 * @param encParams primary encryption settings
175 * @param kencParams key encryption settings, or nullptr
176 * @return a stand-alone EncryptedData object, unconnected to the source DOM
178 EncryptedData* encryptElementContent(
179 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
183 * Encrypts the supplied input stream and returns the resulting object.
185 * If an encryption algorithm is set, but no key, a random key will be
186 * generated iff kencParams is non-NULL and the algorithm is known.
188 * If key encryption parameters are supplied, then the encryption key
189 * is wrapped and the result placed into an EncryptedKey object in the
190 * KeyInfo of the returned EncryptedData.
192 * @param input the stream to encrypt
193 * @param encParams primary encryption settings
194 * @param kencParams key encryption settings, or nullptr
195 * @return a stand-alone EncryptedData object, unconnected to any DOM
197 EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr);
200 * Encrypts the supplied key and returns the resulting object.
202 * @param keyBuffer raw key material to encrypt
203 * @param keyBufferSize size in bytes of raw key material
204 * @param kencParams key encryption settings
205 * @param compact true iff the encrypted representation should be made as small as possible
206 * @return a stand-alone EncryptedKey object, unconnected to any DOM
208 EncryptedKey* encryptKey(
209 const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
213 * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
215 * @param credential the key encryption key
216 * @param encryptionAlg data encryption algorithm
217 * @return a key transport algorithm
219 static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
222 void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
223 EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
225 XENCCipher* m_cipher;
226 unsigned char m_keyBuffer[32];
229 DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
233 #endif /* __xmltooling_encrypter_h__ */