xmltooling/encryption/Encrypter.h

   1 /*
   2  *  Copyright 2001-2010 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/exceptions.h>
  27
  28 #include <xsec/dsig/DSIGConstants.hpp>
  29
  30 class XENCCipher;
  31
  32 namespace xmltooling {
  33     class XMLTOOL_API Credential;
  34 };
  35
  36 namespace xmlencryption {
  37
  38     class XMLTOOL_API EncryptedData;
  39     class XMLTOOL_API EncryptedKey;
  40
  41     /**
  42      * Wrapper API for XML Encryption functionality.
  43      * Designed to allow both external and internal key generation as follows:
  44      *
  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).
  48      *
  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.
  51      *
  52      * If a raw key is provided, then a key object can also be created internally if the
  53      * algorithm is recognized.
  54      *
  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
  58      * or object form.
  59      *
  60      * Finally, when encrypting data, the key transport algorithm can be left blank to
  61      * derive it from the data encryption algorithm.
  62      */
  63     class XMLTOOL_API Encrypter
  64     {
  65     public:
  66
  67         /**
  68          * Structure to collect encryption requirements.
  69          */
  70         struct XMLTOOL_API EncryptionParams {
  71             /**
  72              * Constructor.
  73              *
  74              * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
  75              * the structure.
  76              *
  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
  82              */
  83             EncryptionParams(
  84 #ifdef XSEC_OPENSSL_HAVE_AES
  85                 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES128_CBC,
  86 #else
  87                 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURI3DES_CBC,
  88 #endif
  89                 const unsigned char* keyBuffer=nullptr,
  90                 unsigned int keyBufferSize=0,
  91                 const xmltooling::Credential* credential=nullptr,
  92                 bool compact=false
  93                 );
  94
  95             ~EncryptionParams();
  96
  97             /** Data encryption algorithm. */
  98             const XMLCh* m_algorithm;
  99
 100             /** Buffer containing encryption key. */
 101             const unsigned char* m_keyBuffer;
 102
 103             /** Size of buffer. */
 104             unsigned int m_keyBufferSize;
 105
 106             /** Credential containing the encryption key. */
 107             const xmltooling::Credential* m_credential;
 108
 109             /** Flag limiting the size of the encrypted XML representation. */
 110             bool m_compact;
 111         };
 112
 113         /**
 114          * Structure to collect key wrapping/transport requirements.
 115          */
 116         struct XMLTOOL_API KeyEncryptionParams {
 117             /**
 118              * Constructor.
 119              *
 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
 123              */
 124             KeyEncryptionParams(
 125                 const xmltooling::Credential& credential, const XMLCh* algorithm=nullptr, const XMLCh* recipient=nullptr
 126                 );
 127
 128             ~KeyEncryptionParams();
 129
 130             /** Credential containing key encryption key. */
 131             const xmltooling::Credential& m_credential;
 132
 133             /** Key transport or wrapping algorithm. */
 134             const XMLCh* m_algorithm;
 135
 136             /** Name of recipient that owns the key encryption key. */
 137             const XMLCh* m_recipient;
 138         };
 139
 140         Encrypter();
 141
 142         virtual ~Encrypter();
 143
 144         /**
 145          * Encrypts the supplied element and returns the resulting object.
 146          *
 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.
 149          *
 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.
 153          *
 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
 158          */
 159         EncryptedData* encryptElement(
 160             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
 161             );
 162
 163         /**
 164          * Encrypts the supplied element's children and returns the resulting object.
 165          *
 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.
 168
 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.
 172          *
 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
 177          */
 178         EncryptedData* encryptElementContent(
 179             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
 180             );
 181
 182         /**
 183          * Encrypts the supplied input stream and returns the resulting object.
 184          *
 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.
 187
 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.
 191          *
 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
 196          */
 197         EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr);
 198
 199         /**
 200          * Encrypts the supplied key and returns the resulting object.
 201          *
 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
 207          */
 208         EncryptedKey* encryptKey(
 209             const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
 210             );
 211
 212         /**
 213          * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
 214          *
 215          * @param credential    the key encryption key
 216          * @param encryptionAlg data encryption algorithm
 217          * @return a key transport algorithm
 218          */
 219         static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
 220
 221     private:
 222         void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 223         EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 224
 225         XENCCipher* m_cipher;
 226         unsigned char m_keyBuffer[32];
 227     };
 228
 229     DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
 230
 231 };
 232
 233 #endif /* __xmltooling_encrypter_h__ */