Package org.opensaml.xmlsec.encryption.support

# Class Encrypter

java.lang.Object
org.opensaml.xmlsec.encryption.support.Encrypter

Direct Known Subclasses:
  `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 `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
Description
`private final Unmarshaller`
`encryptedDataUnmarshaller`
Unmarshaller used to create EncryptedData objects from DOM element.
`private final Unmarshaller`
`encryptedKeyUnmarshaller`
Unmarshaller used to create EncryptedData objects from DOM element.
`private String`
`jcaProviderName`
The name of the JCA security provider to use.
`private final XMLSignatureBuilder<KeyInfo>`
`keyInfoBuilder`
Builder instance for building KeyInfo objects.
`private final org.slf4j.Logger`
`log`
Class logger.

## Constructor Summary

Constructors
Constructor
Description
`Encrypter()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected org.apache.xml.security.encryption.XMLCipher`
`buildXMLCipher(Key encryptionKey, 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(List<KeyEncryptionParameters> kekParamsList, boolean allowEmpty)`
Check a list of key encryption parameters for consistency and required values.
`protected void`
`checkParams(DataEncryptionParameters encParams)`
Check data encryption parameters for consistency and required values.
`protected void`
`checkParams(DataEncryptionParameters 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 byte[]`
`decodeOAEPParams(String base64Params)`
Safely decode and normalize base64-encoded OAEPParams data.
`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`
`encryptElement(XMLObject xmlObject, DataEncryptionParameters encParams)`
Encrypts the DOM representation of the XMLObject.
`EncryptedData`
`encryptElement(XMLObject xmlObject, DataEncryptionParameters 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, DataEncryptionParameters encParams, List<KeyEncryptionParameters> kekParamsList, boolean encryptContentMode)`
Encrypts the given XMLObject using the specified encryption key, algorithm URI and content mode flag.
`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`
`encryptElementContent(XMLObject xmlObject, DataEncryptionParameters encParams)`
Encrypts the DOM representation of the content of an XMLObject.
`EncryptedData`
`encryptElementContent(XMLObject xmlObject, DataEncryptionParameters 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..
`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..
`protected EncryptedKey`
`encryptKey(Key targetKey, Key encryptionKey, String encryptionAlgorithmURI, RSAOAEPParameters rsaOAEPParams, 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.
`EncryptedKey`
`encryptKey(Key key, KeyEncryptionParameters kekParams, Document containingDocument)`
Encrypts a key.
`protected SecretKey`
`generateEncryptionKey(String encryptionAlgorithmURI)`
Generate a random symmetric encryption key.
`protected String`
`getEffectiveMGF(String encryptionAlgorithmURI, RSAOAEPParameters rsaOAEPParams)`
Get the effective RSA OAEP mask generation function (MGF) to use.
`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, 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 Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

### encryptedDataUnmarshaller

@Nonnull private final Unmarshaller encryptedDataUnmarshaller
Unmarshaller used to create EncryptedData objects from DOM element.

### encryptedKeyUnmarshaller

@Nonnull private final Unmarshaller encryptedKeyUnmarshaller
Unmarshaller used to create EncryptedData objects from DOM element.

### keyInfoBuilder

@Nonnull private final XMLSignatureBuilder<KeyInfo> keyInfoBuilder
Builder instance for building KeyInfo objects.

### jcaProviderName

@Nullable private String jcaProviderName
The name of the JCA security provider to use.

## Constructor Details

### Encrypter

public Encrypter()
Constructor.

## Method Details

### getJCAProviderName

@Nullable 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(@Nullable 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 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 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 List<EncryptedKey> encryptKey(@Nonnull Key key, @Nonnull List<KeyEncryptionParameters> kekParamsList, @Nonnull 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 Key key, @Nonnull KeyEncryptionParameters kekParams, @Nonnull 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 Key targetKey, @Nonnull Key encryptionKey, @Nonnull String encryptionAlgorithmURI, @Nullable RSAOAEPParameters rsaOAEPParams, @Nonnull 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 Key encryptionKey, @Nonnull 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 String getEffectiveMGF(@Nonnull 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 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 Key targetKey, @Nonnull Key encryptionKey, @Nonnull String encryptionAlgorithmURI, @Nonnull 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 Key encryptionKey, @Nonnull 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 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 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 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 SecretKey generateEncryptionKey(@Nonnull 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