com.entrust.toolkit.xencrypt.core

Class Decryptor

java.lang.Object

com.entrust.toolkit.xencrypt.core.EncryptionHandler

com.entrust.toolkit.xencrypt.core.Decryptor

public final class Decryptor
extends EncryptionHandler

The Decryptor class decrypts encrypted elements in an XML document.

See Also:

Encryptor

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Vector	m_decryptedBinary Holds the decrypted binary data

Fields inherited from class com.entrust.toolkit.xencrypt.core.EncryptionHandler

m_DOMdocument, m_XMLEInit

Constructor Summary

Constructors

Constructor and Description
Decryptor(XMLEInit initializer) Initializes the Toolkit to decrypt external binary data.
Decryptor(XMLEInit initializer, java.io.InputStream document) Parses an encrypted XML document to a DOM tree and initializes the Toolkit to decrypt DOM elements within that document.

Method Summary

Modifier and Type	Method and Description
void	addKeyEncryptionkey(byte[] id, javax.crypto.SecretKey kenEncryptionKey) Enables a particular Decryptor instance to decrypt DOM elements.
void	addUser(User user) Enables a particular Decryptor instance to decrypt DOM elements that were encrypted for the specified User.
boolean	decrypt() Decrypts all <EncryptedData> DOM elements that are encrypted for any User in this Decryptor instance.
java.lang.String	decrypt(org.w3c.dom.Element encryptedDataElement) Decrypts a specified DOM element.
byte[]	decryptBinary(org.w3c.dom.Element encryptedDataElement) Decrypts a specified DOM element for encrypted external binary data.
void	decryptComplete() Called by an application to signal that it has finished decrypting elements in an XML document.
java.util.Vector	getDecryptedBinary()
java.lang.String	getEncryptedDataType(org.w3c.dom.Element encryptedDataElement) Returns the the value of the 'Type' attribute in an <EncryptedData> element.
java.util.Vector	getRecipients() Retrieves a list of the recipients who can decrypt at least one <EncryptedData> DOM element in this document.
java.util.Vector	getRecipients(org.w3c.dom.Element encryptedDataElement) Retrieves a list of the recipients who can decrypt this particular <EncryptedData> DOM element.
java.lang.String	getSymmetricAlgorithm(org.w3c.dom.Element encryptedDataElement) Returns a URN representing the symmetric algorithm that encrypted a particular <EncryptedData> DOM element.
java.util.Vector	getUsers() Return the User instances that have been attached to the Decryptor instance.
org.w3c.dom.Document	toDocument() Returns the DOM tree of the document.
void	updateElement(org.w3c.dom.Element encryptedDataElement) Allows an application to replace a specific <EncryptedData> element with decrypted data.

Methods inherited from class com.entrust.toolkit.xencrypt.core.EncryptionHandler

getDocument, isValidated, toInputStream, toOutputStream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_decryptedBinary

protected java.util.Vector m_decryptedBinary

Holds the decrypted binary data

Constructor Detail

Decryptor

public Decryptor(XMLEInit initializer,
                 java.io.InputStream document)
          throws EncryptionHandlerException,
                 DecryptorException

Parses an encrypted XML document to a DOM tree and initializes the Toolkit to decrypt DOM elements within that document.

Parameters:

initializer - a reference to an XMLEInit object.

document - an InputStream instance that provides an XML document

Throws:

EncryptionHandlerException - if parsing the document without validation fails

DecryptorException - if initialization of the Decryptor fails

Decryptor

public Decryptor(XMLEInit initializer)
          throws EncryptionHandlerException,
                 DecryptorException

Initializes the Toolkit to decrypt external binary data.

Parameters:

initializer - a reference to an XMLEInit object.

Throws:

EncryptionHandlerException - if parsing the document without validation fails

DecryptorException - if initialization of the Decryptor fails

Method Detail

addUser

public void addUser(User user)
             throws DecryptorException

Enables a particular Decryptor instance to decrypt DOM elements that were encrypted for the specified User.

Internally, the User provides the Decryptor instance with access to a private decryption key. By invoking this method repeatedly, an application can add several User instances, enabling the Decryptor to decrypt DOM elements that were encrypted for any of them.

Parameters:

user - a logged in User

Throws:

DecryptorException - if the User is not logged in or the User's distinguished name cannot be determined. The Toolkit identifies the private key by the subject name specified in the <KeyInfo> child element of the <EncryptedKey> DOM element, which must match the User's distinguished name.

See Also:

getRecipients(), getRecipients(Element)

getUsers

public java.util.Vector getUsers()

Return the User instances that have been attached to the Decryptor instance.

Returns:

a Vector of references to the User objects

See Also:

addUser(User)

addKeyEncryptionkey

public void addKeyEncryptionkey(byte[] id,
                                javax.crypto.SecretKey kenEncryptionKey)
                         throws EncryptionHandlerException

Enables a particular Decryptor instance to decrypt DOM elements.

The DOM elements this method decrypts have been encrypted with a symmetric key that has in turn been encrypted by the specified SecretKey.

The SecretKey instance and its id are stored in the Decryptor. By invoking this method repeatedly, an application can add several SecretKey instances to the Decryptor, enabling the decryption of DOM elements that have been encrypted by symmetric keys generated by any of the SecretKey instances.

Parameters:

kenEncryptionKey - a SecretKey used by the key wrap algorithm

id - the SecretKey's id

Throws:

DecryptorException - if the User is not logged in or the User's distinguished name cannot be determined. The Toolkit identifies the private key by the subject name specified in the <KeyInfo> child element of the <EncryptedKey> DOM element, which must match the User's distinguished name.

EncryptionHandlerException

decrypt

public boolean decrypt()
                throws DecryptorException

Decrypts all <EncryptedData> DOM elements that are encrypted for any User in this Decryptor instance.

When the method returns, all the encrypted DOM elements have been replaced by decrypted elements.

Returns:

true if all decrypt operations succeeded

Throws:

DecryptorException - if the decryption of any element fails.

decrypt

public java.lang.String decrypt(org.w3c.dom.Element encryptedDataElement)
                         throws DecryptorException

Decrypts a specified DOM element.

When the method returns, the Toolkit has decrypted the <EncryptedData> element internally but has not modified the DOM document itself. An <EncryptedData> element might contain an <EncryptedKey> child that will be used again when the application decrypts another element. Another <EncryptedData> element might reference the same <EncryptedKey>, for example. After your application has decrypted all the elements it needs, it should call the decryptComplete method to signal that the Decryptor can replace all <EncryptedData> elements with the decrypted results.

Parameters:

encryptedDataElement - is the <EncryptedData> element to be decrypted

Returns:

a String that contains the decrypted UTF-8 encoded XML character data

Throws:

DecryptorException - if decryption fails for any reason

See Also:

decryptComplete()

decryptBinary

public byte[] decryptBinary(org.w3c.dom.Element encryptedDataElement)
                     throws DecryptorException

Decrypts a specified DOM element for encrypted external binary data.

When the method returns, the Toolkit has decrypted the <EncryptedData> element internally but has not modified the DOM document itself. An <EncryptedData> element might contain an <EncryptedKey> child that will be used again when the application decrypts another element. Another <EncryptedData> element might reference the same <EncryptedKey>, for example.

Parameters:

encryptedDataElement - is the <EncryptedData> element to be decrypted

Returns:

a byte array that contains the decrypted octet sequence

Throws:

DecryptorException - if decryption fails for any reason

See Also:

decryptComplete()

updateElement

public void updateElement(org.w3c.dom.Element encryptedDataElement)
                   throws DecryptorException

Allows an application to replace a specific <EncryptedData> element with decrypted data.

This method should work only with an <EncryptedData> element with a type attribute of 'element' or 'content'.

Parameters:

encryptedDataElement - the <EncryptedData> element to be replaced

Throws:

DecryptorException

getEncryptedDataType

public java.lang.String getEncryptedDataType(org.w3c.dom.Element encryptedDataElement)

Returns the the value of the 'Type' attribute in an <EncryptedData> element.

Parameters:

encryptedDataElement - the <EncryptedData> element

Returns:

a String that represents the value of Type.

getDecryptedBinary

public java.util.Vector getDecryptedBinary()

decryptComplete

public void decryptComplete()
                     throws DecryptorException

Called by an application to signal that it has finished decrypting elements in an XML document.

After one or more invocations of decrypt(Element encryptedDataElement), the application calls decryptComplete() to signal that it will not decrypt any more elements in the document. XMLE can then replace each <EncryptedData> element with the XML fragment that resulted from its decryption. An <EncryptedKey> element that is a child of the <EncryptedData> element is removed when the <EncryptedData> element (or its content) is replaced by a decrypted XML fragment, so the <EncryptedKey> is no longer available to decrypt other elements.

The decryptComplete method removes from the document any <EncryptedKey> element that is no longer needed. This is because all <EncryptedData> elements referenced by its DataReferences and all <EncryptedData> elements that referenced it in <EncryptedKeyReferences> elements have been decrypted.

It is not necessary to call the decryptComplete method after a call to decrypt(). Call the decryptComplete method only after calls to the decrypt(Element element) method.

Throws:

DecryptorException - if completion of the decryption operation fails for any reason

getSymmetricAlgorithm

public java.lang.String getSymmetricAlgorithm(org.w3c.dom.Element encryptedDataElement)
                                       throws DecryptorException

Returns a URN representing the symmetric algorithm that encrypted a particular <EncryptedData> DOM element.

Parameters:

encryptedDataElement - a <EncryptedData> DOM element

Returns:

a String that is the URN of the encryption algorithm

Throws:

DecryptorException - if encryptedDataElement is not an <EncryptedData> element

getRecipients

public java.util.Vector getRecipients(org.w3c.dom.Element encryptedDataElement)
                               throws DecryptorException

Retrieves a list of the recipients who can decrypt this particular <EncryptedData> DOM element.

The getRecipients method attempts to resolve all EncryptedKeys that can decrypt this element and returns the subject information (Distinguished Name) that identifies each <EncryptedKey>. An application might call getRecipients to determine which Users have a private decryption key that can decrypt this <EncryptedData> element; the application might add one of those Users to the Decryptor instance.

Parameters:

encryptedDataElement - is an <EncryptedData> element

Returns:

Vector contains a list of Strings which are the distinguished names of the recipients

Throws:

DecryptorException - if the Toolkit fails to parse the <EncryptedData> element

See Also:

addUser(User)

getRecipients

public java.util.Vector getRecipients()
                               throws DecryptorException

Retrieves a list of the recipients who can decrypt at least one <EncryptedData> DOM element in this document.

Attempts to resolve all EncryptedKeys that can decrypt any <EncryptedData> element in the document and returns the subject information (Distinguished Name) that identifies each <EncryptedKey>. An application might call getRecipients to determine which Users have a private decryption key that can decrypt elements in this document. The application might add one or more of these Users to the Decryptor instance.

Returns:

A Vector that contains a list of Strings that are the distinguished names of the recipients.

Throws:

DecryptorException - if the Toolkit fails to parse one of the the <EncryptedData> elements in the document

See Also:

addUser(User)

toDocument

public org.w3c.dom.Document toDocument()

Returns the DOM tree of the document.

This method is usually called after one or more decryption operations to return the decrypted document.

Returns:

the Document tree for the document

See Also:

EncryptionHandler.toOutputStream(java.io.OutputStream), EncryptionHandler.toInputStream()