org.opensaml.xml.encryption
Class Encrypter

java.lang.Object
  org.opensaml.xml.encryption.Encrypter

public class Encrypter
extends Object

Supports encryption of XMLObjects, their content and keys, according to the XML Encryption specification, version 20021210.

Various overloaded method variants are supplied for encrypting XMLObjects and their contents (with or without encryption of the associated data encryption key), as well as for encrypting keys separately.

The parameters for data encryption are specified with an instance of EncryptionParameters. The parameters for key encryption are specified with one or more instances of KeyEncryptionParameters.

The data encryption credential supplied by EncryptionParameters.getEncryptionCredential() is mandatory unless key encryption is also being performed and all associated key encryption parameters contain a valid key encryption credential containing a valid key encryption key. In this case the data encryption key will be randomly generated based on the algorithm URI supplied by EncryptionParameters.getAlgorithm().

If encryption of the data encryption key is being performed using the overloaded methods for elements or content, the resulting EncryptedKey(s) will be placed inline within the KeyInfo of the resulting EncryptedData. If this is not the desired behavior, the XMLObject and the data encryption key should be encrypted separately, and the placement of EncryptedKey(s) handled by the caller. Specialized subclasses of this class maybe also handle key placement in an application-specific manner.

Field Summary

private Unmarshaller	encryptedDataUnmarshaller Unmarshaller used to create EncryptedData objects from DOM element.
private Unmarshaller	encryptedKeyUnmarshaller Unmarshaller used to create EncryptedData objects from DOM element.
private String	jcaProviderName The name of the JCA security provider to use.
private XMLSignatureBuilder<KeyInfo>	keyInfoBuilder Builder instance for building KeyInfo objects.
private Logger	log Class logger.

Constructor Summary

Encrypter()
Constructor.

Method Summary

protected void	checkAndMarshall(XMLObject xmlObject) Ensure that the XMLObject is marshalled.
protected void	checkParams(EncryptionParameters encParams) Check data encryption parameters for consistency and required values.
protected void	checkParams(EncryptionParameters encParams, List<KeyEncryptionParameters> kekParamsList) Check the encryption parameters and key encryption parameters for valid combinations of options.
protected void	checkParams(KeyEncryptionParameters kekParams, boolean allowEmpty) Check key encryption parameters for consistency and required values.
protected void	checkParams(List<KeyEncryptionParameters> kekParamsList, boolean allowEmpty) Check a list of key encryption parameters for consistency and required values.
EncryptedData	encryptElement(XMLObject xmlObject, EncryptionParameters encParams) Encrypts the DOM representation of the XMLObject.
EncryptedData	encryptElement(XMLObject xmlObject, EncryptionParameters encParams, KeyEncryptionParameters kekParams) Encrypts the DOM representation of the XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey within the EncryptedData's KeyInfo.
EncryptedData	encryptElement(XMLObject xmlObject, EncryptionParameters encParams, List<KeyEncryptionParameters> kekParamsList) Encrypts the DOM representation of the XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey(s) within the EncryptedData's KeyInfo.
private EncryptedData	encryptElement(XMLObject xmlObject, EncryptionParameters encParams, List<KeyEncryptionParameters> kekParamsList, boolean encryptContentMode) Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag.
protected EncryptedData	encryptElement(XMLObject xmlObject, Key encryptionKey, String encryptionAlgorithmURI, boolean encryptContentMode) Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag.
EncryptedData	encryptElementContent(XMLObject xmlObject, EncryptionParameters encParams) Encrypts the DOM representation of the content of an XMLObject.
EncryptedData	encryptElementContent(XMLObject xmlObject, EncryptionParameters encParams, KeyEncryptionParameters kekParams) Encrypts the DOM representation of the content of an XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey within the EncryptedData's KeyInfo..
EncryptedData	encryptElementContent(XMLObject xmlObject, EncryptionParameters encParams, List<KeyEncryptionParameters> kekParamsList) Encrypts the DOM representation of the content of an XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey(s) within the EncryptedData's KeyInfo..
EncryptedKey	encryptKey(Key key, KeyEncryptionParameters kekParams, Document containingDocument) Encrypts a key.
protected EncryptedKey	encryptKey(Key targetKey, Key encryptionKey, String encryptionAlgorithmURI, Document containingDocument) Encrypts a key using the specified encryption key and algorithm URI.
List<EncryptedKey>	encryptKey(Key key, List<KeyEncryptionParameters> kekParamsList, Document containingDocument) Encrypts a key once for each key encryption parameters set that is supplied.
protected SecretKey	generateEncryptionKey(String encryptionAlgorithmURI) Generate a random symmetric encryption key.
String	getJCAProviderName() Get the Java Cryptography Architecture (JCA) security provider name that should be used to provide the encryption support.
protected void	postProcessApacheEncryptedKey(EncryptedKey apacheEncryptedKey, Key targetKey, Key encryptionKey, String encryptionAlgorithmURI, Document containingDocument) Post-process the Apache EncryptedKey, prior to marshalling to DOM and unmarshalling into an XMLObject.
void	setJCAProviderName(String providerName) Set the Java Cryptography Architecture (JCA) security provider name that should be used to provide the encryption support.

Methods inherited from class java.lang.Object

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

Field Detail

log

private final Logger log

Class logger.

encryptedDataUnmarshaller

private Unmarshaller encryptedDataUnmarshaller

Unmarshaller used to create EncryptedData objects from DOM element.

encryptedKeyUnmarshaller

private Unmarshaller encryptedKeyUnmarshaller

Unmarshaller used to create EncryptedData objects from DOM element.

keyInfoBuilder

private XMLSignatureBuilder<KeyInfo> keyInfoBuilder

Builder instance for building KeyInfo objects.

jcaProviderName

private String jcaProviderName

The name of the JCA security provider to use.

Constructor Detail

Encrypter

public Encrypter()

Constructor.

Method Detail

getJCAProviderName

public String getJCAProviderName()

Get the Java Cryptography Architecture (JCA) security provider name that should be used to provide the encryption support. Defaults to null, which means that the first registered provider which supports the requested encryption algorithm URI will be used.

Returns:

the JCA provider name to use

setJCAProviderName

public void setJCAProviderName(String providerName)

Set the Java Cryptography Architecture (JCA) security provider name that should be used to provide the encryption support. Defaults to null, which means that the first registered provider which supports the requested encryption algorithm URI will be used.

Parameters:

providerName - the JCA provider name to use

encryptElement

public EncryptedData encryptElement(XMLObject xmlObject,
                                    EncryptionParameters encParams)
                             throws EncryptionException

Encrypts the DOM representation of the XMLObject.

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElement

public EncryptedData encryptElement(XMLObject xmlObject,
                                    EncryptionParameters encParams,
                                    KeyEncryptionParameters kekParams)
                             throws EncryptionException

Encrypts the DOM representation of the XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey within the EncryptedData's KeyInfo.

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

kekParams - parameters for encrypting the encryption key

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElement

public EncryptedData encryptElement(XMLObject xmlObject,
                                    EncryptionParameters encParams,
                                    List<KeyEncryptionParameters> kekParamsList)
                             throws EncryptionException

Encrypts the DOM representation of the XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey(s) within the EncryptedData's KeyInfo.

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

kekParamsList - parameters for encrypting the encryption key

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElementContent

public EncryptedData encryptElementContent(XMLObject xmlObject,
                                           EncryptionParameters encParams)
                                    throws EncryptionException

Encrypts the DOM representation of the content of an XMLObject.

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElementContent

public EncryptedData encryptElementContent(XMLObject xmlObject,
                                           EncryptionParameters encParams,
                                           KeyEncryptionParameters kekParams)
                                    throws EncryptionException

Encrypts the DOM representation of the content of an XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey within the EncryptedData's KeyInfo..

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

kekParams - parameters for encrypting the encryption key

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElementContent

public EncryptedData encryptElementContent(XMLObject xmlObject,
                                           EncryptionParameters encParams,
                                           List<KeyEncryptionParameters> kekParamsList)
                                    throws EncryptionException

Encrypts the DOM representation of the content of an XMLObject, encrypts the encryption key using the specified key encryption parameters and places the resulting EncryptedKey(s) within the EncryptedData's KeyInfo..

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - parameters for encrypting the data

kekParamsList - parameters for encrypting the encryption key

Returns:

the resulting EncryptedData element

Throws:

EncryptionException - exception thrown on encryption errors

encryptKey

public List<EncryptedKey> encryptKey(Key key,
                                     List<KeyEncryptionParameters> kekParamsList,
                                     Document containingDocument)
                              throws EncryptionException

Encrypts a key once for each key encryption parameters set that is supplied.

Parameters:

key - the key to encrypt

kekParamsList - a list parameters for encrypting the key

containingDocument - the document that will own the DOM element underlying the resulting EncryptedKey objects

Returns:

the resulting list of EncryptedKey objects

Throws:

EncryptionException - exception thrown on encryption errors

encryptKey

public EncryptedKey encryptKey(Key key,
                               KeyEncryptionParameters kekParams,
                               Document containingDocument)
                        throws EncryptionException

Encrypts a key.

Parameters:

key - the key to encrypt

kekParams - parameters for encrypting the key

containingDocument - the document that will own the DOM element underlying the resulting EncryptedKey object

Returns:

the resulting EncryptedKey object

Throws:

EncryptionException - exception thrown on encryption errors

encryptKey

protected EncryptedKey encryptKey(Key targetKey,
                                  Key encryptionKey,
                                  String encryptionAlgorithmURI,
                                  Document containingDocument)
                           throws EncryptionException

Encrypts a key using the specified encryption key and algorithm URI.

Parameters:

targetKey - the key to encrypt

encryptionKey - the key with which to encrypt the target key

encryptionAlgorithmURI - the XML Encryption algorithm URI corresponding to the encryption key

containingDocument - the document that will own the resulting element

Returns:

the new EncryptedKey object

Throws:

EncryptionException - exception thrown on encryption errors

postProcessApacheEncryptedKey

protected void postProcessApacheEncryptedKey(EncryptedKey apacheEncryptedKey,
                                             Key targetKey,
                                             Key encryptionKey,
                                             String encryptionAlgorithmURI,
                                             Document containingDocument)
                                      throws EncryptionException

Post-process the Apache EncryptedKey, prior to marshalling to DOM and unmarshalling into an XMLObject.

Parameters:

apacheEncryptedKey - the Apache EncryptedKeyObject to post-process

targetKey - the key to encrypt

encryptionKey - the key with which to encrypt the target key

encryptionAlgorithmURI - the XML Encryption algorithm URI corresponding to the encryption key

containingDocument - the document that will own the resulting element

Throws:

EncryptionException - exception thrown on encryption errors

encryptElement

protected EncryptedData encryptElement(XMLObject xmlObject,
                                       Key encryptionKey,
                                       String encryptionAlgorithmURI,
                                       boolean encryptContentMode)
                                throws EncryptionException

Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag.

Parameters:

xmlObject - the XMLObject to be encrypted

encryptionKey - the key with which to encrypt the XMLObject

encryptionAlgorithmURI - the XML Encryption algorithm URI corresponding to the encryption key

encryptContentMode - whether just the content of the XMLObject should be encrypted

Returns:

the resulting EncryptedData object

Throws:

EncryptionException - exception thrown on encryption errors

encryptElement

private EncryptedData encryptElement(XMLObject xmlObject,
                                     EncryptionParameters encParams,
                                     List<KeyEncryptionParameters> kekParamsList,
                                     boolean encryptContentMode)
                              throws EncryptionException

Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag. EncryptedKeys, if any, are placed inline within the KeyInfo of the resulting EncryptedData.

Parameters:

xmlObject - the XMLObject to be encrypted

encParams - the encryption parameters to use

kekParamsList - the key encryption parameters to use

encryptContentMode - whether just the content of the XMLObject should be encrypted

Returns:

the resulting EncryptedData object

Throws:

EncryptionException - exception thrown on encryption errors

checkAndMarshall

protected void checkAndMarshall(XMLObject xmlObject)
                         throws EncryptionException

Ensure that the XMLObject is marshalled.

Parameters:

xmlObject - the object to check and marshall

Throws:

EncryptionException - thrown if there is an error when marshalling the XMLObject

checkParams

protected void checkParams(EncryptionParameters encParams)
                    throws EncryptionException

Check data encryption parameters for consistency and required values.

Parameters:

encParams - the data encryption parameters to check

Throws:

EncryptionException - thrown if any parameters are missing or have invalid values

checkParams

protected void checkParams(KeyEncryptionParameters kekParams,
                           boolean allowEmpty)
                    throws EncryptionException

Check key encryption parameters for consistency and required values.

Parameters:

kekParams - the key encryption parameters to check

allowEmpty - if false, a null parameter is treated as an error

Throws:

EncryptionException - thrown if any parameters are missing or have invalid values

checkParams

protected void checkParams(List<KeyEncryptionParameters> kekParamsList,
                           boolean allowEmpty)
                    throws EncryptionException

Check a list of key encryption parameters for consistency and required values.

Parameters:

kekParamsList - the key encryption parameters list to check

allowEmpty - if false, a null or empty list is treated as an error

Throws:

EncryptionException - thrown if any parameters are missing or have invalid values

checkParams

protected void checkParams(EncryptionParameters encParams,
                           List<KeyEncryptionParameters> kekParamsList)
                    throws EncryptionException

Check the encryption parameters and key encryption parameters for valid combinations of options.

Parameters:

encParams - the encryption parameters to use

kekParamsList - the key encryption parameters to use

Throws:

EncryptionException - exception thrown on encryption errors

generateEncryptionKey

protected SecretKey generateEncryptionKey(String encryptionAlgorithmURI)
                                   throws EncryptionException

Generate a random symmetric encryption key.

Parameters:

encryptionAlgorithmURI - the encryption algorithm URI

Returns:

a randomly generated symmetric key

Throws:

EncryptionException - thrown if the key can not be generated based on the specified algorithm URI