xmltooling/encryption/Encrypter.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file xmltooling/encryption/Encrypter.h
  19  *
  20  * Methods for encrypting XMLObjects and other data.
  21  */
  22
  23 #if !defined(__xmltooling_encrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  24 #define __xmltooling_encrypter_h__
  25
  26 #include <xmltooling/encryption/Encryption.h>
  27
  28 #include <xsec/enc/XSECCryptoKey.hpp>
  29 #include <xsec/xenc/XENCCipher.hpp>
  30
  31 namespace xmltooling {
  32     class XMLTOOL_API Credential;
  33 };
  34
  35 namespace xmlencryption {
  36
  37     /**
  38      * Wrapper API for XML Encryption functionality.
  39      * Designed to allow both external and internal key generation as follows:
  40      *
  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).
  44      *
  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.
  47      *
  48      * If a raw key is provided, then a key object can also be created internally if the
  49      * algorithm is recognized.
  50      *
  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
  54      * or object form.
  55      *
  56      * Finally, when encrypting data, the key transport algorithm can be left blank to
  57      * derive it from the data encryption algorithm.
  58      */
  59     class XMLTOOL_API Encrypter
  60     {
  61     public:
  62
  63         /**
  64          * Structure to collect encryption requirements.
  65          */
  66         struct XMLTOOL_API EncryptionParams {
  67             /**
  68              * Constructor.
  69              *
  70              * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
  71              * the structure.
  72              *
  73              * @param algorithm     the XML Encryption algorithm constant
  74              * @param keyBuffer     buffer containing the raw key information
  75              * @param keyBufferSize the size of the raw key buffer in bytes
  76              * @param credential    optional Credential supplying the encryption key
  77              * @param compact       true iff the encrypted representation should be made as small as possible
  78              */
  79             EncryptionParams(
  80                 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES128_CBC,
  81                 const unsigned char* keyBuffer=NULL,
  82                 unsigned int keyBufferSize=0,
  83                 const xmltooling::Credential* credential=NULL,
  84                 bool compact=false
  85                 ) :  m_algorithm(algorithm), m_keyBuffer(keyBuffer), m_keyBufferSize(keyBufferSize),
  86                     m_credential(credential), m_compact(compact) {
  87             }
  88
  89             ~EncryptionParams() {}
  90
  91             /** Data encryption algorithm. */
  92             const XMLCh* m_algorithm;
  93
  94             /** Buffer containing encryption key. */
  95             const unsigned char* m_keyBuffer;
  96
  97             /** Size of buffer. */
  98             unsigned int m_keyBufferSize;
  99
 100             /** Credential containing the encryption key. */
 101             const xmltooling::Credential* m_credential;
 102
 103             /** Flag limiting the size of the encrypted XML representation. */
 104             bool m_compact;
 105         };
 106
 107         /**
 108          * Structure to collect key wrapping/transport requirements.
 109          */
 110         struct XMLTOOL_API KeyEncryptionParams {
 111             /**
 112              * Constructor.
 113              *
 114              * @param credential    a Credential supplying the key encryption key
 115              * @param algorithm     XML Encryption key wrapping or transport algorithm constant
 116              * @param recipient     optional name of recipient of encrypted key
 117              */
 118             KeyEncryptionParams(
 119                 const xmltooling::Credential& credential,
 120                 const XMLCh* algorithm=NULL,
 121                 const XMLCh* recipient=NULL
 122                 ) : m_credential(credential), m_algorithm(algorithm), m_recipient(recipient) {
 123             }
 124
 125             ~KeyEncryptionParams() {}
 126
 127             /** Credential containing key encryption key. */
 128             const xmltooling::Credential& m_credential;
 129
 130             /** Key transport or wrapping algorithm. */
 131             const XMLCh* m_algorithm;
 132
 133             /** Name of recipient that owns the key encryption key. */
 134             const XMLCh* m_recipient;
 135         };
 136
 137         Encrypter() : m_cipher(NULL) {}
 138
 139         ~Encrypter();
 140
 141         /**
 142          * Encrypts the supplied element and returns the resulting object.
 143          *
 144          * If an encryption algorithm is set, but no key, a random key will be
 145          * generated iff kencParams is non-NULL and the algorithm is known.
 146          *
 147          * If key encryption parameters are supplied, then the encryption key
 148          * is wrapped and the result placed into an EncryptedKey object in the
 149          * KeyInfo of the returned EncryptedData.
 150          *
 151          * @param element       the DOM element to encrypt
 152          * @param encParams     primary encryption settings
 153          * @param kencParams    key encryption settings, or NULL
 154          * @return a stand-alone EncryptedData object, unconnected to the source DOM
 155          */
 156         EncryptedData* encryptElement(
 157             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
 158             );
 159
 160         /**
 161          * Encrypts the supplied element's children and returns the resulting object.
 162          *
 163          * If an encryption algorithm is set, but no key, a random key will be
 164          * generated iff kencParams is non-NULL and the algorithm is known.
 165
 166          * If key encryption parameters are supplied, then the encryption key
 167          * is wrapped and the result placed into an EncryptedKey object in the
 168          * KeyInfo of the returned EncryptedData.
 169          *
 170          * @param element       parent element of children to encrypt
 171          * @param encParams     primary encryption settings
 172          * @param kencParams    key encryption settings, or NULL
 173          * @return a stand-alone EncryptedData object, unconnected to the source DOM
 174          */
 175         EncryptedData* encryptElementContent(
 176             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL
 177             );
 178
 179         /**
 180          * Encrypts the supplied input stream and returns the resulting object.
 181          *
 182          * If an encryption algorithm is set, but no key, a random key will be
 183          * generated iff kencParams is non-NULL and the algorithm is known.
 184
 185          * If key encryption parameters are supplied, then the encryption key
 186          * is wrapped and the result placed into an EncryptedKey object in the
 187          * KeyInfo of the returned EncryptedData.
 188          *
 189          * @param input         the stream to encrypt
 190          * @param encParams     primary encryption settings
 191          * @param kencParams    key encryption settings, or NULL
 192          * @return a stand-alone EncryptedData object, unconnected to any DOM
 193          */
 194         EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
 195
 196         /**
 197          * Encrypts the supplied key and returns the resulting object.
 198          *
 199          * @param keyBuffer     raw key material to encrypt
 200          * @param keyBufferSize size in bytes of raw key material
 201          * @param kencParams    key encryption settings
 202          * @param compact       true iff the encrypted representation should be made as small as possible
 203          * @return a stand-alone EncryptedKey object, unconnected to any DOM
 204          */
 205         EncryptedKey* encryptKey(
 206             const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
 207             );
 208
 209         /**
 210          * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
 211          *
 212          * @param credential    the key encryption key
 213          * @param encryptionAlg data encryption algorithm
 214          * @return a key transport algorithm
 215          */
 216         static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
 217
 218     private:
 219         void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 220         EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 221
 222         XENCCipher* m_cipher;
 223         unsigned char m_keyBuffer[32];
 224     };
 225
 226     DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
 227
 228 };
 229
 230 #endif /* __xmltooling_encrypter_h__ */