com.entrust.toolkit.xencrypt.core

Class TransformImplDecryption

java.lang.Object

iaik.ixsil.algorithms.Algorithm

iaik.ixsil.algorithms.Transform

com.entrust.toolkit.xencrypt.core.TransformImplDecryption

public class TransformImplDecryption
extends Transform

Provides an implementation of the Decryption Transform for XML Signature.

When it signs XML content, your application should insert a Decryption Transform into the XML signature if portions of the XML content are to be encrypted after being signed. A Decryption Transform enables the Verifier to determine which parts of the signed content must be decrypted before the signature can be verified. The Verifier must not decrypt content that had already been encrypted at the time it was signed.

To make the Decryption Transform available to your application, ensure that IXSIL's algorithms.properties file contains the following line:

  Transform.http\://www.w3.org/2001/04/decrypt\# = com.entrust.toolkit.xencrypt.core.TransformImplDecryption
 

Whenever your application signs XML content that might be encrypted later, your application should insert a Decryption Transform:

      SignerSignedInfo signedInfo;
   // <...Instantiate and configure the signedInfo in the usual way...>
      SignerReference reference = signedInfo.createReference();
   // <...Insert any other required transforms, e.g. XPath or enveloped-signature transforms...>
   // Insert a Decryption Transform in the Reference
      TransformImplDecryption decTransform = new TransformImplDecryption();
      reference.insertTransformAt(decTransform, reference.getTransformsNumber());
 

When your application verifies an XML signature that might contain encrypted content, the following procedure enables the Toolkit to decrypt that content:

  // One time only, initialize the Toolkit's XML Encryption capabilities.
     XMLEInit initializer = new XMLEInit(new FileInputStream( "init\\properties\\init.properties"));
  // ...
  // One time only, instantiate a User that can decrypt the XML content.
  // Note: This is not necessarily the User that is set in the TrustManager
     User user = new User();
  // <... log in that User...>
  // For each signature to be verified, create a Verifier, as usual.
     Verifier verifier = new Verifier(istream, baseURI, signatureSelector, null);
  // Give the Verifier an XMLE initializer.
     verifier.setXMLEinitializer(initializer);
  // Attach the User who will decrypt.  You may attach several Users, as required.
     verifier.setUser(user);
  // Set a TrustManager and verify the signature, in the usual way.
     boolean verifiedByCertificate = setTrustmanager(verifier) ;
     verifier.getSignature().verify();
 

As it verifies the signature, the Toolkit identifies and decrypts encrypted portions of the signed content.

Some restrictions apply to the use of a Decryption Transform. These restrictions are noted in the W3C document entitled Decryption Transform for XML Signature:

• "This transform does not deal with any detached <enc:EncryptedKey > elements... it is not recommended in this document to detach <enc:EncryptedKey> elements from an <enc:EncryptedData> element or to include detached <enc:EncryptedKey> elements in the scope of a signature."

  Note

  By default, the Toolkit does not detach the <EncryptedKey> elements it creates when it encrypts XML. However, when your application uses the class com.entrust.toolkit.xencrypt.EncryptedDataSet to encrypt several DOM elements under the same key or to encrypt several elements for multiple recipients, the Toolkit does generate detached <EncryptedKey> elements. (When fewer encrypted keys are needed, the decryption process is more efficient.) If you use a Decryption Transform while signing a document, do not use the <EncryptedDataSet> for subsequent encryptions. Instead, attach multiple recipients directly to each element, by invoking com.entrust.toolkit.xencrypt.core.Encryptor.setRecipient(Element, X509Certificate).

• "Note: Condition places certain restrictions on the use of this transform. First, the input to the transform MUST be single-rooted. Second, if the first node of the input is an element node with the type enc:EncryptedData, the decrypted octet stream MUST be of type http://www.w3.org/2001/04/xmlenc#Element. These restrictions are necessary to ensure that the decrypted octet stream is parsed correctly in a given parsing context."

  Note

  The requirement that the node set be single rooted may affect the kinds of XPath Transforms you employ ahead of the Decryption Transform, as you sign a document.

Since:

Version 6.1

See Also:

Encryptor.setRecipient(java.lang.Object element, X509Certificate cert)

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	DEFAULT_ALGORITHM_URI The default algorithm URI for this algorithm implementation.

Fields inherited from class iaik.ixsil.algorithms.Transform

inputNodeSet_, inputOctetStream_, inputURI_

Fields inherited from class iaik.ixsil.algorithms.Algorithm

uri_

Constructor Summary

Constructors

Constructor and Description
TransformImplDecryption() Constructor

Method Summary

Methods

Modifier and Type	Method and Description
java.util.Vector	getRecipients() Returns the distinguished names of recipients of the encrypted content.
java.util.Vector	getUsers() Returns the User instances that were attached to this transform.
void	setInitializer(XMLEInit initializer) Allows the Toolkit to initialize the transform for decrypting XML content.
void	setParameters(org.w3c.dom.Element transformElement) Parses the <Transform> element in the signature and initializes the transform for decrypting XML content.
void	setUser(User user) Allows the Toolkit to provide User instances to the transform.
org.w3c.dom.Element	toElement(org.w3c.dom.Document document) Returns the DOM element representation of the transform.
java.lang.Object	transform() Executes the transform.

Methods inherited from class iaik.ixsil.algorithms.Transform

distributeNSDeclarations, setInput, setInput, skipStylesheetElem, withdrawDistributedNSDeclarations

Methods inherited from class iaik.ixsil.algorithms.Algorithm

getURI, setURI

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ALGORITHM_URI

protected static final java.lang.String DEFAULT_ALGORITHM_URI

The default algorithm URI for this algorithm implementation.

See Also:

Constant Field Values

Constructor Detail

TransformImplDecryption

public TransformImplDecryption()

Constructor

Method Detail

setInitializer

public void setInitializer(XMLEInit initializer)

Allows the Toolkit to initialize the transform for decrypting XML content.

Before it verifies each signature, your application must invoke iaik.ixsil.core.Verifier.setXMLEinitializer(XMLEInit)>, to initialize the Decryption Transform.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Parameters:

initializer - an XMLE initialization instance

See Also:

Verifier.setXMLEinitializer(XMLEInit)

setUser

public void setUser(User user)

Allows the Toolkit to provide User instances to the transform.

When the Toolkit needs to decrypt XML content, it searches for a recipient among the User objects set by this method. Before it verifies a signature, your application should invoke iaik.ixsil.core.Verifier.setUser(User), providing a User object that can decrypt the XML content.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Parameters:

user - a User that that must already be logged in

See Also:

Verifier.setUser(User)

getUsers

public java.util.Vector getUsers()

Returns the User instances that were attached to this transform.

Applies only to the VERIFY use case.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Returns:

A Vector of Strings that are the distinguished names of the recipients. Returns null if invoked in the SIGN use case.

See Also:

Verifier.setUser(User)

getRecipients

public java.util.Vector getRecipients()

Returns the distinguished names of recipients of the encrypted content.

Applies only to the VERIFY use case.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Returns:

A Vector of Strings that are the distinguished names of the recipients. Returns null if invoked in the SIGN use case.

See Also:

Verifier.setUser(User)

setParameters

public void setParameters(org.w3c.dom.Element transformElement)
                   throws AlgorithmException

Parses the <Transform> element in the signature and initializes the transform for decrypting XML content.

Applies to the VERIFY use case.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Overrides:

setParameters in class Algorithm

Parameters:

transformElement - The DOM element of this Transform

Throws:

AlgorithmException - if the <Transform> or its child elements could not be parsed

toElement

public org.w3c.dom.Element toElement(org.w3c.dom.Document document)
                              throws AlgorithmException

Returns the DOM element representation of the transform.

Applies to the SIGN use case.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Specified by:

toElement in class Algorithm

Parameters:

document - the DOM document into which the DOM nodes will be added

Returns:

The DOM element representation of the transform.

Throws:

AlgorithmException - if no identifying URI has been specified for this transform.

transform

public java.lang.Object transform()
                           throws AlgorithmException

Executes the transform.

This method identifies all <EncryptedData> DOM elements in the input to the transform. In the SIGN use case, this method creates a DOM representation of the <Transform>. In the VERIFY use case, the transform method determines which elements in the input node set must be decrypted for the signature to be verifiable (the <EncryptedData> elements that were created after the content was signed. If the transform can access the required decryption keys, it decrypts those elements. It does this repeatedly (in case of super-encryptions), until the input node set is transformed into the node set that was signed.

The input to this transform must have been specified previously, as a NodeList.

Note

The Toolkit invokes this method internally, and your application should not need to call it.

Specified by:

transform in class Transform

Returns:

The same NodeList as the input (in the SIGN use case), or the NodeList transformed as described above (in the VERIFY use case).

Throws:

AlgorithmException - if no input node set was provided, or if the decryption fails for some reason