Main Page | Modules | Class Hierarchy | Class List | Directories | File List | Class Members | File Members | Related Pages

XENCCipher Class Reference

#include <XENCCipher.hpp>

List of all members.


Detailed Description

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.


Public Member Functions

Constructors and Destructors
virtual ~XENCCipher ()
Decryption Functions
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMDocument * 
decryptElement (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element)=0
 Decrypt the nominated element.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMNode * 
decryptElementDetached (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element)=0
 Decrypt the nominated element without replacing it.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMDocument * 
decryptElement (void)=0
 Decrypt currently loaded element.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMNode * 
decryptElementDetached (void)=0
 Decrypt currently loaded element without replacing it.
virtual XSECBinTXFMInputStreamdecryptToBinInputStream (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element)=0
 Decrypt the nominated element and put the output to an InputStream.
virtual int decryptKey (XENCEncryptedKey *encryptedKey, XMLByte *rawKey, int maxKeySize)=0
 Decrypt a key.
virtual int decryptKey (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *keyNode, XMLByte *rawKey, int maxKeySize)=0
 Decrypt a key directly from DOM.
Encryption Functions
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMDocument * 
encryptElement (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt the nominated element.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMNode * 
encryptElementDetached (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt the nominated element without affecting the current document.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMDocument * 
encryptElementContent (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt the children of the nominated element.
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMNode * 
encryptElementContentDetached (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *element, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt the children of the nominated element.
virtual XENCEncryptedKeyencryptKey (const unsigned char *keyBuffer, unsigned int keyLen, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt a buffer of data as a key.
virtual XENCEncryptedDataencryptBinInputStream (XERCES_CPP_NAMESPACE_QUALIFIER BinInputStream *plainText, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt an input stream to a CipherValue.
virtual XENCEncryptedDataencryptTXFMChain (TXFMChain *plainText, encryptionMethod em, const XMLCh *algorithmURI=NULL)=0
 Encrypt a TXFMChain to a CipherValue.
Getter Functions
virtual XERCES_CPP_NAMESPACE_QUALIFIER
DOMDocument * 
getDocument (void)=0
 Get owning document.
virtual const XMLCh * getXENCNSPrefix (void) const =0
 Get namespace prefix for XENC nodes.
virtual XENCEncryptedDatagetEncryptedData (void)=0
 Get the EncryptedData element.
virtual bool getPrettyPrint (void)=0
 Tell caller whether PrettyPrinting is active.
virtual bool getExclusiveC14nSerialisation (void)=0
 Tell caller whether the serialisation routines will use exclusive or normal canonicalisation.
Setter Functions
virtual void setKey (XSECCryptoKey *key)=0
 Set decryption key for next operation.
virtual void setKEK (XSECCryptoKey *key)=0
 Set Key Encryption Key for next operation.
virtual void setKeyInfoResolver (const XSECKeyInfoResolver *resolver)=0
 Register a KeyInfoResolver.
virtual void setXENCNSPrefix (const XMLCh *prefix)=0
 Set prefix for XENC nodes.
virtual void setPrettyPrint (bool flag)=0
 Set Pretty Print.
virtual void setExclusiveC14nSerialisation (bool flag)=0
 Set whether the serialisation routines will use exclusive or normal canonicalisation.
Creation and loading Functions
virtual XENCEncryptedDatacreateEncryptedData (XENCCipherData::XENCCipherDataType type, const XMLCh *algorithm, const XMLCh *value)=0
 Create a new EncryptedData element.
virtual XENCEncryptedKeyloadEncryptedKey (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *keyNode)=0
 Load an EncryptedKey element.
virtual XENCEncryptedDataloadEncryptedData (XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *dataNode)=0
 Load an EncryptedData element.


Constructor & Destructor Documentation

virtual XENCCipher::~XENCCipher  )  [inline, virtual]
 


Member Function Documentation

virtual XENCEncryptedData* XENCCipher::createEncryptedData XENCCipherData::XENCCipherDataType  type,
const XMLCh *  algorithm,
const XMLCh *  value
[pure virtual]
 

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.
Parameters:
type Should this set up a CipherReference or a CipherValue
algorithm URI string to use for the Algorithm attribute in EncryptionMethod. Set to NULL for no defined algorithm.
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 XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* XENCCipher::decryptElement void   )  [pure virtual]
 

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

Parameters:
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).
Exceptions:
XSECException if the decryption fails, or if this is not a valid EncryptedData DOM structure.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* XENCCipher::decryptElement XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element  )  [pure virtual]
 

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

Parameters:
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).
Exceptions:
XSECException if the decryption fails, or if this is not a valid EncryptedData DOM structure.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* XENCCipher::decryptElementDetached void   )  [pure virtual]
 

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.

Parameters:
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).
Exceptions:
XSECException if the decryption fails, or if this is not a valid EncryptedData DOM structure.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* XENCCipher::decryptElementDetached XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element  )  [pure virtual]
 

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.

Parameters:
element Root of EncryptedData DOM structyre to decrypt
Returns:
The document fragment containing the decrypted node-set.
Exceptions:
XSECException if the decryption fails, or if this is not a valid EncryptedData DOM structure.

virtual int XENCCipher::decryptKey XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  keyNode,
XMLByte *  rawKey,
int  maxKeySize
[pure virtual]
 

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

Parameters:
keyNode Node to load from
rawKey Buffer to decrypt to
maxKeySize Length of rawKey buffer
Returns:
The number of bytes decrypted

virtual int XENCCipher::decryptKey XENCEncryptedKey encryptedKey,
XMLByte *  rawKey,
int  maxKeySize
[pure virtual]
 

Decrypt a key.

Reads in the passed in KeyInfo structure for an EncryptedKey and decrypts the key to a buffer.

Parameters:
encryptedKey the already loaded encryptedKey structure
rawKey Buffer to place the decrypted key into
maxKeySize Maximum number of bytes to place in the buffer

virtual XSECBinTXFMInputStream* XENCCipher::decryptToBinInputStream XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element  )  [pure virtual]
 

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.

Parameters:
element Root of EncryptedData DOM structyre to decrypt
Returns:
A BinInputStream object that the application can use to read the decrypted data.
Exceptions:
XSECException if the decryption fails, or if this is not a valid EncryptedData DOM structure.

virtual XENCEncryptedData* XENCCipher::encryptBinInputStream XERCES_CPP_NAMESPACE_QUALIFIER BinInputStream *  plainText,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

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

Parameters:
plainText The InputStream to read the plain text from
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI if ENCRYPT_NONE is used for em, this will be used as the algorithm URI
Returns:
the EncryptedData element containing the CipherValue of the data

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* XENCCipher::encryptElement XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

Encrypt the nominated element.

Encrypts the passed in element and all children. The element is replaced with an EncryptedData element

Parameters:
element Element (and children) to encrypt
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI If ENCRYPT_NONE is passed in, this will be used to set the algorithm URI. If this is also NULL - no EncryptionMethod will be set. NULL Value Unsupported if em not set! It's use could cause problems!
Returns:
The owning document with the element replaced, or NULL if the decryption fails for some reason (normally an exception).
Exceptions:
XSECException if the encryption fails.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* XENCCipher::encryptElementContent XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

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

Parameters:
element Element whose children are to be encrypted
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI If ENCRYPT_NONE is passed in, this will be used to set the algorithm URI. If this is also NULL - no EncryptionMethod will be set. NULL Value Unsupported if em not set! It's use could cause problems!
Returns:
The owning document with the element's children replaced, or NULL if the decryption fails for some reason (normally an exception).
Exceptions:
XSECException if the encryption fails.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* XENCCipher::encryptElementContentDetached XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

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.

Parameters:
element Element whose children are to be encrypted
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI If ENCRYPT_NONE is passed in, this will be used to set the algorithm URI. If this is also NULL - no EncryptionMethod will be set. NULL Value Unsupported if em not set! It's use could cause problems!
Returns:
The resulting (orphaned) sub-tree from the passed in document containing the encrypted data.
Exceptions:
XSECException if the encryption fails.

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMNode* XENCCipher::encryptElementDetached XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  element,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

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.

Parameters:
element Element (and children) to encrypt
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI If ENCRYPT_NONE is passed in, this will be used to set the algorithm URI. If this is also NULL - no EncryptionMethod will be set. NULL Value Unsupported if em not set! It's use could cause problems!
Returns:
The resulting document fragment containing the encrypted data.
Exceptions:
XSECException if the encryption fails.

virtual XENCEncryptedKey* XENCCipher::encryptKey const unsigned char *  keyBuffer,
unsigned int  keyLen,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

Encrypt a buffer of data as a key.

Encrypts the passed in data and creates an EncryptedKey element

Parameters:
keyBuffer The key data to encrypt
keyLen Bytes to encrypt
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI If ENCRYPT_NONE is used for em, this will be used as the algorithm URI.
Returns:
The EncryptedKey element

virtual XENCEncryptedData* XENCCipher::encryptTXFMChain TXFMChain plainText,
encryptionMethod  em,
const XMLCh *  algorithmURI = NULL
[pure virtual]
 

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
Parameters:
plainText The TXFMChain to read the plain text from
em The encryptionMethod to use for this encryption. Use ENCRYPT_NONE if a user defined type is required.
algorithmURI if ENCRYPT_NONE is used for em, this will be used as the algorithm URI
Returns:
the EncryptedData element containing the CipherValue of the data

virtual XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* XENCCipher::getDocument void   )  [pure virtual]
 

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 XENCEncryptedData* XENCCipher::getEncryptedData void   )  [pure virtual]
 

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 bool XENCCipher::getExclusiveC14nSerialisation void   )  [pure virtual]
 

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 XENCCipher::getPrettyPrint void   )  [pure virtual]
 

Tell caller whether PrettyPrinting is active.

Returns:
True if Pretty Printing is active, false if not

virtual const XMLCh* XENCCipher::getXENCNSPrefix void   )  const [pure virtual]
 

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 XENCEncryptedData* XENCCipher::loadEncryptedData XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  dataNode  )  [pure virtual]
 

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.
Parameters:
dataNode Element node to load EncryptedData from
Returns:
An XENCEncryptedData structure (owned by the caller) based on the node.

virtual XENCEncryptedKey* XENCCipher::loadEncryptedKey XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *  keyNode  )  [pure virtual]
 

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.

Parameters:
keyNode Element node to load EncryptedKey from
Returns:
An XENCEncryptedKey structure (owned by the caller) based on the node.

virtual void XENCCipher::setExclusiveC14nSerialisation bool  flag  )  [pure virtual]
 

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.

Parameters:
flag Set for true if Exclusive c14n will be used, false otherwise

virtual void XENCCipher::setKEK XSECCryptoKey key  )  [pure virtual]
 

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.
Parameters:
key Key to use
Note:
This function will take ownership of the key and delete it when done.

virtual void XENCCipher::setKey XSECCryptoKey key  )  [pure virtual]
 

Set decryption key for next operation.

Set the passed in key for the next decryption/encryption operation.

Parameters:
key Key to use
Note:
This function will take ownership of the key and delete it when done.

virtual void XENCCipher::setKeyInfoResolver const XSECKeyInfoResolver resolver  )  [pure virtual]
 

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
Parameters:
resolver Resolver to clone and use for resolving keys

virtual void XENCCipher::setPrettyPrint bool  flag  )  [pure virtual]
 

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)

Parameters:
flag Value to set for Pretty Printing (true = do pretty printing)

virtual void XENCCipher::setXENCNSPrefix const XMLCh *  prefix  )  [pure virtual]
 

Set prefix for XENC nodes.

Set the namespace prefix the library will use when creating nodes in the XENC namespace


The documentation for this class was generated from the following file:
Generated on Sun Jan 28 19:48:55 2007 for XML-Security-C by  doxygen 1.4.2