org.opensaml.xml.encryption
Class Decrypter

java.lang.Object
  extended by org.opensaml.xml.encryption.Decrypter
Direct Known Subclasses:
Decrypter

public class Decrypter
extends java.lang.Object

Supports decryption of XMLObjects which represent data encrypted according to the XML Encryption specification, version 20021210.

XML Encryption can encrypt either a single Element or the contents of an Element. The caller of this class must select the decryption method which is most appropriate for their specific use case.

Note that the type of plaintext data contained by an EncryptedData can be checked prior to decryption by examining that element's type attribute (EncryptedType.getType()). This (optional) attribute may contain one of the following two constant values to aid in the decryption process: EncryptionConstants.TYPE_ELEMENT or EncryptionConstants.TYPE_CONTENT.

By nature the fundamental output of XML decryption is a DOM DocumentFragment with 1 or more immediate top-level DOM Node children. This case is reflected in the method decryptDataToDOM(EncryptedData). It is up to the caller to properly process the DOM Nodes which are the children of this document fragment. The DocumentFragment and its Node children will be owned by the DOM Document which owned the original EncryptedData before decryption. Note, however, that the Node children will not be a part of the tree of Nodes rooted at that Document's document element.

A typical use case will be that the content which was encrypted contained solely Element nodes. For this use case a convenience method is provided as decryptDataToList(EncryptedData), which returns a list of XMLObject's which are the result of unmarshalling each of the child Elements of the decrypted DocumentFragment.

Another typical use case is that the content which was encrypted was a single Element. For this use case a convenience method is provided as decryptData(EncryptedData), which returns a single XMLObject which was the result of unmarshalling this decrypted Element.

In both of these cases the underlying DOM Element which is represented by each of the returned XMLObjects will be owned by the DOM Document which also owns the original EncrytpedData Element. However, note that these cached DOM Elements are not part of the tree of Nodes rooted at that Document's document element. If these returned XMLObjects are then inserted as the children of other XMLObjects, it is up to the caller to ensure that the XMLObject tree is then remarshalled if the relationship of the cached DOM nodes is important (e.g. resolution of ID-typed attributes via Document.getElementById(String)).

For some use cases where the returned XMLObjects will not necessarily be stored back as children of another parent XMLObject, it may still necessary for the DOM Elements of the resultant XMLObjects to exist within the tree of Nodes rooted at a DOM Document's document element (e.g. signature verification on the standalone decrypted XMLObject). For these cases these method variants may be used: decryptDataToList(EncryptedData, boolean) and decryptData(EncryptedData, boolean). If the boolean parameter rootInNewDocument is true, then for each top-level child Element of the decrypted DocumentFragment, the following will occur:

  1. A new DOM Document will be created.
  2. The Element will be adopted into that Document.
  3. The Element will be made the root element of the Document.
  4. The Element will be unmarshalled into an XMLObject as in the single argument variant.

Note that new Document creation, node adoption and rooting the new document element are potentially very expensive. This should only be done where the caller's use case really requires it.


Constructor Summary
Decrypter(KeyInfoCredentialResolver newResolver, KeyInfoCredentialResolver newKEKResolver, EncryptedKeyResolver newEncKeyResolver)
          Constructor.
 
Method Summary
protected  void checkAndMarshall(XMLObject xmlObject)
          Ensure that the XMLObject is marshalled.
 XMLObject decryptData(EncryptedData encryptedData)
          Decrypts the supplied EncryptedData and returns the resulting XMLObject.
 XMLObject decryptData(EncryptedData encryptedData, boolean rootInNewDocument)
          Decrypts the supplied EncryptedData and returns the resulting XMLObject.
 org.w3c.dom.DocumentFragment decryptDataToDOM(EncryptedData encryptedData)
          Decrypts the supplied EncryptedData and returns the resulting DOM DocumentFragment.
 org.w3c.dom.DocumentFragment decryptDataToDOM(EncryptedData encryptedData, java.security.Key dataEncKey)
          Decrypts the supplied EncryptedData using the specified key, and returns the resulting DOM DocumentFragment.
 java.util.List<XMLObject> decryptDataToList(EncryptedData encryptedData)
          Decrypts the supplied EncryptedData and returns the resulting list of XMLObjects.
 java.util.List<XMLObject> decryptDataToList(EncryptedData encryptedData, boolean rootInNewDocument)
          Decrypts the supplied EncryptedData and returns the resulting list of XMLObjects.
 java.security.Key decryptKey(EncryptedKey encryptedKey, java.lang.String algorithm)
          Attempts to decrypt the supplied EncryptedKey and returns the resulting Java security Key object.
 java.security.Key decryptKey(EncryptedKey encryptedKey, java.lang.String algorithm, java.security.Key kek)
          Decrypts the supplied EncryptedKey and returns the resulting Java security Key object.
 EncryptedKeyResolver getEncryptedKeyResolver()
          Get the encrypted key resolver.
 KeyInfoCredentialResolver getKEKResolver()
          Get the key encryption key credential resolver.
 CredentialCriteriaSet getKEKResolverCriteria()
          Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element.
 KeyInfoCredentialResolver getKeyResolver()
          Get the data encryption key credential resolver.
 void setEncryptedKeyResolver(EncryptedKeyResolver newResolver)
          Set a new encrypted key resolver.
 void setKEKResolver(KeyInfoCredentialResolver newKEKResolver)
          Set a new key encryption key credential resolver.
 void setKEKResolverCriteria(CredentialCriteriaSet newCriteria)
          Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element.
 void setKeyResolver(KeyInfoCredentialResolver newResolver)
          Set a new data encryption key credential resolver.
 CredentialCriteriaSet setKeyResolverCriteria()
          Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element.
 void setKeyResolverCriteria(CredentialCriteriaSet newCriteria)
          Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Decrypter

public Decrypter(KeyInfoCredentialResolver newResolver,
                 KeyInfoCredentialResolver newKEKResolver,
                 EncryptedKeyResolver newEncKeyResolver)
Constructor.

Parameters:
newResolver - resolver for data encryption keys.
newKEKResolver - resolver for key encryption keys.
newEncKeyResolver - resolver for EncryptedKey elements
Method Detail

getKeyResolver

public KeyInfoCredentialResolver getKeyResolver()
Get the data encryption key credential resolver.

Returns:
the data encryption key resolver

setKeyResolver

public void setKeyResolver(KeyInfoCredentialResolver newResolver)
Set a new data encryption key credential resolver.

Parameters:
newResolver - the new data encryption key resolver

getKEKResolver

public KeyInfoCredentialResolver getKEKResolver()
Get the key encryption key credential resolver.

Returns:
the key encryption key resolver

setKEKResolver

public void setKEKResolver(KeyInfoCredentialResolver newKEKResolver)
Set a new key encryption key credential resolver.

Parameters:
newKEKResolver - the new key encryption key resolver

getEncryptedKeyResolver

public EncryptedKeyResolver getEncryptedKeyResolver()
Get the encrypted key resolver.

Returns:
the encrypted key resolver

setEncryptedKeyResolver

public void setEncryptedKeyResolver(EncryptedKeyResolver newResolver)
Set a new encrypted key resolver.

Parameters:
newResolver - the new encrypted key resolver

setKeyResolverCriteria

public CredentialCriteriaSet setKeyResolverCriteria()
Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element.

Returns:
the static criteria set to use

setKeyResolverCriteria

public void setKeyResolverCriteria(CredentialCriteriaSet newCriteria)
Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedData element.

Parameters:
newCriteria - the static criteria set to use

getKEKResolverCriteria

public CredentialCriteriaSet getKEKResolverCriteria()
Get the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element.

Returns:
the static criteria set to use

setKEKResolverCriteria

public void setKEKResolverCriteria(CredentialCriteriaSet newCriteria)
Set the optional static set of criteria used when resolving credentials based on the KeyInfo of an EncryptedKey element.

Parameters:
newCriteria - the static criteria set to use

decryptData

public XMLObject decryptData(EncryptedData encryptedData)
                      throws DecryptionException
Decrypts the supplied EncryptedData and returns the resulting XMLObject. This will only succeed if the decrypted EncryptedData contains exactly one DOM Node of type Element.

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
Returns:
the decrypted XMLObject
Throws:
DecryptionException - exception indicating a decryption error, possibly because the decrypted data contained more than one top-level Element, or some non-Element Node type.

decryptData

public XMLObject decryptData(EncryptedData encryptedData,
                             boolean rootInNewDocument)
                      throws DecryptionException
Decrypts the supplied EncryptedData and returns the resulting XMLObject. This will only succeed if the decrypted EncryptedData contains exactly one DOM Node of type Element.

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
rootInNewDocument - if true, root the underlying Element of the returned XMLObject in a new Document as described in Decrypter
Returns:
the decrypted XMLObject
Throws:
DecryptionException - exception indicating a decryption error, possibly because the decrypted data contained more than one top-level Element, or some non-Element Node type.

decryptDataToList

public java.util.List<XMLObject> decryptDataToList(EncryptedData encryptedData)
                                            throws DecryptionException
Decrypts the supplied EncryptedData and returns the resulting list of XMLObjects. This will succeed only if the decrypted EncryptedData contains at the top-level only DOM Elements (not other types of DOM Nodes).

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
Returns:
the list decrypted top-level XMLObjects
Throws:
DecryptionException - exception indicating a decryption error, possibly because the decrypted data contained DOM nodes other than type of Element

decryptDataToList

public java.util.List<XMLObject> decryptDataToList(EncryptedData encryptedData,
                                                   boolean rootInNewDocument)
                                            throws DecryptionException
Decrypts the supplied EncryptedData and returns the resulting list of XMLObjects. This will succeed only if the decrypted EncryptedData contains at the top-level only DOM Elements (not other types of DOM Nodes).

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
rootInNewDocument - if true, root the underlying Elements of the returned XMLObjects in a new Document as described in Decrypter
Returns:
the list decrypted top-level XMLObjects
Throws:
DecryptionException - exception indicating a decryption error, possibly because the decrypted data contained DOM nodes other than type of Element

decryptDataToDOM

public org.w3c.dom.DocumentFragment decryptDataToDOM(EncryptedData encryptedData)
                                              throws DecryptionException
Decrypts the supplied EncryptedData and returns the resulting DOM DocumentFragment.

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
Returns:
the decrypted DOM DocumentFragment
Throws:
DecryptionException - exception indicating a decryption error

decryptDataToDOM

public org.w3c.dom.DocumentFragment decryptDataToDOM(EncryptedData encryptedData,
                                                     java.security.Key dataEncKey)
                                              throws DecryptionException
Decrypts the supplied EncryptedData using the specified key, and returns the resulting DOM DocumentFragment.

Parameters:
encryptedData - encrypted data element containing the data to be decrypted
dataEncKey - Java Key with which to attempt decryption of the encrypted data
Returns:
the decrypted DOM DocumentFragment
Throws:
DecryptionException - exception indicating a decryption error

decryptKey

public java.security.Key decryptKey(EncryptedKey encryptedKey,
                                    java.lang.String algorithm)
                             throws DecryptionException
Attempts to decrypt the supplied EncryptedKey and returns the resulting Java security Key object. The algorithm of the decrypted key must be supplied by the caller based on knowledge of the associated EncryptedData information.

Parameters:
encryptedKey - encrypted key element containing the encrypted key to be decrypted
algorithm - the algorithm associated with the decrypted key
Returns:
the decrypted key
Throws:
DecryptionException - exception indicating a decryption error

decryptKey

public java.security.Key decryptKey(EncryptedKey encryptedKey,
                                    java.lang.String algorithm,
                                    java.security.Key kek)
                             throws DecryptionException
Decrypts the supplied EncryptedKey and returns the resulting Java security Key object. The algorithm of the decrypted key must be supplied by the caller based on knowledge of the associated EncryptedData information.

Parameters:
encryptedKey - encrypted key element containing the encrypted key to be decrypted
algorithm - the algorithm associated with the decrypted key
kek - the key encryption key with which to attempt decryption of the encrypted key
Returns:
the decrypted key
Throws:
DecryptionException - exception indicating a decryption error

checkAndMarshall

protected void checkAndMarshall(XMLObject xmlObject)
                         throws DecryptionException
Ensure that the XMLObject is marshalled.

Parameters:
xmlObject - the object to check and marshall
Throws:
DecryptionException - thrown if there is an error when marshalling the XMLObject