com.entrust.toolkit.xencrypt.core

Class Encryptor

java.lang.Object

com.entrust.toolkit.xencrypt.core.EncryptionHandler

com.entrust.toolkit.xencrypt.core.Encryptor

public final class Encryptor
extends EncryptionHandler

The Encryptor class encrypts Document Object Model (DOM) elements in an XML document.

See Also:

Decryptor

Field Summary

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

m_DOMdocument, m_XMLEInit

Constructor Summary

Constructors

Constructor and Description
Encryptor(XMLEInit initializer) Creates a new XML DOM Document.
Encryptor(XMLEInit initializer, java.io.InputStream document) Parses an XML document to a DOM tree and initializes the Toolkit to encrypt DOM elements within the document.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	encrypt() Encrypts all DOM elements for which at least one recipient has been set.
org.w3c.dom.Element	encryptBinary(java.io.InputStream input) Encrypts an external binary file referenced by an Inputstream.
org.w3c.dom.Element	encryptBinary(java.lang.String plaintextURI) Encrypts an external binary file referenced by plaintextURI.
org.w3c.dom.Element	encryptContent(org.w3c.dom.Element element) Encrypts only the content of a DOM element, not the element's tag and attributes.
org.w3c.dom.Element	encryptElement(org.w3c.dom.Element element) Encrypts a DOM element.
byte[]	getCipherText(java.lang.String ciphertextURI) Returns the cipher text corresponding to the given ciphertext URI after encryption.
java.lang.String	getEncryptedDataBaseID() Accessor method to rerieve base ID of the <EncryptedData> element.
org.w3c.dom.Element	getEncryptedDataElement(java.io.InputStream binaryInputStream) Returns the lt;EncryptedData> element referred to by the Inputstream.
org.w3c.dom.Element	getEncryptedDataElement(java.lang.String externalBinaryURI) Returns the <EncryptedData> element referred to by the URI references to binary data.
EncryptedElementSet[]	getEncryptedElementSets() Returns EncryptedElementSets that contain all the <EncryptedData> and <EncryptedKey> DOM elements the Toolkit created when it encrypted the document.
java.lang.String	getEncryptedKeyAlgorithm() Retrieves the algorithm that encrypts <EncryptedKey> elements.
java.lang.String	getEncryptedKeyBaseID() Accessor method to retrieve the <EncryptedKey> element's base ID.
X509Certificate[]	getRecipients(java.lang.Object element) Identifies the recipients for whom a particular DOM element has been encrypted — all the users who will be able to decrypt the element.
java.lang.String	getSymmetricAlgorithm() Identifies the symmetric algorithm currently in effect.
java.lang.String	getSymmetricAlgorithm(org.w3c.dom.Element element) Identifies the symmetric algorithm that encrypted a particular <EncryptedData> DOM element.
Trustmanager	getTrustmanager() Returns the Trustmanager that was set in a particular Encryptor instance.
protected void	setCipherText(java.lang.String ciphertextURI, byte[] ciphertext) Stores the cipher text corresponding to the given ciphertext URI.
void	setCipherURI(java.lang.Object element, java.lang.String ciphertextURI) Specifies the cipher text URI for this element.
void	setContentOnly(org.w3c.dom.Element element, boolean contentOnly) Determines whether an entire DOM element (including opening and closing tags) or just the content of a DOM element is to be encrypted.
void	setEncryptedDataBaseID(java.lang.String baseID) Sets the <EncryptedData> base ID.
void	setEncryptedDataId(java.lang.Object element, java.lang.String id) Lets the application specify a particular value for the Id attribute of an <EncryptedData> DOM element.
void	setEncryptedKeyAlgorithm(java.lang.String algorithm) Sets the algorithm that encrypts <EncryptedKey> DOM elements.
void	setEncryptedKeyBaseID(java.lang.String baseID) Sets the <EncryptedKey> base ID.
void	setKeyEncryptionKey(java.lang.Object element, javax.crypto.SecretKey keyEncryptionKey, byte[] id) Sets a key encryption key that will be used to encrypt this particular DOM element.
void	setRecipient(java.lang.Object element, X509Certificate certificate) Sets a certificate whose public key will be used to encrypt this particular DOM element or its content.
void	setSymmetricAlgorithm(java.lang.String algorithm) Sets the symmetric algorithm.
void	setTrustmanager(Trustmanager trustmanager) Initializes this instance with a Trustmanager, which can validate encryption certificates.
void	setTrustmanager(User validator) Deprecated. use setTrustmanager(Trustmanager trustmanager) instead.
org.w3c.dom.Document	toDocument() Returns the DOM tree of the document.
void	updateContent(org.w3c.dom.Element element) Replaces the unencrypted element content with an <EncryptedData> element — called after the encryptContent method.
void	updateElement(org.w3c.dom.Element element) Replaces the unencrypted element or content with an <EncryptedData> element — called after encryption.

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

Constructor Detail

Encryptor

public Encryptor(XMLEInit initializer)
          throws EncryptionHandlerException,
                 EncryptorException

Creates a new XML DOM Document.

Parameters:

initializer - a reference to an XMLEInit object.

Throws:

EncryptionHandlerException - if creating the DOM Document fails.

EncryptorException

Encryptor

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

Parses an XML document to a DOM tree and initializes the Toolkit to encrypt DOM elements within the document.

Parameters:

initializer - a reference to an XMLEInit object.

document - an InputStream that provides the XML document to be encrypted.

Throws:

EncryptionHandlerException - if parsing the document without validation fails

Method Detail

setTrustmanager

public void setTrustmanager(User validator)
                     throws UserNotLoggedInException

Deprecated. use setTrustmanager(Trustmanager trustmanager) instead.

Initializes the Encryptor with a trust manager.

This method provides a means of validating encryption certificates, by providing capabilities such as secure access to a root of trust and certificate revocation checking.

Parameters:

validator - a logged in User

Throws:

UserNotLoggedInException - if the User is not already logged in

setTrustmanager

public void setTrustmanager(Trustmanager trustmanager)

Initializes this instance with a Trustmanager, which can validate encryption certificates.

Parameters:

trustmanager - a Trustmanager

Throws:

UserNotLoggedInException - if the User is not already logged in

getTrustmanager

public Trustmanager getTrustmanager()

Returns the Trustmanager that was set in a particular Encryptor instance.

Returns:

a Trustmanager

getEncryptedKeyAlgorithm

public java.lang.String getEncryptedKeyAlgorithm()

Retrieves the algorithm that encrypts <EncryptedKey> elements.

The algorithm can be set using the setEncryptedKeyAlgorithm method.

Returns:

a URN that identifies the algorithm

See Also:

setEncryptedKeyAlgorithm(java.lang.String)

setEncryptedKeyAlgorithm

public void setEncryptedKeyAlgorithm(java.lang.String algorithm)
                              throws EncryptorException

Sets the algorithm that encrypts <EncryptedKey> DOM elements.

Parameters:

algorithm - a URN that identifies the algorithm. Allowed values are found in the com.entrust.toolkit.xencrypt.init.XMLEConstants class.

Throws:

EncryptorException

See Also:

XMLEConstants.ALGORITHM_RSA, XMLEConstants.ALGORITHM_RSA_OAEP, XMLEConstants.ALGORITHM_AES_256_KEY_WRAP, XMLEConstants.ALGORITHM_AES_128_KEY_WRAP, XMLEConstants.ALGORITHM_AES_192_KEY_WRAP, XMLEConstants.ALGORITHM_3DES_KEY_WRAP

setKeyEncryptionKey

public void setKeyEncryptionKey(java.lang.Object element,
                       javax.crypto.SecretKey keyEncryptionKey,
                       byte[] id)
                         throws EncryptionHandlerException

Sets a key encryption key that will be used to encrypt this particular DOM element.

The method encrypts the DOM element, its content, or an inputstream or URI referring to the external binary data. If the element already has other key encryption keys, the method adds this one. If the element already has this key, the method does nothing.

Parameters:

element - an Element to be encrypted for the recipient, or an Inputstream or a URI string reference to the external binary data

keyEncryptionKey - the key encryption key

id - the id of the key encryption key

Throws:

EncryptorException - if the certificate cannot be validated.

EncryptionHandlerException

See Also:

EncryptedElementSet.addRecipient(iaik.x509.X509Certificate)

getSymmetricAlgorithm

public java.lang.String getSymmetricAlgorithm()

Identifies the symmetric algorithm currently in effect.

The algorithm can be set using the setSymmetricAlgorithm method.

Returns:

a URN that identifies the algorithm

See Also:

setSymmetricAlgorithm(java.lang.String)

getSymmetricAlgorithm

public java.lang.String getSymmetricAlgorithm(org.w3c.dom.Element element)
                                       throws EncryptorException

Identifies the symmetric algorithm that encrypted a particular <EncryptedData> DOM element.

Note

The DOM element must have been encrypted before this method is invoked.

This method is provided for convenience, since the application can specify the encryption algorithm itself.

Parameters:

element - an <EncryptedData> DOM element

Returns:

a URN that identifies the algorithm

Throws:

EncryptorException - if element parameter is not an <EncryptedData> DOM element.

See Also:

setSymmetricAlgorithm(java.lang.String)

setSymmetricAlgorithm

public void setSymmetricAlgorithm(java.lang.String algorithm)

Sets the symmetric algorithm.

This method does the following:

• Determines the algorithm used to encrypt individual <EncryptedData> DOM elements.
• Determines the algorithm used to encrypt <EncryptedElementSets> that are created after this method has been invoked.

The setSymmetricAlgorithm method has no effect on the following:

• DOM elements that already have a recipient assigned to them.
• EncryptedElementSets that were created before invoking this method.

Parameters:

algorithm - a String that specifies the symmetric algorithm. Allowed values are found in the com.entrust.toolkit.xencrypt.init.XMLEConstants class

See Also:

XMLEConstants.ALGORITHM_3DES, XMLEConstants.ALGORITHM_AES_256, XMLEConstants.ALGORITHM_AES_192, XMLEConstants.ALGORITHM_AES_128

getEncryptedKeyBaseID

public java.lang.String getEncryptedKeyBaseID()

Accessor method to retrieve the <EncryptedKey> element's base ID.

The base ID is used by an application to specify a value for the Id attribute of <EncryptedKey> DOM elements created by the Encryptor instance that calls this method.

Returns:

a String that contains the base ID value

See Also:

setEncryptedKeyBaseID(java.lang.String)

setEncryptedKeyBaseID

public void setEncryptedKeyBaseID(java.lang.String baseID)
                           throws EncryptorException

Sets the <EncryptedKey> base ID.

The base ID determines the value of the Id attribute assigned to <EncryptedKey> DOM elements created by the Encryptor instance that calls this method.

As new <EncryptedKey> DOM elements are created, the Encryptor assigns them Ids numbered sequentially from zero, using the base ID as a common String. For example, if the base ID is set to "EK", then <EncryptedKey> elements will have Id values as follows: Id="EK0", Id="EK1", and so on.

Note

An application does not necessarily need to invoke this method. The Toolkit specifies a default value for the base ID — the value of the variable XMLEConstants.ENCRYPTEDKEY_BASE_ID.

An application is responsible for selecting a baseId that makes all the Ids within a particular document unique.

Parameters:

baseID - a String common to all Ids as described above

Throws:

EncryptorException - if the 'id' argument is not a unique ID value within this DOM document

See Also:

XMLEConstants.ENCRYPTEDKEY_BASE_ID, getEncryptedKeyBaseID()

getEncryptedDataBaseID

public java.lang.String getEncryptedDataBaseID()

Accessor method to rerieve base ID of the <EncryptedData> element.

The base ID is used by an application to specify a value for the Id attribute of <EncryptedData> DOM elements created by the Encryptor instance that calls this method.

Returns:

a String that contains the base ID value

See Also:

setEncryptedDataBaseID(java.lang.String)

setEncryptedDataBaseID

public void setEncryptedDataBaseID(java.lang.String baseID)
                            throws EncryptorException

Sets the <EncryptedData> base ID.

The base ID determines the value of the Id attribute assigned to the <EncryptedData> DOM elements created by the Encryptor instance that calls this method.

As new <EncryptedData> DOM elements are created, the Encryptor assigns them Id values numbered sequentially starting from zero. The Encryptor uses this base ID as a prefix. For example, if the base ID is set to "ED", then <EncryptedData> DOM elements will receive Id values: Id="ED0", Id="ED1", and so on.

Parameters:

baseID - a String common to all Ids as described above

Throws:

EncryptorException - if 'id' is not a unique attribute value within this document

See Also:

setEncryptedDataId(java.lang.Object, java.lang.String), setEncryptedKeyBaseID(java.lang.String)

encryptElement

public org.w3c.dom.Element encryptElement(org.w3c.dom.Element element)
                                   throws EncryptorException

Encrypts a DOM element.

When this method returns, the DOM element has been replaced by an <EncryptedData> DOM element whose Type attribute has the value "Element". Its Id attribute has a value that is generated internally by the Toolkit, unless the application has specified a particular value for the Id by invoking the methods setEncryptedDataBaseID or setEncryptedDataId.

Parameters:

element - is the DOM Element to be encrypted

Throws:

EncryptorException

See Also:

setEncryptedDataBaseID(java.lang.String)

updateElement

public void updateElement(org.w3c.dom.Element element)
                   throws EncryptionHandlerException

Replaces the unencrypted element or content with an <EncryptedData> element — called after encryption.

Parameters:

element - the DOM Element to be encrypted

Throws:

EncryptionHandlerException

encryptContent

public org.w3c.dom.Element encryptContent(org.w3c.dom.Element element)
                                   throws EncryptorException

Encrypts only the content of a DOM element, not the element's tag and attributes.

When this method returns, the content has been replaced by an <EncryptedData> DOM element whose Type attribute has the value "CONTENT".

The Id attribute of the <EncryptedData> DOM element is created internally by the Toolkit, unless the application has specified a particular value by calling setEncryptedDataBaseID or setEncryptedDataId.

Parameters:

element - is the DOM Element to be encrypted

Throws:

EncryptorException

See Also:

setContentOnly(org.w3c.dom.Element, boolean)

updateContent

public void updateContent(org.w3c.dom.Element element)
                   throws EncryptionHandlerException

Replaces the unencrypted element content with an <EncryptedData> element — called after the encryptContent method.

Parameters:

element - the DOM element to be encrypted

Throws:

EncryptionHandlerException

encryptBinary

public org.w3c.dom.Element encryptBinary(java.lang.String plaintextURI)
                                  throws EncryptorException

Encrypts an external binary file referenced by plaintextURI.

Parameters:

plaintextURI - a URI reference to binary data

Throws:

EncryptorException

encryptBinary

public org.w3c.dom.Element encryptBinary(java.io.InputStream input)
                                  throws EncryptorException

Encrypts an external binary file referenced by an Inputstream.

Parameters:

input - an Inputstream reference to binary data

Throws:

EncryptorException

encrypt

public boolean encrypt()
                throws EncryptorException

Encrypts all DOM elements for which at least one recipient has been set.

The recipient may have been set directly on the DOM element or attached to an EncryptedElementSet instance to which the DOM element belongs. When this method returns, all of the DOM elements have been replaced by <EncryptedData> DOM elements.

For each element, this method encrypts either the element and its content or just the content, depending on what the application specified in a prior call to the setContentOnly(Element, boolean) method. If setContentOnly(Element, boolean) has not been called, this method throws an exception.

Returns:

false if no DOM elements were encrypted by this invocation (if no recipients have been set, for example)

Throws:

EncryptorException - if the encryption of an element fails for some reason

See Also:

setContentOnly(org.w3c.dom.Element, boolean), setRecipient(java.lang.Object, iaik.x509.X509Certificate), EncryptedElementSet.addRecipient(X509Certificate)

setRecipient

public void setRecipient(java.lang.Object element,
                X509Certificate certificate)
                  throws EncryptorException

Sets a certificate whose public key will be used to encrypt this particular DOM element or its content.

If the element already has other recipients, the method adds this one. If the element already has this recipient, the method does nothing.

Parameters:

element - is an Element to be encrypted for the recipient

certificate - is the recipient's encryption certificate

Throws:

EncryptorException - if the certificate cannot be validated.

See Also:

EncryptedElementSet.addRecipient(iaik.x509.X509Certificate)

setEncryptedDataId

public void setEncryptedDataId(java.lang.Object element,
                      java.lang.String id)
                        throws EncryptorException

Lets the application specify a particular value for the Id attribute of an <EncryptedData> DOM element.

This method is called before the element is encrypted. The <EncryptedData> DOM element is created later, when the element is encrypted.

Parameters:

element - is the DOM element to be encrypted

id - the value to be set for the Id attribute of the <EncryptedData> DOM element

Throws:

EncryptorException - if 'id' is not a unique attribute value within the document or if the element has not been specified as one to be encrypted, i.e. if setRecipient() has not yet been called on this element.

See Also:

setRecipient(java.lang.Object, iaik.x509.X509Certificate), setEncryptedKeyBaseID(java.lang.String)

setCipherURI

public void setCipherURI(java.lang.Object element,
                java.lang.String ciphertextURI)
                  throws EncryptorException

Specifies the cipher text URI for this element.

Parameters:

element - the XML document element or external binary data to be encrypted

ciphertextURI - the URI at which the application will write the ciphertext externally to the <EncryptedData> element. This URI is pointed to in the <CipherReference> element.

Throws:

EncryptorException

getCipherText

public byte[] getCipherText(java.lang.String ciphertextURI)

Returns the cipher text corresponding to the given ciphertext URI after encryption.

Parameters:

ciphertextURI - the uri at which the application will write the ciphertext externally to the <EncryptedData> element. This URI is pointed to in the <CipherReference> element.

Returns:

byte[] The cipher text corresponding to the given ciphertext URI.

setCipherText

protected void setCipherText(java.lang.String ciphertextURI,
                 byte[] ciphertext)

Stores the cipher text corresponding to the given ciphertext URI. Used internally in the Toolkit.

Parameters:

ciphertextURI - the URI at which the application will write the ciphertext externally to the EncryptedData element. This URI is pointed to in the <CipherReference> element.

ciphertext - The result ciphertext after encryption.

setContentOnly

public void setContentOnly(org.w3c.dom.Element element,
                  boolean contentOnly)
                    throws EncryptorException

Determines whether an entire DOM element (including opening and closing tags) or just the content of a DOM element is to be encrypted.

Two kinds of element encryption are defined by the XENC proposal: the encryption of the entire element, and the encryption of the contents of the element.

Calling setContentOnly(element, true) encrypts the child elements of the element argument. Calling setContentOnly(element, false), encrypts the opening and closing tags of the element argument, its attributes, and all of its children.

For example, given the following XML element, parent:

    <parent name=Mary>
       <childElementA />
       <childElementB>cat</childElementB>
       <childElementC>dog</childElementC>
    </parent>
 

setContentOnly(element, true) (element argument references the parent element in the XML fragment) encrypts the childElementA, childElementB, and childElementC elements, their opening and closing tags and their contents.

setContentOnly(element, false) (element argument references the parent element in the XML fragment) encrypts the parent element's opening and closing tags, its name attribute and the childElementA, childElementB, and childElementC elements, their opening and closing tags and their contents.

Throws:

EncryptorException - if this setting has already been specified or if the DOM element has not been initialized as an element to be encrypted, either by adding a recipient to the element or adding the DOM element into an EncryptedElementSet.

See Also:

encryptContent(org.w3c.dom.Element)

toDocument

public org.w3c.dom.Document toDocument()

Returns the DOM tree of the document.

This method is usually called after one or more encryption operations to return the encrypted document.

Returns:

the Document tree for the document.

See Also:

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

getRecipients

public X509Certificate[] getRecipients(java.lang.Object element)
                                throws EncryptorException

Identifies the recipients for whom a particular DOM element has been encrypted — all the users who will be able to decrypt the element.

The method returns all the recipients of the EncryptedElementSet of which this <EncryptedData> DOM element is a member.

Note

This method is provided for convenience, because the application itself specifies the recipients.

Returns:

the X509Certificate of each recipient

Throws:

EncryptorException - if element is not an <EncryptedData> DOM element

getEncryptedElementSets

public EncryptedElementSet[] getEncryptedElementSets()

Returns EncryptedElementSets that contain all the <EncryptedData> and <EncryptedKey> DOM elements the Toolkit created when it encrypted the document. The document should be encrypted before this method is invoked.

The application might use this method when it must access the <EncryptedData> and <EncryptedKey> elements using methods of the standard DOM API. For example, the application might move an <EncryptedKey> element to a different position in the encrypted document, in order to conform to a particular DTD or XML schema.

Note

This method is provided for convenience. An application could use methods of the standard DOM API to find <EncryptedData> and <EncryptedKey> DOM elements in the encrypted XML document.

Returns:

an array of EncryptedElementSets, or null if no elements have been encrypted

See Also:

EncryptedElementSet.getEncryptedDatas(), EncryptedElementSet.getEncryptedKeys()

getEncryptedDataElement

public org.w3c.dom.Element getEncryptedDataElement(java.lang.String externalBinaryURI)
                                            throws EncryptionHandlerException

Returns the <EncryptedData> element referred to by the URI references to binary data.

Used for external binary data encryption.

Returns:

An Element that corresponds to the externalBinaryURI.

Throws:

EncryptionHandlerException

getEncryptedDataElement

public org.w3c.dom.Element getEncryptedDataElement(java.io.InputStream binaryInputStream)
                                            throws EncryptionHandlerException

Returns the lt;EncryptedData> element referred to by the Inputstream.

Used for external binary data encryption.

Returns:

An Element that corresponds to the Inputstream.

Throws:

EncryptionHandlerException