com.entrust.toolkit.xencrypt.core

Class EncryptedElementSet

java.lang.Object

com.entrust.toolkit.xencrypt.core.EncryptedElementSet

public class EncryptedElementSet
extends java.lang.Object

The EncryptedElementSet class allows an application to define a set of DOM elements to be encrypted for a group of recipients.

An application specifies the DOM elements to be encrypted for a set of recipients by performing the following steps:

• Create an EncryptedElementSet
• Attach recipients to the EncryptedElementSet instance
• Add DOM elements into the EncryptedElementSet instance
• Encrypt the set

All DOM elements in a particular EncryptedElementSet are encrypted by the same symmetric key. This means that relatively few private key operations are required when decrypting (fewer <EncryptedKey> elements are needed), and the encrypted document is smaller in size. For these reasons, an application might use an EncryptedElementSet even when it encrypts a document for just one recipient.

Internally, the Toolkit manages details that arise when encrypting several DOM elements with the same symmetric key and encrypting that key material for multiple recipients. For example, the Toolkit does not permit the application to add a DOM element into more than one EncryptedElementSet instance — each set receives its own unique symmetric key and the recipients who can decrypt a particular DOM element are defined explicitly (by the application, when it attaches recipients to a set). In addition, the Toolkit generates a fresh initialization vector (IV) as it encrypts each element in a set, even though the elements share symmetric key material.

Note

The EncryptedElementSet class assists the application in managing the encrypt use case and is not needed when decrypting.

Constructor Summary

Constructors

Constructor and Description
EncryptedElementSet(Encryptor encryptor) Creates an empty EncryptedElementSet that has no recipients.

Method Summary

Modifier and Type	Method and Description
void	addElement(org.w3c.dom.Element element) Adds a DOM element to the set of DOM elements to be encrypted (or whose content is to be encrypted) for the recipients of this EncryptedElementSet.
void	addElement(java.io.InputStream input) Adds an InputStream to the data set to be encrypted for the recipients of this EncryptedElementSet.
void	addElement(java.lang.String plaintextURI) Adds a plaintext URI to the data set to be encrypted for the recipients of this EncryptedElementSet.
void	addKeyEncryptionKey(javax.crypto.SecretKey keyEncryptionKey, byte[] id) Adds a key encryption key (KEK) to a set of elements.
void	addRecipient(X509Certificate certificate) Adds a recipient to a set of elements.
void	encrypt() Encrypts the DOM elements in this EncryptedElementSet, creating <EncryptedKey> and <EncryptedData> DOM elements as required.
org.w3c.dom.Element[]	getEncryptedDatas() Retrieves the <EncryptedData> DOM elements that were created by the Toolkit when the DOM elements in this EncryptedElementSet were encrypted.
org.w3c.dom.Element[]	getEncryptedKeys() Retrieves the <EncryptedKey> DOM elements that were created by the Toolkit when the DOM elements in this EncryptedElementSet were encrypted.
X509Certificate[]	getRecipients() Identifies the recipients attached to this set.
boolean	isEncrypted() Indicates whether or not the set of elements has been encrypted.

Methods inherited from class java.lang.Object

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

Constructor Detail

EncryptedElementSet

public EncryptedElementSet(Encryptor encryptor)
                    throws EncryptedElementSetException

Creates an empty EncryptedElementSet that has no recipients.

The symmetric algorithm for an EncryptedElementSet instance is the algorithm in effect when the set is instantiated.

Parameters:

encryptor - the Encryptor that encrypts the set

Throws:

EncryptedElementSetException - if the set cannot be instantiated

See Also:

Encryptor.setSymmetricAlgorithm(java.lang.String)

Method Detail

isEncrypted

public boolean isEncrypted()

Indicates whether or not the set of elements has been encrypted.

Returns:

true If the set of elements has been encrypted for at least one recipient

getEncryptedKeys

public org.w3c.dom.Element[] getEncryptedKeys()
                                       throws EncryptedElementSetException

Retrieves the <EncryptedKey> DOM elements that were created by the Toolkit when the DOM elements in this EncryptedElementSet were encrypted.

Returns:

Element[] is an array of <EncryptedKey> elements

Throws:

EncryptedElementSetException - if the EncryptedElementSet has not yet been encrypted

getEncryptedDatas

public org.w3c.dom.Element[] getEncryptedDatas()
                                        throws EncryptedElementSetException

Retrieves the <EncryptedData> DOM elements that were created by the Toolkit when the DOM elements in this EncryptedElementSet were encrypted.

Returns:

Element[] is an array of <EncryptedData> elements

Throws:

EncryptedElementSetException - if the EncryptedElementSet has not yet been encrypted yet

getRecipients

public X509Certificate[] getRecipients()

Identifies the recipients attached to this set.

Note

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

Returns:

the X509Certificate of each recipient, or null if there are no recipients

addElement

public void addElement(org.w3c.dom.Element element)
                throws EncryptedElementSetException

Adds a DOM element to the set of DOM elements to be encrypted (or whose content is to be encrypted) for the recipients of this EncryptedElementSet.

Parameters:

element - is the DOM Element to be added

Throws:

EncryptedElementSetException - if adding the element fails for any reason

See Also:

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

addElement

public void addElement(java.lang.String plaintextURI)
                throws EncryptedElementSetException

Adds a plaintext URI to the data set to be encrypted for the recipients of this EncryptedElementSet.

Parameters:

plaintextURI - the plaintext URI to be added

Throws:

EncryptedElementSetException - if adding the URI fails for any reason

addElement

public void addElement(java.io.InputStream input)
                throws EncryptedElementSetException

Adds an InputStream to the data set to be encrypted for the recipients of this EncryptedElementSet.

Parameters:

input - the InputStream to be added

Throws:

EncryptedElementSetException - if adding the URI fails for any reason

addRecipient

public void addRecipient(X509Certificate certificate)
                  throws EncryptedElementSetException

Adds a recipient to a set of elements.

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

An <EncryptedKey> DOM element encrypts the set for a particular recipient. The public key comes from the certificate provided as an argument of the method (validated internally before being used), and the encryption method is the <EncryptedKey> algorithm in effect when this method is invoked. The algorithm is determined by setEncryptedKeyAlgorithm(String algorithm) and is RSA encryption with either PKCS#1 v1.5 or PKCS#1 v2.0 (OAEP).

Parameters:

certificate - an encryption certificate

Throws:

EncryptedElementSetException - is the certificate is not valid

See Also:

Encryptor.setEncryptedKeyAlgorithm(java.lang.String)

addKeyEncryptionKey

public void addKeyEncryptionKey(javax.crypto.SecretKey keyEncryptionKey,
                                byte[] id)
                         throws EncryptedElementSetException

Adds a key encryption key (KEK) to a set of elements.

If the element set has other KEKs,the addKeyEncryptionKey method adds this one. If the element set already had this KEK, the method does nothing.

An <EncryptedKey> DOM element encrypts the set with a particular key encryption key. The key encryption key and its id are provided as arguments, and the encryption method is the <EncryptedKey> algorithm in effect when this method is invoked. The algorithm is determined by setEncryptedKeyAlgorithm(String algorithm) and is one of the key wrap algorithms.

Parameters:

keyEncryptionKey - n key encryption key

id - the id of key encryption key

Throws:

EncryptedElementSetException - error when adding the key encryption key

See Also:

Encryptor.setEncryptedKeyAlgorithm(java.lang.String)

encrypt

public void encrypt()
             throws EncryptedElementSetException

Encrypts the DOM elements in this EncryptedElementSet, creating <EncryptedKey> and <EncryptedData> DOM elements as required.

After this method has been called, the application can retrieve the <EncryptedData> and <EncryptedKey> DOM elements by invoking getEncryptedDatas or getEncryptedKeys.

Throws:

EncryptedElementSetException

See Also:

getEncryptedDatas(), getEncryptedKeys()