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/Encrypter.h
24 * Methods for encrypting XMLObjects and other data.
27 #if !defined(__xmltooling_encrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
28 #define __xmltooling_encrypter_h__
30 #include <xmltooling/exceptions.h>
32 #include <xsec/dsig/DSIGConstants.hpp>
36 namespace xmltooling {
37 class XMLTOOL_API Credential;
40 namespace xmlencryption {
42 class XMLTOOL_API EncryptedData;
43 class XMLTOOL_API EncryptedKey;
46 * Wrapper API for XML Encryption functionality.
47 * Designed to allow both external and internal key generation as follows:
49 * If no keying material is supplied, then the algorithm MAY be recognized
50 * and a key can be generated internally. This is only done if a KeyEncryptionParams
51 * structure is also supplied to the operation (otherwise the key would be lost).
53 * If an XSECCryptoKey is supplied, then it is used directly, but if KeyEncryptionParams
54 * are supplied, an exception will result unless the raw key buffer is also supplied.
56 * If a raw key is provided, then a key object can also be created internally if the
57 * algorithm is recognized.
59 * Summing up, if KeyEncryptionParams are used, a raw key must be available or the
60 * key can be generated when the encryption algorithm itself is a standard one. If
61 * no KeyEncryptionParams are supplied, then the key must be supplied either in raw
64 * Finally, when encrypting data, the key transport algorithm can be left blank to
65 * derive it from the data encryption algorithm.
67 class XMLTOOL_API Encrypter
72 * Structure to collect encryption requirements.
74 struct XMLTOOL_API EncryptionParams {
78 * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
81 * @param algorithm the XML Encryption algorithm constant
82 * @param keyBuffer buffer containing the raw key information
83 * @param keyBufferSize the size of the raw key buffer in bytes
84 * @param credential optional Credential supplying the encryption key
85 * @param compact true iff the encrypted representation should be made as small as possible
88 #ifdef XSEC_OPENSSL_HAVE_AES
89 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES128_CBC,
91 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURI3DES_CBC,
93 const unsigned char* keyBuffer=nullptr,
94 unsigned int keyBufferSize=0,
95 const xmltooling::Credential* credential=nullptr,
101 /** Data encryption algorithm. */
102 const XMLCh* m_algorithm;
104 /** Buffer containing encryption key. */
105 const unsigned char* m_keyBuffer;
107 /** Size of buffer. */
108 unsigned int m_keyBufferSize;
110 /** Credential containing the encryption key. */
111 const xmltooling::Credential* m_credential;
113 /** Flag limiting the size of the encrypted XML representation. */
118 * Structure to collect key wrapping/transport requirements.
120 struct XMLTOOL_API KeyEncryptionParams {
124 * @param credential a Credential supplying the key encryption key
125 * @param algorithm XML Encryption key wrapping or transport algorithm constant
126 * @param recipient optional name of recipient of encrypted key
129 const xmltooling::Credential& credential, const XMLCh* algorithm=nullptr, const XMLCh* recipient=nullptr
132 ~KeyEncryptionParams();
134 /** Credential containing key encryption key. */
135 const xmltooling::Credential& m_credential;
137 /** Key transport or wrapping algorithm. */
138 const XMLCh* m_algorithm;
140 /** Name of recipient that owns the key encryption key. */
141 const XMLCh* m_recipient;
146 virtual ~Encrypter();
149 * Encrypts the supplied element and returns the resulting object.
151 * If an encryption algorithm is set, but no key, a random key will be
152 * generated iff kencParams is non-NULL and the algorithm is known.
154 * If key encryption parameters are supplied, then the encryption key
155 * is wrapped and the result placed into an EncryptedKey object in the
156 * KeyInfo of the returned EncryptedData.
158 * @param element the DOM element to encrypt
159 * @param encParams primary encryption settings
160 * @param kencParams key encryption settings, or nullptr
161 * @return a stand-alone EncryptedData object, unconnected to the source DOM
163 EncryptedData* encryptElement(
164 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
168 * Encrypts the supplied element's children and returns the resulting object.
170 * If an encryption algorithm is set, but no key, a random key will be
171 * generated iff kencParams is non-NULL and the algorithm is known.
173 * If key encryption parameters are supplied, then the encryption key
174 * is wrapped and the result placed into an EncryptedKey object in the
175 * KeyInfo of the returned EncryptedData.
177 * @param element parent element of children to encrypt
178 * @param encParams primary encryption settings
179 * @param kencParams key encryption settings, or nullptr
180 * @return a stand-alone EncryptedData object, unconnected to the source DOM
182 EncryptedData* encryptElementContent(
183 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
187 * Encrypts the supplied input stream and returns the resulting object.
189 * If an encryption algorithm is set, but no key, a random key will be
190 * generated iff kencParams is non-NULL and the algorithm is known.
192 * If key encryption parameters are supplied, then the encryption key
193 * is wrapped and the result placed into an EncryptedKey object in the
194 * KeyInfo of the returned EncryptedData.
196 * @param input the stream to encrypt
197 * @param encParams primary encryption settings
198 * @param kencParams key encryption settings, or nullptr
199 * @return a stand-alone EncryptedData object, unconnected to any DOM
201 EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr);
204 * Encrypts the supplied key and returns the resulting object.
206 * @param keyBuffer raw key material to encrypt
207 * @param keyBufferSize size in bytes of raw key material
208 * @param kencParams key encryption settings
209 * @param compact true iff the encrypted representation should be made as small as possible
210 * @return a stand-alone EncryptedKey object, unconnected to any DOM
212 EncryptedKey* encryptKey(
213 const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
217 * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
219 * @param credential the key encryption key
220 * @param encryptionAlg data encryption algorithm
221 * @return a key transport algorithm
223 static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
226 void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
227 EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
229 XENCCipher* m_cipher;
230 unsigned char m_keyBuffer[32];
233 DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
237 #endif /* __xmltooling_encrypter_h__ */