xmltooling/encryption/Encrypter.h

   1 /**
   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.
   6  *
   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
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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.
  19  */
  20
  21 /**
  22  * @file xmltooling/encryption/Encrypter.h
  23  *
  24  * Methods for encrypting XMLObjects and other data.
  25  */
  26
  27 #if !defined(__xmltooling_encrypter_h__) && !defined(XMLTOOLING_NO_XMLSEC)
  28 #define __xmltooling_encrypter_h__
  29
  30 #include <xmltooling/exceptions.h>
  31
  32 #include <xsec/dsig/DSIGConstants.hpp>
  33
  34 class XENCCipher;
  35
  36 namespace xmltooling {
  37     class XMLTOOL_API Credential;
  38 };
  39
  40 namespace xmlencryption {
  41
  42     class XMLTOOL_API EncryptedData;
  43     class XMLTOOL_API EncryptedKey;
  44
  45     /**
  46      * Wrapper API for XML Encryption functionality.
  47      * Designed to allow both external and internal key generation as follows:
  48      *
  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).
  52      *
  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.
  55      *
  56      * If a raw key is provided, then a key object can also be created internally if the
  57      * algorithm is recognized.
  58      *
  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
  62      * or object form.
  63      *
  64      * Finally, when encrypting data, the key transport algorithm can be left blank to
  65      * derive it from the data encryption algorithm.
  66      */
  67     class XMLTOOL_API Encrypter
  68     {
  69     public:
  70
  71         /**
  72          * Structure to collect encryption requirements.
  73          */
  74         struct XMLTOOL_API EncryptionParams {
  75             /**
  76              * Constructor.
  77              *
  78              * The algorithm constant and key buffer <strong>MUST</strong> be accessible for the life of
  79              * the structure.
  80              *
  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
  86              */
  87             EncryptionParams(
  88 #ifdef XSEC_OPENSSL_HAVE_AES
  89                 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURIAES128_CBC,
  90 #else
  91                 const XMLCh* algorithm=DSIGConstants::s_unicodeStrURI3DES_CBC,
  92 #endif
  93                 const unsigned char* keyBuffer=nullptr,
  94                 unsigned int keyBufferSize=0,
  95                 const xmltooling::Credential* credential=nullptr,
  96                 bool compact=false
  97                 );
  98
  99             ~EncryptionParams();
 100
 101             /** Data encryption algorithm. */
 102             const XMLCh* m_algorithm;
 103
 104             /** Buffer containing encryption key. */
 105             const unsigned char* m_keyBuffer;
 106
 107             /** Size of buffer. */
 108             unsigned int m_keyBufferSize;
 109
 110             /** Credential containing the encryption key. */
 111             const xmltooling::Credential* m_credential;
 112
 113             /** Flag limiting the size of the encrypted XML representation. */
 114             bool m_compact;
 115         };
 116
 117         /**
 118          * Structure to collect key wrapping/transport requirements.
 119          */
 120         struct XMLTOOL_API KeyEncryptionParams {
 121             /**
 122              * Constructor.
 123              *
 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
 127              */
 128             KeyEncryptionParams(
 129                 const xmltooling::Credential& credential, const XMLCh* algorithm=nullptr, const XMLCh* recipient=nullptr
 130                 );
 131
 132             ~KeyEncryptionParams();
 133
 134             /** Credential containing key encryption key. */
 135             const xmltooling::Credential& m_credential;
 136
 137             /** Key transport or wrapping algorithm. */
 138             const XMLCh* m_algorithm;
 139
 140             /** Name of recipient that owns the key encryption key. */
 141             const XMLCh* m_recipient;
 142         };
 143
 144         Encrypter();
 145
 146         virtual ~Encrypter();
 147
 148         /**
 149          * Encrypts the supplied element and returns the resulting object.
 150          *
 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.
 153          *
 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.
 157          *
 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
 162          */
 163         EncryptedData* encryptElement(
 164             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
 165             );
 166
 167         /**
 168          * Encrypts the supplied element's children and returns the resulting object.
 169          *
 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.
 172
 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.
 176          *
 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
 181          */
 182         EncryptedData* encryptElementContent(
 183             xercesc::DOMElement* element, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr
 184             );
 185
 186         /**
 187          * Encrypts the supplied input stream and returns the resulting object.
 188          *
 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.
 191
 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.
 195          *
 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
 200          */
 201         EncryptedData* encryptStream(std::istream& input, EncryptionParams& encParams, KeyEncryptionParams* kencParams=nullptr);
 202
 203         /**
 204          * Encrypts the supplied key and returns the resulting object.
 205          *
 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
 211          */
 212         EncryptedKey* encryptKey(
 213             const unsigned char* keyBuffer, unsigned int keyBufferSize, KeyEncryptionParams& kencParams, bool compact=false
 214             );
 215
 216         /**
 217          * Maps a data encryption algorithm to an appropriate key transport algorithm to use.
 218          *
 219          * @param credential    the key encryption key
 220          * @param encryptionAlg data encryption algorithm
 221          * @return a key transport algorithm
 222          */
 223         static const XMLCh* getKeyTransportAlgorithm(const xmltooling::Credential& credential, const XMLCh* encryptionAlg);
 224
 225     private:
 226         void checkParams(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 227         EncryptedData* decorateAndUnmarshall(EncryptionParams& encParams, KeyEncryptionParams* kencParams);
 228
 229         XENCCipher* m_cipher;
 230         unsigned char m_keyBuffer[32];
 231     };
 232
 233     DECL_XMLTOOLING_EXCEPTION(EncryptionException,XMLTOOL_EXCEPTIONAPI(XMLTOOL_API),xmlencryption,xmltooling::XMLSecurityException,Exceptions in encryption processing);
 234
 235 };
 236
 237 #endif /* __xmltooling_encrypter_h__ */