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 Details

    • 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 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