Class XMLCipher

java.lang.Object
org.apache.xml.security.encryption.XMLCipher
public class XMLCipher extends Object
XMLCipher encrypts and decrypts the contents of Documents, Elements and Element contents. It was designed to resemble javax.crypto.Cipher in order to facilitate understanding of its functioning.

  • Field Details

  • Constructor Details

    • XMLCipher

      private XMLCipher(String transformation, String provider, String canonAlg, String digestMethod) throws XMLEncryptionException
      Creates a new XMLCipher.
      Parameters:
      transformation - the name of the transformation, e.g., XMLCipher.TRIPLEDES. If null the XMLCipher can only be used for decrypt or unwrap operations where the encryption method is defined in the EncryptionMethod element.
      provider - the JCE provider that supplies the transformation, if null use the default provider.
      canonAlg - the name of the c14n algorithm, if null use standard serializer
      digestMethod - An optional digestMethod to use.
      Throws:
      XMLEncryptionException

  • Method Details

    • setSerializer

      public void setSerializer(Serializer serializer)
      Set the Serializer algorithm to use

    • getSerializer

      public Serializer getSerializer()
      Get the Serializer algorithm to use

    • isValidEncryptionAlgorithm

      private static boolean isValidEncryptionAlgorithm(String algorithm)
      Checks to ensure that the supplied algorithm is valid.
      Parameters:
      algorithm - the algorithm to check.
      Returns:
      true if the algorithm is valid, otherwise false.
      Since:
      1.0.

    • validateTransformation

      private static void validateTransformation(String transformation)
      Validate the transformation argument of getInstance or getProviderInstance
      Parameters:
      transformation - the name of the transformation, e.g., XMLCipher.TRIPLEDES which is shorthand for "http://www.w3.org/2001/04/xmlenc#tripledes-cbc"

    • getInstance

      public static XMLCipher getInstance(String transformation) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation and operates on the specified context document.

      If the default provider package supplies an implementation of the requested transformation, an instance of Cipher containing that implementation is returned. If the transformation is not available in the default provider package, other provider packages are searched.

      NOTE1: The transformation name does not follow the same pattern as that outlined in the Java Cryptography Extension Reference Guide but rather that specified by the XML Encryption Syntax and Processing document. The rational behind this is to make it easier for a novice at writing Java Encryption software to use the library.

      NOTE2: getInstance() does not follow the same pattern regarding exceptional conditions as that used in javax.crypto.Cipher. Instead, it only throws an XMLEncryptionException which wraps an underlying exception. The stack trace from the exception should be self explanatory.

      Parameters:
      transformation - the name of the transformation, e.g., XMLCipher.TRIPLEDES which is shorthand for "http://www.w3.org/2001/04/xmlenc#tripledes-cbc"
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException
      See Also:

    • getInstance

      public static XMLCipher getInstance(String transformation, String canon) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation, operates on the specified context document and serializes the document with the specified canonicalization algorithm before it encrypts the document.

      Parameters:
      transformation - the name of the transformation
      canon - the name of the c14n algorithm, if null use standard serializer
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • getInstance

      public static XMLCipher getInstance(String transformation, String canon, String digestMethod) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation, operates on the specified context document and serializes the document with the specified canonicalization algorithm before it encrypts the document.

      Parameters:
      transformation - the name of the transformation
      canon - the name of the c14n algorithm, if null use standard serializer
      digestMethod - An optional digestMethod to use
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • getProviderInstance

      public static XMLCipher getProviderInstance(String transformation, String provider) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation and operates on the specified context document.
      Parameters:
      transformation - the name of the transformation
      provider - the JCE provider that supplies the transformation
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • getProviderInstance

      public static XMLCipher getProviderInstance(String transformation, String provider, String canon) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation, operates on the specified context document and serializes the document with the specified canonicalization algorithm before it encrypts the document.

      Parameters:
      transformation - the name of the transformation
      provider - the JCE provider that supplies the transformation
      canon - the name of the c14n algorithm, if null use standard serializer
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • getProviderInstance

      public static XMLCipher getProviderInstance(String transformation, String provider, String canon, String digestMethod) throws XMLEncryptionException
      Returns an XMLCipher that implements the specified transformation, operates on the specified context document and serializes the document with the specified canonicalization algorithm before it encrypts the document.

      Parameters:
      transformation - the name of the transformation
      provider - the JCE provider that supplies the transformation
      canon - the name of the c14n algorithm, if null use standard serializer
      digestMethod - An optional digestMethod to use
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • getInstance

      public static XMLCipher getInstance() throws XMLEncryptionException
      Returns an XMLCipher that implements no specific transformation, and can therefore only be used for decrypt or unwrap operations where the encryption method is defined in the EncryptionMethod element.
      Returns:
      The XMLCipher
      Throws:
      XMLEncryptionException

    • getProviderInstance

      public static XMLCipher getProviderInstance(String provider) throws XMLEncryptionException
      Returns an XMLCipher that implements no specific transformation, and can therefore only be used for decrypt or unwrap operations where the encryption method is defined in the EncryptionMethod element. Allows the caller to specify a provider that will be used for cryptographic operations.
      Parameters:
      provider - the JCE provider that supplies the transformation
      Returns:
      the XMLCipher
      Throws:
      XMLEncryptionException

    • init

      public void init(int opmode, Key key) throws XMLEncryptionException
      Initializes this cipher with a key.

      The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode. For WRAP and ENCRYPT modes, this also initialises the internal EncryptedKey or EncryptedData (with a CipherValue) structure that will be used during the ensuing operations. This can be obtained (in order to modify KeyInfo elements etc. prior to finalising the encryption) by calling getEncryptedData() or getEncryptedKey().

      Parameters:
      opmode - the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE)
      key -
      Throws:
      XMLEncryptionException
      See Also:

    • setSecureValidation

      public void setSecureValidation(boolean secureValidation)
      Set whether secure validation is enabled or not. The default is false.

    • registerInternalKeyResolver

      public void registerInternalKeyResolver(KeyResolverSpi keyResolver)
      This method is used to add a custom KeyResolverSpi to an XMLCipher. These KeyResolvers are used in KeyInfo objects in DECRYPT and UNWRAP modes.
      Parameters:
      keyResolver -

    • getEncryptedData

      public EncryptedData getEncryptedData()
      Get the EncryptedData being built

      Returns the EncryptedData being built during an ENCRYPT operation. This can then be used by applications to add KeyInfo elements and set other parameters.

      Returns:
      The EncryptedData being built

    • getEncryptedKey

      public EncryptedKey getEncryptedKey()
      Get the EncryptedData being build Returns the EncryptedData being built during an ENCRYPT operation. This can then be used by applications to add KeyInfo elements and set other parameters.
      Returns:
      The EncryptedData being built

    • setKEK

      public void setKEK(Key kek)
      Set a Key Encryption Key.

      The Key Encryption Key (KEK) is used for encrypting/decrypting EncryptedKey elements. By setting this separately, the XMLCipher class can know whether a key applies to the data part or wrapped key part of an encrypted object.

      Parameters:
      kek - The key to use for de/encrypting key data

    • martial

      public Element martial(EncryptedData encryptedData)
      Martial an EncryptedData Takes an EncryptedData object and returns a DOM Element that represents the appropriate EncryptedData

      Note: This should only be used in cases where the context document has been passed in via a call to doFinal.

      Parameters:
      encryptedData - EncryptedData object to martial
      Returns:
      the DOM Element representing the passed in object

    • martial

      public Element martial(Document context, EncryptedData encryptedData)
      Martial an EncryptedData Takes an EncryptedData object and returns a DOM Element that represents the appropriate EncryptedData
      Parameters:
      context - The document that will own the returned nodes
      encryptedData - EncryptedData object to martial
      Returns:
      the DOM Element representing the passed in object

    • martial

      public Element martial(EncryptedKey encryptedKey)
      Martial an EncryptedKey Takes an EncryptedKey object and returns a DOM Element that represents the appropriate EncryptedKey

      Note: This should only be used in cases where the context document has been passed in via a call to doFinal.

      Parameters:
      encryptedKey - EncryptedKey object to martial
      Returns:
      the DOM Element representing the passed in object

    • martial

      public Element martial(Document context, EncryptedKey encryptedKey)
      Martial an EncryptedKey Takes an EncryptedKey object and returns a DOM Element that represents the appropriate EncryptedKey
      Parameters:
      context - The document that will own the created nodes
      encryptedKey - EncryptedKey object to martial
      Returns:
      the DOM Element representing the passed in object

    • martial

      public Element martial(ReferenceList referenceList)
      Martial a ReferenceList Takes a ReferenceList object and returns a DOM Element that represents the appropriate ReferenceList

      Note: This should only be used in cases where the context document has been passed in via a call to doFinal.

      Parameters:
      referenceList - ReferenceList object to martial
      Returns:
      the DOM Element representing the passed in object

    • martial

      public Element martial(Document context, ReferenceList referenceList)
      Martial a ReferenceList Takes a ReferenceList object and returns a DOM Element that represents the appropriate ReferenceList
      Parameters:
      context - The document that will own the created nodes
      referenceList - ReferenceList object to martial
      Returns:
      the DOM Element representing the passed in object

    • encryptElement

      private Document encryptElement(Element element) throws Exception
      Encrypts an Element and replaces it with its encrypted counterpart in the context Document, that is, the Document specified when one calls getInstance.
      Parameters:
      element - the Element to encrypt.
      Returns:
      the context Document with the encrypted Element having replaced the source Element.
      Throws:
      Exception

    • encryptElementContent

      private Document encryptElementContent(Element element) throws Exception
      Encrypts a NodeList (the contents of an Element) and replaces its parent Element's content with this the resulting EncryptedType within the context Document, that is, the Document specified when one calls getInstance.
      Parameters:
      element - the NodeList to encrypt.
      Returns:
      the context Document with the encrypted NodeList having replaced the content of the source Element.
      Throws:
      Exception

    • doFinal

      public Document doFinal(Document context, Document source) throws Exception
      Process a DOM Document node. The processing depends on the initialization parameters of init().
      Parameters:
      context - the context Document.
      source - the Document to be encrypted or decrypted.
      Returns:
      the processed Document.
      Throws:
      Exception - to indicate any exceptional conditions.

    • doFinal

      public Document doFinal(Document context, Element element) throws Exception
      Process a DOM Element node. The processing depends on the initialization parameters of init().
      Parameters:
      context - the context Document.
      element - the Element to be encrypted.
      Returns:
      the processed Document.
      Throws:
      Exception - to indicate any exceptional conditions.

    • doFinal

      public Document doFinal(Document context, Element element, boolean content) throws Exception
      Process the contents of a DOM Element node. The processing depends on the initialization parameters of init().
      Parameters:
      context - the context Document.
      element - the Element which contents is to be encrypted.
      content -
      Returns:
      the processed Document.
      Throws:
      Exception - to indicate any exceptional conditions.

    • encryptData

      public EncryptedData encryptData(Document context, Element element) throws Exception
      Returns an EncryptedData interface. Use this operation if you want to have full control over the contents of the EncryptedData structure. This does not change the source document in any way.
      Parameters:
      context - the context Document.
      element - the Element that will be encrypted.
      Returns:
      the EncryptedData
      Throws:
      Exception

    • encryptData

      public EncryptedData encryptData(Document context, String type, InputStream serializedData) throws Exception
      Returns an EncryptedData interface. Use this operation if you want to have full control over the serialization of the element or element content. This does not change the source document in any way.
      Parameters:
      context - the context Document.
      type - a URI identifying type information about the plaintext form of the encrypted content (may be null)
      serializedData - the serialized data
      Returns:
      the EncryptedData
      Throws:
      Exception

    • encryptData

      public EncryptedData encryptData(Document context, Element element, boolean contentMode) throws Exception
      Returns an EncryptedData interface. Use this operation if you want to have full control over the contents of the EncryptedData structure. This does not change the source document in any way.
      Parameters:
      context - the context Document.
      element - the Element that will be encrypted.
      contentMode - true to encrypt element's content only, false otherwise
      Returns:
      the EncryptedData
      Throws:
      Exception

    • encryptData

      private EncryptedData encryptData(Document context, Element element, String type, InputStream serializedData) throws Exception
      Throws:
      Exception

    • constructBlockCipherParameters

      private AlgorithmParameterSpec constructBlockCipherParameters(String algorithm, byte[] iv)
      Build an AlgorithmParameterSpec instance used to initialize a Cipher instance for block cipher encryption and decryption.
      Parameters:
      algorithm - the XML encryption algorithm URI
      iv - the initialization vector
      Returns:
      the newly constructed AlgorithmParameterSpec instance, appropriate for the specified algorithm

    • loadEncryptedData

      public EncryptedData loadEncryptedData(Document context, Element element) throws XMLEncryptionException
      Returns an EncryptedData interface. Use this operation if you want to load an EncryptedData structure from a DOM structure and manipulate the contents.
      Parameters:
      context - the context Document.
      element - the Element that will be loaded
      Returns:
      the EncryptedData
      Throws:
      XMLEncryptionException

    • loadEncryptedKey

      public EncryptedKey loadEncryptedKey(Document context, Element element) throws XMLEncryptionException
      Returns an EncryptedKey interface. Use this operation if you want to load an EncryptedKey structure from a DOM structure and manipulate the contents.
      Parameters:
      context - the context Document.
      element - the Element that will be loaded
      Returns:
      the EncryptedKey
      Throws:
      XMLEncryptionException

    • loadEncryptedKey

      public EncryptedKey loadEncryptedKey(Element element) throws XMLEncryptionException
      Returns an EncryptedKey interface. Use this operation if you want to load an EncryptedKey structure from a DOM structure and manipulate the contents. Assumes that the context document is the document that owns the element
      Parameters:
      element - the Element that will be loaded
      Returns:
      the EncryptedKey
      Throws:
      XMLEncryptionException

    • encryptKey

      public EncryptedKey encryptKey(Document doc, Key key) throws XMLEncryptionException
      Encrypts a key to an EncryptedKey structure
      Parameters:
      doc - the Context document that will be used to general DOM
      key - Key to encrypt (will use previously set KEK to perform encryption
      Returns:
      the EncryptedKey
      Throws:
      XMLEncryptionException

    • encryptKey

      public EncryptedKey encryptKey(Document doc, Key key, String mgfAlgorithm, byte[] oaepParams) throws XMLEncryptionException
      Encrypts a key to an EncryptedKey structure
      Parameters:
      doc - the Context document that will be used to general DOM
      key - Key to encrypt (will use previously set KEK to perform encryption
      mgfAlgorithm - The xenc11 MGF Algorithm to use
      oaepParams - The OAEPParams to use
      Returns:
      the EncryptedKey
      Throws:
      XMLEncryptionException

    • encryptKey

      public EncryptedKey encryptKey(Document doc, Key key, String mgfAlgorithm, byte[] oaepParams, SecureRandom random) throws XMLEncryptionException
      Encrypts a key to an EncryptedKey structure
      Parameters:
      doc - the Context document that will be used to general DOM
      key - Key to encrypt (will use previously set KEK to perform encryption
      mgfAlgorithm - The xenc11 MGF Algorithm to use
      oaepParams - The OAEPParams to use
      random - The SecureRandom instance to use when initializing the Cipher
      Returns:
      the EncryptedKey
      Throws:
      XMLEncryptionException

    • decryptKey

      public Key decryptKey(EncryptedKey encryptedKey, String algorithm) throws XMLEncryptionException
      Decrypt a key from a passed in EncryptedKey structure
      Parameters:
      encryptedKey - Previously loaded EncryptedKey that needs to be decrypted.
      algorithm - Algorithm for the decrypted key
      Returns:
      a key corresponding to the given type
      Throws:
      XMLEncryptionException

    • constructOAEPParameters

      private OAEPParameterSpec constructOAEPParameters(String encryptionAlgorithm, String digestAlgorithm, String mgfAlgorithm, byte[] oaepParams)
      Construct an OAEPParameterSpec object from the given parameters

    • constructCipher

      private Cipher constructCipher(String algorithm, String digestAlgorithm) throws XMLEncryptionException
      Construct a Cipher object
      Throws:
      XMLEncryptionException

    • constructCipher

      private Cipher constructCipher(String algorithm, String digestAlgorithm, Exception nsae) throws XMLEncryptionException
      Throws:
      XMLEncryptionException

    • decryptKey

      public Key decryptKey(EncryptedKey encryptedKey) throws XMLEncryptionException
      Decrypt a key from a passed in EncryptedKey structure. This version is used mainly internally, when the cipher already has an EncryptedData loaded. The algorithm URI will be read from the EncryptedData
      Parameters:
      encryptedKey - Previously loaded EncryptedKey that needs to be decrypted.
      Returns:
      a key corresponding to the given type
      Throws:
      XMLEncryptionException

    • removeContent

      private static void removeContent(Node node)
      Removes the contents of a Node.
      Parameters:
      node - the Node to clear.

    • decryptElement

      private Document decryptElement(Element element) throws XMLEncryptionException
      Decrypts EncryptedData in a single-part operation.
      Parameters:
      element - the EncryptedData to decrypt.
      Returns:
      the Node as a result of the decrypt operation.
      Throws:
      XMLEncryptionException

    • decryptElementContent

      private Document decryptElementContent(Element element) throws XMLEncryptionException
      Parameters:
      element -
      Returns:
      the Node as a result of the decrypt operation.
      Throws:
      XMLEncryptionException

    • decryptToByteArray

      public byte[] decryptToByteArray(Element element) throws XMLEncryptionException
      Decrypt an EncryptedData element to a byte array. When passed in an EncryptedData node, returns the decryption as a byte array. Does not modify the source document.
      Parameters:
      element -
      Returns:
      the bytes resulting from the decryption
      Throws:
      XMLEncryptionException

    • createEncryptedData

      public EncryptedData createEncryptedData(int type, String value) throws XMLEncryptionException
      Creates an EncryptedData Element. The newEncryptedData and newEncryptedKey methods create fairly complete elements that are immediately useable. All the other create* methods return bare elements that still need to be built upon.

      An EncryptionMethod will still need to be added however

      Parameters:
      type - Either REFERENCE_TYPE or VALUE_TYPE - defines what kind of CipherData this EncryptedData will contain.
      value - the Base 64 encoded, encrypted text to wrap in the EncryptedData or the URI to set in the CipherReference (usage will depend on the type
      Returns:
      the EncryptedData Element.
      Throws:
      XMLEncryptionException

    • createEncryptedKey

      public EncryptedKey createEncryptedKey(int type, String value) throws XMLEncryptionException
      Creates an EncryptedKey Element. The newEncryptedData and newEncryptedKey methods create fairly complete elements that are immediately useable. All the other create* methods return bare elements that still need to be built upon.

      An EncryptionMethod will still need to be added however

      Parameters:
      type - Either REFERENCE_TYPE or VALUE_TYPE - defines what kind of CipherData this EncryptedData will contain.
      value - the Base 64 encoded, encrypted text to wrap in the EncryptedKey or the URI to set in the CipherReference (usage will depend on the type
      Returns:
      the EncryptedKey Element.
      Throws:
      XMLEncryptionException

    • createAgreementMethod

      public AgreementMethod createAgreementMethod(String algorithm)
      Create an AgreementMethod object
      Parameters:
      algorithm - Algorithm of the agreement method
      Returns:
      a new AgreementMethod

    • createCipherData

      public CipherData createCipherData(int type)
      Create a CipherData object
      Parameters:
      type - Type of this CipherData (either VALUE_TUPE or REFERENCE_TYPE)
      Returns:
      a new CipherData

    • createCipherReference

      public CipherReference createCipherReference(String uri)
      Create a CipherReference object
      Parameters:
      uri - The URI that the reference will refer
      Returns:
      a new CipherReference

    • createCipherValue

      public CipherValue createCipherValue(String value)
      Create a CipherValue element
      Parameters:
      value - The value to set the ciphertext to
      Returns:
      a new CipherValue

    • createEncryptionMethod

      public EncryptionMethod createEncryptionMethod(String algorithm)
      Create an EncryptionMethod object
      Parameters:
      algorithm - Algorithm for the encryption
      Returns:
      a new EncryptionMethod

    • createEncryptionProperties

      public EncryptionProperties createEncryptionProperties()
      Create an EncryptionProperties element
      Returns:
      a new EncryptionProperties

    • createEncryptionProperty

      public EncryptionProperty createEncryptionProperty()
      Create a new EncryptionProperty element
      Returns:
      a new EncryptionProperty

    • createReferenceList

      public ReferenceList createReferenceList(int type)
      Create a new ReferenceList object
      Parameters:
      type - ReferenceList.DATA_REFERENCE or ReferenceList.KEY_REFERENCE
      Returns:
      a new ReferenceList

    • createTransforms

      public Transforms createTransforms()
      Create a new Transforms object

      Note: A context document must have been set elsewhere (possibly via a call to doFinal). If not, use the createTransforms(Document) method.

      Returns:
      a new Transforms

    • createTransforms

      public Transforms createTransforms(Document doc)
      Create a new Transforms object Because the handling of Transforms is currently done in the signature code, the creation of a Transforms object requires a context document.
      Parameters:
      doc - Document that will own the created Transforms node
      Returns:
      a new Transforms

    • haveFunctionalIdentityTransformer

      private static boolean haveFunctionalIdentityTransformer()