xsec/xenc/XENCCipher.hpp - santuario-cpp - Git at Google

 /**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements. See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership. The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */

 /*
  * XSEC
  *
  * XENCCipher := Interface definition for main encryption worker class
  *
  * $Id$
  *
  */

 #ifndef XENCCIPHER_INCLUDE
 #define XENCCIPHER_INCLUDE

 // XSEC Includes

 #include <xsec/framework/XSECDefs.hpp>
 #include <xsec/xenc/XENCCipherData.hpp>
 #include <xsec/dsig/DSIGConstants.hpp>

 // Xerces

 XSEC_DECLARE_XERCES_CLASS(DOMElement);
 XSEC_DECLARE_XERCES_CLASS(DOMDocument);
 XSEC_DECLARE_XERCES_CLASS(BinInputStream);

 class XSECCryptoKey;
 class XENCEncryptedData;
 class XENCEncryptedKey;
 class XSECKeyInfoResolver;
 class XSECBinTXFMInputStream;
 class TXFMChain;

 /**
  * @defgroup xenc XML Encryption Implementation
  *
  * <p>The classes in this group implement the XML Encryption
  * standard.  In most cases, users should interact with these
  * functions via the XENCCipher class</p>
  *
  *\@{*/


 /**
  * @brief Main worker class for the XSEC implementation of XML
  * Encryption.
  *
  * The XENCCipher class not something that is directly defined in
  * the XML Encryption standard.  It is a control class used by the
  * library to generate encrypted XML information and to decrypt
  * information held in XML Encryption structures.
  *
  * All encryption and decryption work performed by the library is
  * handled within this class.  The other XENC classes simply
  * handle marshalling and unmarshalling of the DOM data.
  *
  */


 class XSEC_EXPORT XENCCipher {

 public:

     /** @name Constructors and Destructors */
     //@{

     virtual ~XENCCipher() {};

     //@}

     /** @name Decryption Functions */
     //@{

     /**
      * \brief Decrypt the nominated element.
      *
      * Decrypts the passed in element, which must be the root
      * node of a \<EncryptedData\> method with a type of "#Element".
      * If not, the library will throw an XSECException exception.
      *
      * This is an "all in one method".  The library will replace
      * the passed in Element (i.e. the encrypted XML data) with
      * the resultant plain text, after it has been parsed back into
      * DOM nodes
      *
      * @param element Root of EncryptedData DOM structyre to decrypt
      * @returns The owning document with the element replaced, or NULL
      * if the decryption fails for some reason (normally an exception).
      * @throws XSECException if the decryption fails, or if this is
      * not a valid EncryptedData DOM structure.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* decryptElement(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
     ) = 0;

     /**
      * \brief Decrypt the nominated element without replacing it.
      *
      * Decrypts the passed in element, which must be the root
      * node of a \<EncryptedData\> method with a type of "#Element".
      * If not, the library will throw an XSECException exception.  Rather
      * than replacing the element with the decrypted content, the
      * result is passed to the caller as an orphaned document fragment.
      *
      * @param element Root of EncryptedData DOM structyre to decrypt
      * @returns The document fragment containing the decrypted node-set.
      * @throws XSECException if the decryption fails, or if this is
      * not a valid EncryptedData DOM structure.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* decryptElementDetached(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
     ) = 0;

     /**
      * \brief Decrypt currently loaded element.
      *
      * Decrypts the an element that was previously passed in via
      * loadEncryptedData with a type of "#Element".
      * If not, the library will throw an XSECException exception.
      *
      * This is an "all in one method".  The library will replace
      * the passed in Element (i.e. the encrypted XML data) with
      * the resultant plain text, after it has been parsed back into
      * DOM nodes
      *
      * @param element Root of EncryptedData DOM structyre to decrypt
      * @returns The owning document with the element replaced, or NULL
      * if the decryption fails for some reason (normally an exception).
      * @throws XSECException if the decryption fails, or if this is
      * not a valid EncryptedData DOM structure.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* decryptElement() = 0;

     /**
      * \brief Decrypt currently loaded element without replacing it.
      *
      * Decrypts the an element that was previously passed in via
      * loadEncryptedData with a type of "#Element".
      * If not, the library will throw an XSECException exception.
      *
      * This does not replace the currently existing DOM document.  It returns
      * an "orphaned" document fragment containing the serialised version of the
      * decrypted data.
      *
      * @param element Root of EncryptedData DOM structyre to decrypt
      * @returns The owning document with the element replaced, or NULL
      * if the decryption fails for some reason (normally an exception).
      * @throws XSECException if the decryption fails, or if this is
      * not a valid EncryptedData DOM structure.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* decryptElementDetached() = 0;

     /**
      * \brief Decrypt the nominated element and put the output to an InputStream.
      *
      * Decrypts the passed in element, which must be the root
      * node of a \<EncryptedData\> method.
      *
      * This call does not change the source DOM in any way.  It simply
      * processes the encrypted data and provides an InputStream that the
      * caller can read from to read the plain text data.
      *
      * @param element Root of EncryptedData DOM structyre to decrypt
      * @returns A BinInputStream object that the application can use to
      * read the decrypted data.
      * @throws XSECException if the decryption fails, or if this is
      * not a valid EncryptedData DOM structure.
      */

     virtual XSECBinTXFMInputStream* decryptToBinInputStream(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
     ) = 0;

     /**
      * \brief Decrypt a key
      *
      * Reads in the passed in KeyInfo structure for an EncryptedKey and
      * decrypts the key to a buffer.
      *
      * @param encryptedKey the already loaded encryptedKey structure
      * @param rawKey Buffer to place the decrypted key into
      * @param maxKeySize Maximum number of bytes to place in the buffer
      */

     virtual int decryptKey(
         XENCEncryptedKey* encryptedKey,
         XMLByte* rawKey,
         int maxKeySize
     ) = 0;

     /**
      * \brief Decrypt a key directly from DOM
      *
      * Loads an EncryptedKey from DOM and then decrypts the key.
      * If a NULL buffer is passed in, will simply load the key and return
      *
      * @param keyNode Node to load from
      * @param rawKey Buffer to decrypt to
      * @param maxKeySize Length of rawKey buffer
      * @returns The number of bytes decrypted
      */

     virtual int decryptKey(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* keyNode,
         XMLByte* rawKey,
         int maxKeySize
     ) = 0;

     //@}

     /** @name Encryption Functions */
     //@{

     /**
      * \brief Encrypt the nominated element.
      *
      * Encrypts the passed in element and all children.  The element
      * is replaced with an EncryptedData element
      *
      * @param element Element (and children) to encrypt
      * @param algorithmURI algorithm URI to set
      *
      * @returns The owning document with the element replaced, or NULL
      * if the decryption fails for some reason (normally an exception).
      * @throws XSECException if the encryption fails.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* encryptElement(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
         const XMLCh* algorithmURI
     ) = 0;

     /**
      * \brief Encrypt the nominated element without affecting the current document.
      *
      * Encrypts the passed in element and all children.  The element
      * is not replaced - the return node is an "orphaned" subtree from
      * the passed in document and the original document is untouched.
      *
      * @param element Element (and children) to encrypt
      * @param algorithmURI algorithm URI to set
      *
      * @returns The resulting document fragment containing the encrypted data.
      * @throws XSECException if the encryption fails.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* encryptElementDetached(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
         const XMLCh* algorithmURI
     ) = 0;

     /**
      * \brief Encrypt the children of the nominated element
      *
      * Encrypts the all children of the passed in element, but
      * leaves the element itself in place, with one new child - an
      * EncryptedData node of type #content
      *
      * @param element Element whose children are to be encrypted
      * @param algorithmURI algorithm URI to set
      *
      * @returns The owning document with the element's children replaced, or NULL
      * if the decryption fails for some reason (normally an exception).
      * @throws XSECException if the encryption fails.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* encryptElementContent(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
         const XMLCh* algorithmURI
     ) = 0;

     /**
      * \brief Encrypt the children of the nominated element
      *
      * Encrypts the all children of the passed in element.  The input
      * DOM node set is untouched, but the function returns an orphaned
      * sub-tree owned by the passed in document containing the encrypted
      * data.
      *
      * @param element Element whose children are to be encrypted
      * @param algorithmURI algorithm URI to set
      *
      * @returns The resulting (orphaned) sub-tree from the passed in document
      * containing the encrypted data.
      * @throws XSECException if the encryption fails.
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* encryptElementContentDetached(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
         const XMLCh* algorithmURI
     ) = 0;

     /**
      * \brief Encrypt a buffer of data as a key
      *
      * Encrypts the passed in data and creates an EncryptedKey element
      *
      * @param keyBuffer The key data to encrypt
      * @param keyLen Bytes to encrypt
      * @param algorithmURI algorithm URI to set
      * @param mgfURI RSA-OAEP mask generation algorithm
      * @param oaepParams RSA-OAEP parameters, if any
      * @param oaepParamsLen RSA-OAEP parameter length
      *
      * @returns The EncryptedKey element
      */

     virtual XENCEncryptedKey* encryptKey(
         const unsigned char* keyBuffer,
         unsigned int keyLen,
         const XMLCh* algorithmURI,
         const XMLCh* mgfURI=NULL,
         unsigned char* oaepParams=NULL,
         unsigned int oaepParamsLen=0
     ) = 0;

     /**
      * \brief Encrypt an input stream to a CipherValue
      *
      * Encrypts the data passed in via a Xerces BinInputStream and places it
      * directly into a new EncryptedData element that contains a CipherValue
      *
      * @param plainText The InputStream to read the plain text from
      * @param algorithmURI algorithm URI to set
      *
      * @returns the EncryptedData element containing the CipherValue of the data
      */

     virtual XENCEncryptedData* encryptBinInputStream(
         XERCES_CPP_NAMESPACE_QUALIFIER BinInputStream* plainText,
         const XMLCh* algorithmURI
     ) = 0;

     /**
      * \brief Encrypt a TXFMChain to a CipherValue
      *
      * Encrypts the data passed in via a TXFMChain and places it
      * directly into a new EncryptedData element that contains a CipherValue.
      *
      * @note This is not really intended for client apps, but is used internally
      * and is provided for flexibility.  The "formal" method is encryptBinInputStream
      *
      * @param plainText The TXFMChain to read the plain text from
      * @param algorithmURI algorithm URI to set
      *
      * @returns the EncryptedData element containing the CipherValue of the data
      */

     virtual XENCEncryptedData* encryptTXFMChain(
         TXFMChain* plainText,
         const XMLCh* algorithmURI
     ) = 0;

     //@}
     /** @name Getter Functions */
     //@{

     /**
      * \brief Get owning document
      *
      * Every Cipher object is associated with an owning document (for generation of
      * nodes etc.)  This allows callers to retrieve this value.
      *
      * @returns The DOMDocument that is used by this object
      */

     virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* getDocument() const = 0;

     /**
      * \brief Get namespace prefix for XENC nodes
      *
      * Find the string being used by the library to prefix nodes in the
      * xenc: namespace.
      *
      * @returns XENC namespace prefix
      */

     virtual const XMLCh* getXENCNSPrefix() const = 0;

     /**
      * \brief Get the EncryptedData element
      *
      * Allows the user to get the EncryptedData element that was last processed/
      * created by this XENCCipher object.
      *
      * @returns The last used EncryptedData
      */

     virtual XENCEncryptedData* getEncryptedData() const = 0;

     /**
      * \brief Tell caller whether PrettyPrinting is active
      *
      * @returns True if Pretty Printing is active, false if not
      */

     virtual bool getPrettyPrint() const = 0;

     /**
      * \brief Tell caller whether the serialisation routines will
      * use exclusive or normal canonicalisation.
      *
      * When serialising an element prior to encryption, the c14n
      * canonicalisation routines are used.  By default, exclusive
      * c14n is used, however this can be turned off using the
      * setExclusiveC14nSerialisation call.  This function returns
      * the current state of the associated flag.
      *
      * @returns True if Exclusive c14n will be used, false if standard
      */

     virtual bool getExclusiveC14nSerialisation() const = 0;

     //@}

     /** @name Setter Functions */
     //@{

     /**
      * \brief Set decryption key for next operation
      *
      * Set the passed in key for the next decryption/encryption
      * operation.
      *
      * @param key Key to use
      * @note This function will take ownership of the key and delete it when done.
      */

     virtual void setKey(XSECCryptoKey* key) = 0;

     /**
      * \brief Set Key Encryption Key for next operation
      *
      * Set the passed in key for the next key decryption/encryption
      * operation.
      *
      * @note This key will only be used to decrypt EncryptedKey elements.
      * To set a key for decrypting an EncryptedData use #setKey instead.
      *
      * @param key Key to use
      * @note This function will take ownership of the key and delete it when done.
      */

     virtual void setKEK(XSECCryptoKey* key) = 0;

     /**
      * \brief Register a KeyInfoResolver
      *
      * Registers a KeyInfoResolver to be used by the cipher when
      * it needs to find a key to be used to decrypt some ciper text
      *
      * @note The library will use the #clone() function from the resolver
      * to get a copy.  The passed in resolver remains the property of
      * the calling function
      *
      * @param resolver Resolver to clone and use for resolving keys
      *
      */

     virtual void setKeyInfoResolver(const XSECKeyInfoResolver* resolver) = 0;

     /**
      * \brief Set prefix for XENC nodes
      *
      * Set the namespace prefix the library will use when creating
      * nodes in the XENC namespace
      */

     virtual void setXENCNSPrefix(const XMLCh* prefix) = 0;

     /**
      * \brief Set Pretty Print
      *
      * The pretty print functions controls whether the library will output
      * CR/LF after the elements it adds to a document
      *
      * By default the library will do pretty printing (flag is true)
      *
      * @param flag Value to set for Pretty Printing (true = do pretty printing)
      */

     virtual void setPrettyPrint(bool flag) = 0;

     /**
      * \brief Set whether the serialisation routines will
      * use exclusive or normal canonicalisation.
      *
      * When serialising an element prior to encryption, the c14n
      * canonicalisation routines are used.  By default, exclusive
      * c14n is used, however this can be turned off using the
      * setExclusiveC14nSerialisation call.
      *
      * @param flag Set for true if Exclusive c14n will be used,
      * false otherwise
      */

     virtual void setExclusiveC14nSerialisation(bool flag) = 0;

     //@}

     /** @name Creation and loading Functions */
     //@{

     /**
      * \brief Create a new EncryptedData element
      *
      * Method for creating a basic Encrypted Data element.  Can be used
      * in cases where an application needs to build this from scratch.
      *
      * In general, applications should use the higher level methods such
      * as #encryptElement or #encryptElementContent.
      *
      * @note The Cipher object will take on this new object as the current
      * EncryptedData and delete any currently being held.
      *
      * @param type Should this set up a CipherReference or a CipherValue
      * @param algorithm URI string to use for the Algorithm attribute in EncryptionMethod.
      * Set to NULL for no defined algorithm.
      * @param value String to set the cipher data to if the type is VALUE_TYPE.
      * for REFERENCE_TYPE CipherData elements, this should be the URI value.
      * @returns An XENCEncryptedData object
      */

     virtual XENCEncryptedData* createEncryptedData(XENCCipherData::XENCCipherDataType type,
                                                     const XMLCh* algorithm,
                                                     const XMLCh* value) = 0;

     /**
      * \brief Load an EncryptedKey element
      *
      * Take a passed in EncryptedKey DOMNode and return a loaded XENCEncryptedKey
      * object based on the DOMNode from the passed in element.
      *
      * @param keyNode Element node to load EncryptedKey from
      * @returns An XENCEncryptedKey structure (owned by the caller) based on the
      * node.
      */

     virtual XENCEncryptedKey* loadEncryptedKey(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* keyNode
         ) = 0;

     /**
      * \brief Load an EncryptedData element
      *
      * Take a passed in EncryptedData DOMNode and return a loaded XENCEncryptedData
      * object based on the DOMNode from the passed in element.
      *
      * @note The Cipher object will take on this new object as the current
      * EncryptedData and delete any currently being held.
      *
      * @param dataNode Element node to load EncryptedData from
      * @returns An XENCEncryptedData structure (owned by the caller) based on the
      * node.
      */

     virtual XENCEncryptedData* loadEncryptedData(
         XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* dataNode
         ) = 0;


     //@}

 };

 /*\@}*/

 #endif /* XENCCIPHER_INCLUDE */
	/**
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/

	/*
	* XSEC
	*
	* XENCCipher := Interface definition for main encryption worker class
	*
	* $Id$
	*
	*/

	#ifndef XENCCIPHER_INCLUDE
	#define XENCCIPHER_INCLUDE

	// XSEC Includes

	#include <xsec/framework/XSECDefs.hpp>
	#include <xsec/xenc/XENCCipherData.hpp>
	#include <xsec/dsig/DSIGConstants.hpp>

	// Xerces

	XSEC_DECLARE_XERCES_CLASS(DOMElement);
	XSEC_DECLARE_XERCES_CLASS(DOMDocument);
	XSEC_DECLARE_XERCES_CLASS(BinInputStream);

	class XSECCryptoKey;
	class XENCEncryptedData;
	class XENCEncryptedKey;
	class XSECKeyInfoResolver;
	class XSECBinTXFMInputStream;
	class TXFMChain;

	/**
	* @defgroup xenc XML Encryption Implementation
	*
	* <p>The classes in this group implement the XML Encryption
	* standard. In most cases, users should interact with these
	* functions via the XENCCipher class</p>
	*
	\@{/



	/**
	* @brief Main worker class for the XSEC implementation of XML
	* Encryption.
	*
	* The XENCCipher class not something that is directly defined in
	* the XML Encryption standard. It is a control class used by the
	* library to generate encrypted XML information and to decrypt
	* information held in XML Encryption structures.
	*
	* All encryption and decryption work performed by the library is
	* handled within this class. The other XENC classes simply
	* handle marshalling and unmarshalling of the DOM data.
	*
	*/


	class XSEC_EXPORT XENCCipher {

	public:

	/** @name Constructors and Destructors */
	//@{

	virtual ~XENCCipher() {};

	//@}

	/** @name Decryption Functions */
	//@{

	/**
	* \brief Decrypt the nominated element.
	*
	* Decrypts the passed in element, which must be the root
	* node of a \<EncryptedData\> method with a type of "#Element".
	* If not, the library will throw an XSECException exception.
	*
	* This is an "all in one method". The library will replace
	* the passed in Element (i.e. the encrypted XML data) with
	* the resultant plain text, after it has been parsed back into
	* DOM nodes
	*
	* @param element Root of EncryptedData DOM structyre to decrypt
	* @returns The owning document with the element replaced, or NULL
	* if the decryption fails for some reason (normally an exception).
	* @throws XSECException if the decryption fails, or if this is
	* not a valid EncryptedData DOM structure.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* decryptElement(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
	) = 0;

	/**
	* \brief Decrypt the nominated element without replacing it.
	*
	* Decrypts the passed in element, which must be the root
	* node of a \<EncryptedData\> method with a type of "#Element".
	* If not, the library will throw an XSECException exception. Rather
	* than replacing the element with the decrypted content, the
	* result is passed to the caller as an orphaned document fragment.
	*
	* @param element Root of EncryptedData DOM structyre to decrypt
	* @returns The document fragment containing the decrypted node-set.
	* @throws XSECException if the decryption fails, or if this is
	* not a valid EncryptedData DOM structure.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* decryptElementDetached(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
	) = 0;

	/**
	* \brief Decrypt currently loaded element.
	*
	* Decrypts the an element that was previously passed in via
	* loadEncryptedData with a type of "#Element".
	* If not, the library will throw an XSECException exception.
	*
	* This is an "all in one method". The library will replace
	* the passed in Element (i.e. the encrypted XML data) with
	* the resultant plain text, after it has been parsed back into
	* DOM nodes
	*
	* @param element Root of EncryptedData DOM structyre to decrypt
	* @returns The owning document with the element replaced, or NULL
	* if the decryption fails for some reason (normally an exception).
	* @throws XSECException if the decryption fails, or if this is
	* not a valid EncryptedData DOM structure.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* decryptElement() = 0;

	/**
	* \brief Decrypt currently loaded element without replacing it.
	*
	* Decrypts the an element that was previously passed in via
	* loadEncryptedData with a type of "#Element".
	* If not, the library will throw an XSECException exception.
	*
	* This does not replace the currently existing DOM document. It returns
	* an "orphaned" document fragment containing the serialised version of the
	* decrypted data.
	*
	* @param element Root of EncryptedData DOM structyre to decrypt
	* @returns The owning document with the element replaced, or NULL
	* if the decryption fails for some reason (normally an exception).
	* @throws XSECException if the decryption fails, or if this is
	* not a valid EncryptedData DOM structure.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* decryptElementDetached() = 0;

	/**
	* \brief Decrypt the nominated element and put the output to an InputStream.
	*
	* Decrypts the passed in element, which must be the root
	* node of a \<EncryptedData\> method.
	*
	* This call does not change the source DOM in any way. It simply
	* processes the encrypted data and provides an InputStream that the
	* caller can read from to read the plain text data.
	*
	* @param element Root of EncryptedData DOM structyre to decrypt
	* @returns A BinInputStream object that the application can use to
	* read the decrypted data.
	* @throws XSECException if the decryption fails, or if this is
	* not a valid EncryptedData DOM structure.
	*/

	virtual XSECBinTXFMInputStream* decryptToBinInputStream(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element
	) = 0;

	/**
	* \brief Decrypt a key
	*
	* Reads in the passed in KeyInfo structure for an EncryptedKey and
	* decrypts the key to a buffer.
	*
	* @param encryptedKey the already loaded encryptedKey structure
	* @param rawKey Buffer to place the decrypted key into
	* @param maxKeySize Maximum number of bytes to place in the buffer
	*/

	virtual int decryptKey(
	XENCEncryptedKey* encryptedKey,
	XMLByte* rawKey,
	int maxKeySize
	) = 0;

	/**
	* \brief Decrypt a key directly from DOM
	*
	* Loads an EncryptedKey from DOM and then decrypts the key.
	* If a NULL buffer is passed in, will simply load the key and return
	*
	* @param keyNode Node to load from
	* @param rawKey Buffer to decrypt to
	* @param maxKeySize Length of rawKey buffer
	* @returns The number of bytes decrypted
	*/

	virtual int decryptKey(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* keyNode,
	XMLByte* rawKey,
	int maxKeySize
	) = 0;

	//@}

	/** @name Encryption Functions */
	//@{

	/**
	* \brief Encrypt the nominated element.
	*
	* Encrypts the passed in element and all children. The element
	* is replaced with an EncryptedData element
	*
	* @param element Element (and children) to encrypt
	* @param algorithmURI algorithm URI to set
	*
	* @returns The owning document with the element replaced, or NULL
	* if the decryption fails for some reason (normally an exception).
	* @throws XSECException if the encryption fails.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* encryptElement(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
	const XMLCh* algorithmURI
	) = 0;

	/**
	* \brief Encrypt the nominated element without affecting the current document.
	*
	* Encrypts the passed in element and all children. The element
	* is not replaced - the return node is an "orphaned" subtree from
	* the passed in document and the original document is untouched.
	*
	* @param element Element (and children) to encrypt
	* @param algorithmURI algorithm URI to set
	*
	* @returns The resulting document fragment containing the encrypted data.
	* @throws XSECException if the encryption fails.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* encryptElementDetached(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
	const XMLCh* algorithmURI
	) = 0;

	/**
	* \brief Encrypt the children of the nominated element
	*
	* Encrypts the all children of the passed in element, but
	* leaves the element itself in place, with one new child - an
	* EncryptedData node of type #content
	*
	* @param element Element whose children are to be encrypted
	* @param algorithmURI algorithm URI to set
	*
	* @returns The owning document with the element's children replaced, or NULL
	* if the decryption fails for some reason (normally an exception).
	* @throws XSECException if the encryption fails.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* encryptElementContent(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
	const XMLCh* algorithmURI
	) = 0;

	/**
	* \brief Encrypt the children of the nominated element
	*
	* Encrypts the all children of the passed in element. The input
	* DOM node set is untouched, but the function returns an orphaned
	* sub-tree owned by the passed in document containing the encrypted
	* data.
	*
	* @param element Element whose children are to be encrypted
	* @param algorithmURI algorithm URI to set
	*
	* @returns The resulting (orphaned) sub-tree from the passed in document
	* containing the encrypted data.
	* @throws XSECException if the encryption fails.
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* encryptElementContentDetached(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* element,
	const XMLCh* algorithmURI
	) = 0;

	/**
	* \brief Encrypt a buffer of data as a key
	*
	* Encrypts the passed in data and creates an EncryptedKey element
	*
	* @param keyBuffer The key data to encrypt
	* @param keyLen Bytes to encrypt
	* @param algorithmURI algorithm URI to set
	* @param mgfURI RSA-OAEP mask generation algorithm
	* @param oaepParams RSA-OAEP parameters, if any
	* @param oaepParamsLen RSA-OAEP parameter length
	*
	* @returns The EncryptedKey element
	*/

	virtual XENCEncryptedKey* encryptKey(
	const unsigned char* keyBuffer,
	unsigned int keyLen,
	const XMLCh* algorithmURI,
	const XMLCh* mgfURI=NULL,
	unsigned char* oaepParams=NULL,
	unsigned int oaepParamsLen=0
	) = 0;

	/**
	* \brief Encrypt an input stream to a CipherValue
	*
	* Encrypts the data passed in via a Xerces BinInputStream and places it
	* directly into a new EncryptedData element that contains a CipherValue
	*
	* @param plainText The InputStream to read the plain text from
	* @param algorithmURI algorithm URI to set
	*
	* @returns the EncryptedData element containing the CipherValue of the data
	*/

	virtual XENCEncryptedData* encryptBinInputStream(
	XERCES_CPP_NAMESPACE_QUALIFIER BinInputStream* plainText,
	const XMLCh* algorithmURI
	) = 0;

	/**
	* \brief Encrypt a TXFMChain to a CipherValue
	*
	* Encrypts the data passed in via a TXFMChain and places it
	* directly into a new EncryptedData element that contains a CipherValue.
	*
	* @note This is not really intended for client apps, but is used internally
	* and is provided for flexibility. The "formal" method is encryptBinInputStream
	*
	* @param plainText The TXFMChain to read the plain text from
	* @param algorithmURI algorithm URI to set
	*
	* @returns the EncryptedData element containing the CipherValue of the data
	*/

	virtual XENCEncryptedData* encryptTXFMChain(
	TXFMChain* plainText,
	const XMLCh* algorithmURI
	) = 0;

	//@}
	/** @name Getter Functions */
	//@{

	/**
	* \brief Get owning document
	*
	* Every Cipher object is associated with an owning document (for generation of
	* nodes etc.) This allows callers to retrieve this value.
	*
	* @returns The DOMDocument that is used by this object
	*/

	virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* getDocument() const = 0;

	/**
	* \brief Get namespace prefix for XENC nodes
	*
	* Find the string being used by the library to prefix nodes in the
	* xenc: namespace.
	*
	* @returns XENC namespace prefix
	*/

	virtual const XMLCh* getXENCNSPrefix() const = 0;

	/**
	* \brief Get the EncryptedData element
	*
	* Allows the user to get the EncryptedData element that was last processed/
	* created by this XENCCipher object.
	*
	* @returns The last used EncryptedData
	*/

	virtual XENCEncryptedData* getEncryptedData() const = 0;

	/**
	* \brief Tell caller whether PrettyPrinting is active
	*
	* @returns True if Pretty Printing is active, false if not
	*/

	virtual bool getPrettyPrint() const = 0;

	/**
	* \brief Tell caller whether the serialisation routines will
	* use exclusive or normal canonicalisation.
	*
	* When serialising an element prior to encryption, the c14n
	* canonicalisation routines are used. By default, exclusive
	* c14n is used, however this can be turned off using the
	* setExclusiveC14nSerialisation call. This function returns
	* the current state of the associated flag.
	*
	* @returns True if Exclusive c14n will be used, false if standard
	*/

	virtual bool getExclusiveC14nSerialisation() const = 0;

	//@}

	/** @name Setter Functions */
	//@{

	/**
	* \brief Set decryption key for next operation
	*
	* Set the passed in key for the next decryption/encryption
	* operation.
	*
	* @param key Key to use
	* @note This function will take ownership of the key and delete it when done.
	*/

	virtual void setKey(XSECCryptoKey* key) = 0;

	/**
	* \brief Set Key Encryption Key for next operation
	*
	* Set the passed in key for the next key decryption/encryption
	* operation.
	*
	* @note This key will only be used to decrypt EncryptedKey elements.
	* To set a key for decrypting an EncryptedData use #setKey instead.
	*
	* @param key Key to use
	* @note This function will take ownership of the key and delete it when done.
	*/

	virtual void setKEK(XSECCryptoKey* key) = 0;

	/**
	* \brief Register a KeyInfoResolver
	*
	* Registers a KeyInfoResolver to be used by the cipher when
	* it needs to find a key to be used to decrypt some ciper text
	*
	* @note The library will use the #clone() function from the resolver
	* to get a copy. The passed in resolver remains the property of
	* the calling function
	*
	* @param resolver Resolver to clone and use for resolving keys
	*
	*/

	virtual void setKeyInfoResolver(const XSECKeyInfoResolver* resolver) = 0;

	/**
	* \brief Set prefix for XENC nodes
	*
	* Set the namespace prefix the library will use when creating
	* nodes in the XENC namespace
	*/

	virtual void setXENCNSPrefix(const XMLCh* prefix) = 0;

	/**
	* \brief Set Pretty Print
	*
	* The pretty print functions controls whether the library will output
	* CR/LF after the elements it adds to a document
	*
	* By default the library will do pretty printing (flag is true)
	*
	* @param flag Value to set for Pretty Printing (true = do pretty printing)
	*/

	virtual void setPrettyPrint(bool flag) = 0;

	/**
	* \brief Set whether the serialisation routines will
	* use exclusive or normal canonicalisation.
	*
	* When serialising an element prior to encryption, the c14n
	* canonicalisation routines are used. By default, exclusive
	* c14n is used, however this can be turned off using the
	* setExclusiveC14nSerialisation call.
	*
	* @param flag Set for true if Exclusive c14n will be used,
	* false otherwise
	*/

	virtual void setExclusiveC14nSerialisation(bool flag) = 0;

	//@}

	/** @name Creation and loading Functions */
	//@{

	/**
	* \brief Create a new EncryptedData element
	*
	* Method for creating a basic Encrypted Data element. Can be used
	* in cases where an application needs to build this from scratch.
	*
	* In general, applications should use the higher level methods such
	* as #encryptElement or #encryptElementContent.
	*
	* @note The Cipher object will take on this new object as the current
	* EncryptedData and delete any currently being held.
	*
	* @param type Should this set up a CipherReference or a CipherValue
	* @param algorithm URI string to use for the Algorithm attribute in EncryptionMethod.
	* Set to NULL for no defined algorithm.
	* @param value String to set the cipher data to if the type is VALUE_TYPE.
	* for REFERENCE_TYPE CipherData elements, this should be the URI value.
	* @returns An XENCEncryptedData object
	*/

	virtual XENCEncryptedData* createEncryptedData(XENCCipherData::XENCCipherDataType type,
	const XMLCh* algorithm,
	const XMLCh* value) = 0;

	/**
	* \brief Load an EncryptedKey element
	*
	* Take a passed in EncryptedKey DOMNode and return a loaded XENCEncryptedKey
	* object based on the DOMNode from the passed in element.
	*
	* @param keyNode Element node to load EncryptedKey from
	* @returns An XENCEncryptedKey structure (owned by the caller) based on the
	* node.
	*/

	virtual XENCEncryptedKey* loadEncryptedKey(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* keyNode
	) = 0;

	/**
	* \brief Load an EncryptedData element
	*
	* Take a passed in EncryptedData DOMNode and return a loaded XENCEncryptedData
	* object based on the DOMNode from the passed in element.
	*
	* @note The Cipher object will take on this new object as the current
	* EncryptedData and delete any currently being held.
	*
	* @param dataNode Element node to load EncryptedData from
	* @returns An XENCEncryptedData structure (owned by the caller) based on the
	* node.
	*/

	virtual XENCEncryptedData* loadEncryptedData(
	XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* dataNode
	) = 0;


	//@}

	};

	/\@}/

	#endif /* XENCCIPHER_INCLUDE */