| /** |
| * 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 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 */ |
| |