2 * Copyright 2001-2007 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/encryption/Encryption.h>
28 #include <xsec/enc/XSECCryptoKey.hpp>
29 #include <xsec/xenc/XENCCipher.hpp>
31 namespace xmltooling {
32 class XMLTOOL_API Credential;
35 namespace xmlencryption {
38 * Wrapper API for XML Encryption functionality.
39 * Designed to allow both external and internal key generation as follows:
41 * If no keying material is supplied, then the algorithm MAY be recognized
42 * and a key can be generated internally. This is only done if a KeyEncryptionParams
43 * structure is also supplied to the operation (otherwise the key would be lost).
45 * If an XSECCryptoKey is supplied, then it is used directly, but if KeyEncryptionParams
46 * are supplied, an exception will result unless the raw key buffer is also supplied.
48 * If a raw key is provided, then a key object can also be created internally if the
49 * algorithm is recognized.
51 * Summing up, if KeyEncryptionParams are used, a raw key must be available or the
52 * key can be generated when the encryption algorithm itself is a standard one. If
53 * no KeyEncryptionParams are supplied, then the key must be supplied either in raw
56 * Finally, when encrypting data, the key transport algorithm can be left blank to
57 * derive it from the data encryption algorithm.
59 class XMLTOOL_API Encrypter
64 * Structure to collect encryption requirements.
66 struct XMLTOOL_API EncryptionParams {
71 * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
74 * @param algorithm the XML Encryption algorithm constant
75 * @param keyBuffer buffer containing the raw key information
76 * @param keyBufferSize the size of the raw key buffer in bytes
77 * @param credential optional Credential supplying the encryption key
78 * @param compact true iff the encrypted representation should be made as small as possible
81 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES256_CBC,
82 const unsigned char* keyBuffer=NULL,
83 unsigned int keyBufferSize=0,
84 const xmltooling::Credential* credential=NULL,
86 ) : m_algorithm(algorithm), m_keyBuffer(keyBuffer), m_keyBufferSize(keyBufferSize),
87 m_credential(credential), m_compact(compact) {
90 ~EncryptionParams() {}
92 const XMLCh* m_algorithm;
93 const unsigned char* m_keyBuffer;
94 unsigned int m_keyBufferSize;
95 const xmltooling::Credential* m_credential;
98 friend class Encrypter;
102 * Structure to collect key wrapping/transport requirements.
104 struct XMLTOOL_API KeyEncryptionParams {
109 * @param credential a Credential supplying the key encryption key
110 * @param algorithm XML Encryption key wrapping or transport algorithm constant
111 * @param recipient optional name of recipient of encrypted key
114 const xmltooling::Credential& credential,
115 const XMLCh* algorithm=NULL,
116 const XMLCh* recipient=NULL
117 ) : m_credential(credential), m_algorithm(algorithm), m_recipient(recipient) {
120 ~KeyEncryptionParams() {}
122 const xmltooling::Credential& m_credential;
123 const XMLCh* m_algorithm;
124 const XMLCh* m_recipient;
126 friend class Encrypter;
129 Encrypter() : m_cipher(NULL) {}
134 * Encrypts the supplied element and returns the resulting object.
136 * If an encryption algorithm is set, but no key, a random key will be
137 * generated iff kencParams is non-NULL and the algorithm is known.
139 * If key encryption parameters are supplied, then the encryption key
140 * is wrapped and the result placed into an EncryptedKey object in the
141 * KeyInfo of the returned EncryptedData.
143 * @param element the DOM element to encrypt
144 * @param encParams primary encryption settings
145 * @param kencParams key encryption settings, or NULL
146 * @return a stand-alone EncryptedData object, unconnected to the source DOM
148 EncryptedData* encryptElement(
149 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
153 * Encrypts the supplied element's children and returns the resulting object.
155 * If an encryption algorithm is set, but no key, a random key will be
156 * generated iff kencParams is non-NULL and the algorithm is known.
158 * If key encryption parameters are supplied, then the encryption key
159 * is wrapped and the result placed into an EncryptedKey object in the
160 * KeyInfo of the returned EncryptedData.
162 * @param element parent element of children to encrypt
163 * @param encParams primary encryption settings
164 * @param kencParams key encryption settings, or NULL
165 * @return a stand-alone EncryptedData object, unconnected to the source DOM
167 EncryptedData* encryptElementContent(
168 xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
172 * Encrypts the supplied input stream and returns the resulting object.
174 * If an encryption algorithm is set, but no key, a random key will be
175 * generated iff kencParams is non-NULL and the algorithm is known.
177 * If key encryption parameters are supplied, then the encryption key
178 * is wrapped and the result placed into an EncryptedKey object in the
179 * KeyInfo of the returned EncryptedData.
181 * @param input the stream to encrypt
182 * @param encParams primary encryption settings
183 * @param kencParams key encryption settings, or NULL
184 * @return a stand-alone EncryptedData object, unconnected to any DOM
186 EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
189 * Encrypts the supplied key and returns the resulting object.
191 * @param keyBuffer raw key material to encrypt
192 * @param keyBufferSize size in bytes of raw key material
193 * @param kencParams key encryption settings
194 * @param compact true iff the encrypted representation should be made as small as possible
195 * @return a stand-alone EncryptedKey object, unconnected to any DOM
197 EncryptedKey* encryptKey(
198 const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
202 * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
204 * @param algorithm data encryption algorithm
205 * @return a key transport algorithm
207 static const XMLCh* getKeyTransportAlgorithm(const XMLCh* algorithm) {
208 if (xercesc::XMLString::equals(algorithm,DSIGConstants::s_unicodeStrURI3DES_CBC))
209 return DSIGConstants::s_unicodeStrURIRSA_1_5;
211 return DSIGConstants::s_unicodeStrURIRSA_OAEP_MGFP1;
215 void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
216 EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
218 XENCCipher* m_cipher;
219 unsigned char m_keyBuffer[32];
222 DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
226 #endif /* __xmltooling_encrypter_h__ */