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 xmlencryption {
  32
  33     /**
  34      * Wrapper API for XML Encryption functionality.
  35      * Designed to allow both external and internal key generation as follows:
  36      *
  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).
  40      *
  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.
  43      *
  44      * If a raw key is provided, then a key object can also be created internally if the
  45      * algorithm is recognized.
  46      *
  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
  50      * or object form.
  51      */
  52     class XMLTOOL_API Encrypter
  53     {
  54     public:
  55
  56         /**
  57          * Structure to collect encryption requirements.
  58          */
  59         struct XMLTOOL_API EncryptionParams {
  60
  61             /**
  62              * Constructor.
  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.
  65              *
  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
  71              */
  72             EncryptionParams(
  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) {
  79             }
  80
  81             ~EncryptionParams() {
  82                 delete m_key;
  83                 delete m_keyInfo;
  84             }
  85         private:
  86             const unsigned char* m_keyBuffer;
  87             unsigned int m_keyBufferSize;
  88             XSECCryptoKey* m_key;
  89             xmlsignature::KeyInfo* m_keyInfo;
  90             const XMLCh* m_algorithm;
  91
  92             friend class Encrypter;
  93         };
  94
  95         /**
  96          * Structure to collect key wrapping/transport requirements.
  97          */
  98         struct XMLTOOL_API KeyEncryptionParams {
  99
 100             /**
 101              * Constructor.
 102              * The algorithm and recipient constants <strong>MUST</strong> be accessible for the life of the
 103              * structure. Using a static constant suffices for this. The other objects will be destroyed if
 104              * when the structure is destroyed.
 105              *
 106              * @param algorithm     the XML Encryption key wrapping or transport algorithm constant
 107              * @param key           the key encryption key to use
 108              * @param recipient     optional name of recipient of encrypted key
 109              * @param keyInfo       a KeyInfo object to place within the EncryptedKey structure that describes the KEK
 110              */
 111             KeyEncryptionParams(
 112                 const XMLCh* algorithm,
 113                 XSECCryptoKey* key,
 114                 const XMLCh* recipient=NULL,
 115                 xmlsignature::KeyInfo* keyInfo=NULL
 116                 ) : m_algorithm(algorithm), m_key(key), m_recipient(recipient), m_keyInfo(keyInfo) {
 117             }
 118
 119             ~KeyEncryptionParams() {
 120                 delete m_key;
 121                 delete m_keyInfo;
 122             }
 123         private:
 124             const XMLCh* m_algorithm;
 125             XSECCryptoKey* m_key;
 126             const XMLCh* m_recipient;
 127             xmlsignature::KeyInfo* m_keyInfo;
 128
 129             friend class Encrypter;
 130         };
 131
 132         Encrypter() : m_cipher(NULL) {}
 133
 134         ~Encrypter();
 135
 136         /**
 137          * Encrypts the supplied element and returns the resulting object.
 138          *
 139          * If an encryption algorithm is set, but no key, a random key will be
 140          * generated iff kencParams is non-NULL and the algorithm is known.
 141          *
 142          * If key encryption parameters are supplied, then the encryption key
 143          * is wrapped and the result placed into an EncryptedKey object in the
 144          * KeyInfo of the returned EncryptedData.
 145          *
 146          * @param element       the DOM element to encrypt
 147          * @param encParams     primary encryption settings
 148          * @param kencParams    key encryption settings, or NULL
 149          * @return a stand-alone EncryptedData object, unconnected to the source DOM
 150          */
 151         EncryptedData* encryptElement(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
 152
 153         /**
 154          * Encrypts the supplied element's children and returns the resulting object.
 155          *
 156          * If an encryption algorithm is set, but no key, a random key will be
 157          * generated iff kencParams is non-NULL and the algorithm is known.
 158
 159          * If key encryption parameters are supplied, then the encryption key
 160          * is wrapped and the result placed into an EncryptedKey object in the
 161          * KeyInfo of the returned EncryptedData.
 162          *
 163          * @param element       parent element of children to encrypt
 164          * @param encParams     primary encryption settings
 165          * @param kencParams    key encryption settings, or NULL
 166          * @return a stand-alone EncryptedData object, unconnected to the source DOM
 167          */
 168         EncryptedData* encryptElementContent(DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
 169
 170         /**
 171          * Encrypts the supplied input stream and returns the resulting object.
 172          *
 173          * If an encryption algorithm is set, but no key, a random key will be
 174          * generated iff kencParams is non-NULL and the algorithm is known.
 175
 176          * If key encryption parameters are supplied, then the encryption key
 177          * is wrapped and the result placed into an EncryptedKey object in the
 178          * KeyInfo of the returned EncryptedData.
 179          *
 180          * @param input         the stream to encrypt
 181          * @param encParams     primary encryption settings
 182          * @param kencParams    key encryption settings, or NULL
 183          * @return a stand-alone EncryptedData object, unconnected to any DOM
 184          */
 185         EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=NULL);
 186
 187         /**
 188          * Encrypts the supplied key and returns the resulting object.
 189          *
 190          * @param keyBuffer     raw key material to encrypt
 191          * @param keyBufferSize size in bytes of raw key material
 192          * @param kencParams    key encryption settings
 193          * @return a stand-alone EncryptedKey object, unconnected to any DOM
 194          */
 195         EncryptedKey* encryptKey(const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams);
 196
 197     private:
 198         void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 199         EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 200
 201         XENCCipher* m_cipher;
 202         unsigned char m_keyBuffer[32];
 203     };
 204
 205     DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
 206
 207 };
 208
 209 #endif /* __xmltooling_encrypter_h__ */