org.opensaml.xmlsec.encryption.support

Class Encrypter

java.lang.Object

org.opensaml.xmlsec.encryption.support.Encrypter

Direct Known Subclasses:

Encrypter

public class Encrypter
extends java.lang.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 DataEncryptionParameters. The parameters for key encryption are specified with one or more instances of KeyEncryptionParameters.

The data encryption credential supplied by DataEncryptionParameters.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 DataEncryptionParameters.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

Fields

Modifier and Type	Field and Description
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 java.lang.String	jcaProviderName The name of the JCA security provider to use.
private XMLSignatureBuilder<KeyInfo>	keyInfoBuilder Builder instance for building KeyInfo objects.
private org.slf4j.Logger	log Class logger.

Constructor Summary

Constructors

Constructor and Description
Encrypter() Constructor.

Method Summary

Modifier and Type	Method and Description
protected org.apache.xml.security.encryption.XMLCipher	buildXMLCipher(java.security.Key encryptionKey, java.lang.String encryptionAlgorithmURI, RSAOAEPParameters rsaOAEPParams) Construct and return an instance of XMLCipher based on the given inputs.
protected void	checkAndMarshall(XMLObject xmlObject) Ensure that the XMLObject is marshalled.
protected void	checkParams(DataEncryptionParameters encParams) Check data encryption parameters for consistency and required values.
protected void	checkParams(DataEncryptionParameters encParams, java.util.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(java.util.List<KeyEncryptionParameters> kekParamsList, boolean allowEmpty) Check a list of key encryption parameters for consistency and required values.
protected byte[]	decodeOAEPParams(java.lang.String base64Params) Safely decode and normalize base64-encoded OAEPParams data.
EncryptedData	encryptElement(XMLObject xmlObject, DataEncryptionParameters encParams) Encrypts the DOM representation of the XMLObject.
EncryptedData	encryptElement(XMLObject xmlObject, DataEncryptionParameters 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, DataEncryptionParameters encParams, java.util.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, DataEncryptionParameters encParams, java.util.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, java.security.Key encryptionKey, java.lang.String encryptionAlgorithmURI, boolean encryptContentMode) Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag.
EncryptedData	encryptElementContent(XMLObject xmlObject, DataEncryptionParameters encParams) Encrypts the DOM representation of the content of an XMLObject.
EncryptedData	encryptElementContent(XMLObject xmlObject, DataEncryptionParameters 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, DataEncryptionParameters encParams, java.util.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(java.security.Key key, KeyEncryptionParameters kekParams, org.w3c.dom.Document containingDocument) Encrypts a key.
protected EncryptedKey	encryptKey(java.security.Key targetKey, java.security.Key encryptionKey, java.lang.String encryptionAlgorithmURI, RSAOAEPParameters rsaOAEPParams, org.w3c.dom.Document containingDocument) Encrypts a key using the specified encryption key and algorithm URI.
java.util.List<EncryptedKey>	encryptKey(java.security.Key key, java.util.List<KeyEncryptionParameters> kekParamsList, org.w3c.dom.Document containingDocument) Encrypts a key once for each key encryption parameters set that is supplied.
protected javax.crypto.SecretKey	generateEncryptionKey(java.lang.String encryptionAlgorithmURI) Generate a random symmetric encryption key.
protected java.lang.String	getEffectiveMGF(java.lang.String encryptionAlgorithmURI, RSAOAEPParameters rsaOAEPParams) Get the effective RSA OAEP mask generation function (MGF) to use.
java.lang.String	getJCAProviderName() Get the Java Cryptography Architecture (JCA) security provider name that should be used to provide the encryption support.
protected void	postProcessApacheEncryptedKey(org.apache.xml.security.encryption.EncryptedKey apacheEncryptedKey, java.security.Key targetKey, java.security.Key encryptionKey, java.lang.String encryptionAlgorithmURI, org.w3c.dom.Document containingDocument) Post-process the Apache EncryptedKey, prior to marshalling to DOM and unmarshalling into an XMLObject.
void	setJCAProviderName(java.lang.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 org.slf4j.Logger log

Class logger.

encryptedDataUnmarshaller

private final Unmarshaller encryptedDataUnmarshaller

Unmarshaller used to create EncryptedData objects from DOM element.

encryptedKeyUnmarshaller

private final Unmarshaller encryptedKeyUnmarshaller

Unmarshaller used to create EncryptedData objects from DOM element.

keyInfoBuilder

private final XMLSignatureBuilder<KeyInfo> keyInfoBuilder

Builder instance for building KeyInfo objects.

jcaProviderName

private java.lang.String jcaProviderName

The name of the JCA security provider to use.

Constructor Detail

Encrypter

public Encrypter()

Constructor.

Method Detail

getJCAProviderName

@Nullable
public java.lang.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(@Nullable
                               java.lang.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

@Nonnull
public EncryptedData encryptElement(@Nonnull
                                             XMLObject xmlObject,
                                             @Nonnull
                                             DataEncryptionParameters 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

@Nonnull
public EncryptedData encryptElement(@Nonnull
                                             XMLObject xmlObject,
                                             @Nonnull
                                             DataEncryptionParameters encParams,
                                             @Nonnull
                                             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

@Nonnull
public EncryptedData encryptElement(@Nonnull
                                             XMLObject xmlObject,
                                             @Nonnull
                                             DataEncryptionParameters encParams,
                                             @Nonnull
                                             java.util.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

@Nonnull
public EncryptedData encryptElementContent(@Nonnull
                                                    XMLObject xmlObject,
                                                    @Nonnull
                                                    DataEncryptionParameters 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

@Nonnull
public EncryptedData encryptElementContent(@Nonnull
                                                    XMLObject xmlObject,
                                                    @Nonnull
                                                    DataEncryptionParameters encParams,
                                                    @Nonnull
                                                    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

@Nonnull
public EncryptedData encryptElementContent(@Nonnull
                                                    XMLObject xmlObject,
                                                    @Nonnull
                                                    DataEncryptionParameters encParams,
                                                    @Nonnull
                                                    java.util.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

@Nonnull
public java.util.List<EncryptedKey> encryptKey(@Nonnull
                                                        java.security.Key key,
                                                        @Nonnull
                                                        java.util.List<KeyEncryptionParameters> kekParamsList,
                                                        @Nonnull
                                                        org.w3c.dom.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

@Nonnull
public EncryptedKey encryptKey(@Nonnull
                                        java.security.Key key,
                                        @Nonnull
                                        KeyEncryptionParameters kekParams,
                                        @Nonnull
                                        org.w3c.dom.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

@Nonnull
protected EncryptedKey encryptKey(@Nonnull
                                           java.security.Key targetKey,
                                           @Nonnull
                                           java.security.Key encryptionKey,
                                           @Nonnull
                                           java.lang.String encryptionAlgorithmURI,
                                           @Nullable
                                           RSAOAEPParameters rsaOAEPParams,
                                           @Nonnull
                                           org.w3c.dom.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

rsaOAEPParams - the RSA-OAEP params instance (may be null)

containingDocument - the document that will own the resulting element

Returns:

the new EncryptedKey object

Throws:

EncryptionException - exception thrown on encryption errors

buildXMLCipher

@Nonnull
protected org.apache.xml.security.encryption.XMLCipher buildXMLCipher(@Nonnull
                                                                               java.security.Key encryptionKey,
                                                                               @Nonnull
                                                                               java.lang.String encryptionAlgorithmURI,
                                                                               @Nullable
                                                                               RSAOAEPParameters rsaOAEPParams)
                                                                        throws org.apache.xml.security.encryption.XMLEncryptionException

Construct and return an instance of XMLCipher based on the given inputs.

Parameters:

encryptionKey - the key transport encryption key with which to initialize the XMLCipher

encryptionAlgorithmURI - the key transport encryption algorithm URI

rsaOAEPParams - the optional RSA OAEP parameters instance

Returns:

new XMLCipher instance

Throws:

org.apache.xml.security.encryption.XMLEncryptionException - if there is a problem constructing the XMLCipher instance

getEffectiveMGF

@Nullable
protected java.lang.String getEffectiveMGF(@Nonnull
                                                     java.lang.String encryptionAlgorithmURI,
                                                     @Nullable
                                                     RSAOAEPParameters rsaOAEPParams)

Get the effective RSA OAEP mask generation function (MGF) to use.

Parameters:

encryptionAlgorithmURI - the key transport encryption algorithm URI

rsaOAEPParams - the optional RSA OAEP params instance

Returns:

the effective MGF algorithm URI to use, may be null

decodeOAEPParams

@Nullable
protected byte[] decodeOAEPParams(@Nullable
                                            java.lang.String base64Params)
                                     throws EncryptionException

Safely decode and normalize base64-encoded OAEPParams data.

Parameters:

base64Params - the base64-encoded parameters

Returns:

the decoded parameters or null

Throws:

EncryptionException - if there is a problem base64-decoding the OAEPParams data

postProcessApacheEncryptedKey

protected void postProcessApacheEncryptedKey(@Nonnull
                                             org.apache.xml.security.encryption.EncryptedKey apacheEncryptedKey,
                                             @Nonnull
                                             java.security.Key targetKey,
                                             @Nonnull
                                             java.security.Key encryptionKey,
                                             @Nonnull
                                             java.lang.String encryptionAlgorithmURI,
                                             @Nonnull
                                             org.w3c.dom.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

@Nonnull
protected EncryptedData encryptElement(@Nonnull
                                                XMLObject xmlObject,
                                                @Nonnull
                                                java.security.Key encryptionKey,
                                                @Nonnull
                                                java.lang.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

@Nonnull
private EncryptedData encryptElement(@Nonnull
                                              XMLObject xmlObject,
                                              @Nonnull
                                              DataEncryptionParameters encParams,
                                              @Nonnull
                                              java.util.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(@Nonnull
                                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(@Nonnull
                           DataEncryptionParameters 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(@Nullable
                           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(@Nullable
                           java.util.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(@Nonnull
                           DataEncryptionParameters encParams,
                           @Nullable
                           java.util.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

@Nonnull
protected javax.crypto.SecretKey generateEncryptionKey(@Nonnull
                                                                java.lang.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 cannot be generated based on the specified algorithm URI