Module java.xml.crypto
Package javax.xml.crypto.dsig

Class XMLSignatureFactory

java.lang.Object
javax.xml.crypto.dsig.XMLSignatureFactory
public abstract class XMLSignatureFactory
extends Object
A factory for creating XMLSignature objects from scratch or for unmarshalling an XMLSignature object from a corresponding XML representation.

XMLSignatureFactory Type

Each instance of XMLSignatureFactory supports a specific XML mechanism type. To create an XMLSignatureFactory, call one of the static getInstance methods, passing in the XML mechanism type desired, for example:

XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");

The objects that this factory produces will be based on DOM and abide by the DOM interoperability requirements as defined in the DOM Mechanism Requirements. See the XMLSignatureFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

XMLSignatureFactory implementations are registered and loaded using the Provider mechanism. For example, a service provider that supports the DOM mechanism would be specified in the Provider subclass as: 

     put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");

An implementation MUST minimally support the default mechanism type: DOM.

Note that a caller must use the same XMLSignatureFactory instance to create the XMLStructures of a particular XMLSignature that is to be generated. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

Also, the XMLStructures that are created by this factory may contain state specific to the XMLSignature and are not intended to be reusable.

Creating XMLSignatures from scratch

Once the XMLSignatureFactory has been created, objects can be instantiated by calling the appropriate method. For example, a Reference instance may be created by invoking one of the newReference methods.

Unmarshalling XMLSignatures from XML

Alternatively, an XMLSignature may be created from an existing XML representation by invoking the unmarshalXMLSignature method and passing it a mechanism-specific XMLValidateContext instance containing the XML content: 

 DOMValidateContext context = new DOMValidateContext(key, signatureElement);
 XMLSignature signature = factory.unmarshalXMLSignature(context);
Each XMLSignatureFactory must support the required XMLValidateContext types for that factory type, but may support others. A DOM XMLSignatureFactory must support DOMValidateContext objects.

Signing and marshalling XMLSignatures to XML

Each XMLSignature created by the factory can also be marshalled to an XML representation and signed, by invoking the sign method of the XMLSignature object and passing it a mechanism-specific XMLSignContext object containing the signing key and marshalling parameters (see DOMSignContext). For example: 
    DOMSignContext context = new DOMSignContext(privateKey, document);
    signature.sign(context);
Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single XMLSignatureFactory instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different XMLSignatureFactory instance need not synchronize.

Since:
1.6

  • Constructor Details

    • XMLSignatureFactory

      protected XMLSignatureFactory()
      Default constructor, for invocation by subclasses.

  • Method Details

    • getInstance

      public static XMLSignatureFactory getInstance​(String mechanismType)
      Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").

      This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLSignatureFactory implementation of the desired mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new XMLSignatureFactory object from the first Provider that supports the specified mechanism is returned.

      Note that the list of registered providers may be retrieved via the Security.getProviders() method.

      Implementation Note:
      The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by Security.getProviders().
      Parameters:
      mechanismType - the type of the XML processing mechanism and representation. See the XMLSignatureFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
      Returns:
      a new XMLSignatureFactory
      Throws:
      NullPointerException - if mechanismType is null
      NoSuchMechanismException - if no Provider supports an XMLSignatureFactory implementation for the specified mechanism
      See Also:
      Provider

    • getInstance

      public static XMLSignatureFactory getInstance​(String mechanismType, Provider provider)
      Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. Note that the specified Provider object does not have to be registered in the provider list.
      Parameters:
      mechanismType - the type of the XML processing mechanism and representation. See the XMLSignatureFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
      provider - the Provider object
      Returns:
      a new XMLSignatureFactory
      Throws:
      NullPointerException - if provider or mechanismType is null
      NoSuchMechanismException - if an XMLSignatureFactory implementation for the specified mechanism is not available from the specified Provider object
      See Also:
      Provider

    • getInstance

      public static XMLSignatureFactory getInstance​(String mechanismType, String provider) throws NoSuchProviderException
      Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. The specified provider must be registered in the security provider list.

      Note that the list of registered providers may be retrieved via the Security.getProviders() method.

      Parameters:
      mechanismType - the type of the XML processing mechanism and representation. See the XMLSignatureFactory section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
      provider - the string name of the provider
      Returns:
      a new XMLSignatureFactory
      Throws:
      NoSuchProviderException - if the specified provider is not registered in the security provider list
      NullPointerException - if provider or mechanismType is null
      NoSuchMechanismException - if an XMLSignatureFactory implementation for the specified mechanism is not available from the specified provider
      See Also:
      Provider

    • getInstance

      public static XMLSignatureFactory getInstance()
      Returns an XMLSignatureFactory that supports the default XML processing mechanism and representation type ("DOM").

      This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLSignatureFactory implementation of the default mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new XMLSignatureFactory object from the first Provider that supports the DOM mechanism is returned.

      Note that the list of registered providers may be retrieved via the Security.getProviders() method.

      Returns:
      a new XMLSignatureFactory
      Throws:
      NoSuchMechanismException - if no Provider supports an XMLSignatureFactory implementation for the DOM mechanism
      See Also:
      Provider

    • getMechanismType

      public final String getMechanismType()
      Returns the type of the XML processing mechanism and representation supported by this XMLSignatureFactory (ex: "DOM").
      Returns:
      the XML processing mechanism type supported by this XMLSignatureFactory

    • getProvider

      public final Provider getProvider()
      Returns the provider of this XMLSignatureFactory.
      Returns:
      the provider of this XMLSignatureFactory

    • newXMLSignature

      public abstract XMLSignature newXMLSignature​(SignedInfo si, KeyInfo ki)
      Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
      Parameters:
      si - the signed info
      ki - the key info (may be null)
      Returns:
      an XMLSignature
      Throws:
      NullPointerException - if si is null

    • newXMLSignature

      public abstract XMLSignature newXMLSignature​(SignedInfo si, KeyInfo ki, List<? extends XMLObject> objects, String id, String signatureValueId)
      Creates an XMLSignature and initializes it with the specified parameters.
      Parameters:
      si - the signed info
      ki - the key info (may be null)
      objects - a list of XMLObjects (may be empty or null)
      id - the Id (may be null)
      signatureValueId - the SignatureValue Id (may be null)
      Returns:
      an XMLSignature
      Throws:
      NullPointerException - if si is null
      ClassCastException - if any of the objects are not of type XMLObject

    • newReference

      public abstract Reference newReference​(String uri, DigestMethod dm)
      Creates a Reference with the specified URI and digest method.
      Parameters:
      uri - the reference URI (may be null)
      dm - the digest method
      Returns:
      a Reference
      Throws:
      IllegalArgumentException - if uri is not RFC 2396 compliant
      NullPointerException - if dm is null

    • newReference

      public abstract Reference newReference​(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id)
      Creates a Reference with the specified parameters.
      Parameters:
      uri - the reference URI (may be null)
      dm - the digest method
      transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
      type - the reference type, as a URI (may be null)
      id - the reference ID (may be null)
      Returns:
      a Reference
      Throws:
      ClassCastException - if any of the transforms are not of type Transform
      IllegalArgumentException - if uri is not RFC 2396 compliant
      NullPointerException - if dm is null

    • newReference

      public abstract Reference newReference​(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id, byte[] digestValue)
      Creates a Reference with the specified parameters and pre-calculated digest value.

      This method is useful when the digest value of a Reference has been previously computed. See for example, the OASIS-DSS (Digital Signature Services) specification.

      Parameters:
      uri - the reference URI (may be null)
      dm - the digest method
      transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
      type - the reference type, as a URI (may be null)
      id - the reference ID (may be null)
      digestValue - the digest value. The array is cloned to protect against subsequent modification.
      Returns:
      a Reference
      Throws:
      ClassCastException - if any of the transforms are not of type Transform
      IllegalArgumentException - if uri is not RFC 2396 compliant
      NullPointerException - if dm or digestValue is null

    • newReference

      public abstract Reference newReference​(String uri, DigestMethod dm, List<? extends Transform> appliedTransforms, Data result, List<? extends Transform> transforms, String type, String id)
      Creates a Reference with the specified parameters.

      This method is useful when a list of transforms have already been applied to the Reference. See for example, the OASIS-DSS (Digital Signature Services) specification.

      When an XMLSignature containing this reference is generated, the specified transforms (if non-null) are applied to the specified result. The Transforms element of the resulting Reference element is set to the concatenation of the appliedTransforms and transforms.

      Parameters:
      uri - the reference URI (may be null)
      dm - the digest method
      appliedTransforms - a list of Transforms that have already been applied. The list is defensively copied to protect against subsequent modification. The list must contain at least one entry.
      result - the result of processing the sequence of appliedTransforms
      transforms - a list of Transforms that are to be applied when generating the signature. The list is defensively copied to protect against subsequent modification. May be null or empty.
      type - the reference type, as a URI (may be null)
      id - the reference ID (may be null)
      Returns:
      a Reference
      Throws:
      ClassCastException - if any of the transforms (in either list) are not of type Transform
      IllegalArgumentException - if uri is not RFC 2396 compliant or appliedTransforms is empty
      NullPointerException - if dm, appliedTransforms or result is null

    • newSignedInfo

      public abstract SignedInfo newSignedInfo​(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references)
      Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
      Parameters:
      cm - the canonicalization method
      sm - the signature method
      references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
      Returns:
      a SignedInfo
      Throws:
      ClassCastException - if any of the references are not of type Reference
      IllegalArgumentException - if references is empty
      NullPointerException - if any of the parameters are null

    • newSignedInfo

      public abstract SignedInfo newSignedInfo​(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references, String id)
      Creates a SignedInfo with the specified parameters.
      Parameters:
      cm - the canonicalization method
      sm - the signature method
      references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
      id - the id (may be null)
      Returns:
      a SignedInfo
      Throws:
      ClassCastException - if any of the references are not of type Reference
      IllegalArgumentException - if references is empty
      NullPointerException - if cm, sm, or references are null

    • newXMLObject

      public abstract XMLObject newXMLObject​(List<? extends XMLStructure> content, String id, String mimeType, String encoding)
      Creates an XMLObject from the specified parameters.
      Parameters:
      content - a list of XMLStructures. The list is defensively copied to protect against subsequent modification. May be null or empty.
      id - the Id (may be null)
      mimeType - the mime type (may be null)
      encoding - the encoding (may be null)
      Returns:
      an XMLObject
      Throws:
      ClassCastException - if content contains any entries that are not of type XMLStructure

    • newManifest

      public abstract Manifest newManifest​(List<? extends Reference> references)
      Creates a Manifest containing the specified list of References.
      Parameters:
      references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
      Returns:
      a Manifest
      Throws:
      NullPointerException - if references is null
      IllegalArgumentException - if references is empty
      ClassCastException - if references contains any entries that are not of type Reference

    • newManifest

      public abstract Manifest newManifest​(List<? extends Reference> references, String id)
      Creates a Manifest containing the specified list of References and optional id.
      Parameters:
      references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
      id - the id (may be null)
      Returns:
      a Manifest
      Throws:
      NullPointerException - if references is null
      IllegalArgumentException - if references is empty
      ClassCastException - if references contains any entries that are not of type Reference

    • newSignatureProperty

      public abstract SignatureProperty newSignatureProperty​(List<? extends XMLStructure> content, String target, String id)
      Creates a SignatureProperty containing the specified list of XMLStructures, target URI and optional id.
      Parameters:
      content - a list of one or more XMLStructures. The list is defensively copied to protect against subsequent modification.
      target - the target URI of the Signature that this property applies to
      id - the id (may be null)
      Returns:
      a SignatureProperty
      Throws:
      NullPointerException - if content or target is null
      IllegalArgumentException - if content is empty
      ClassCastException - if content contains any entries that are not of type XMLStructure

    • newSignatureProperties

      public abstract SignatureProperties newSignatureProperties​(List<? extends SignatureProperty> properties, String id)
      Creates a SignatureProperties containing the specified list of SignaturePropertys and optional id.
      Parameters:
      properties - a list of one or more SignaturePropertys. The list is defensively copied to protect against subsequent modification.
      id - the id (may be null)
      Returns:
      a SignatureProperties
      Throws:
      NullPointerException - if properties is null
      IllegalArgumentException - if properties is empty
      ClassCastException - if properties contains any entries that are not of type SignatureProperty

    • newDigestMethod

      public abstract DigestMethod newDigestMethod​(String algorithm, DigestMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a DigestMethod for the specified algorithm URI and parameters.
      Parameters:
      algorithm - the URI identifying the digest algorithm
      params - algorithm-specific digest parameters (may be null)
      Returns:
      the DigestMethod
      Throws:
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • newSignatureMethod

      public abstract SignatureMethod newSignatureMethod​(String algorithm, SignatureMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a SignatureMethod for the specified algorithm URI and parameters.
      Parameters:
      algorithm - the URI identifying the signature algorithm
      params - algorithm-specific signature parameters (may be null)
      Returns:
      the SignatureMethod
      Throws:
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • newTransform

      public abstract Transform newTransform​(String algorithm, TransformParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a Transform for the specified algorithm URI and parameters.
      Parameters:
      algorithm - the URI identifying the transform algorithm
      params - algorithm-specific transform parameters (may be null)
      Returns:
      the Transform
      Throws:
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • newTransform

      public abstract Transform newTransform​(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a Transform for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific XMLStructure (ex: DOMStructure). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.
      Parameters:
      algorithm - the URI identifying the transform algorithm
      params - a mechanism-specific XML structure from which to unmarshal the parameters from (may be null if not required or optional)
      Returns:
      the Transform
      Throws:
      ClassCastException - if the type of params is inappropriate for this XMLSignatureFactory
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • newCanonicalizationMethod

      public abstract CanonicalizationMethod newCanonicalizationMethod​(String algorithm, C14NMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
      Parameters:
      algorithm - the URI identifying the canonicalization algorithm
      params - algorithm-specific canonicalization parameters (may be null)
      Returns:
      the CanonicalizationMethod
      Throws:
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • newCanonicalizationMethod

      public abstract CanonicalizationMethod newCanonicalizationMethod​(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
      Creates a CanonicalizationMethod for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific XMLStructure (ex: DOMStructure). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.
      Parameters:
      algorithm - the URI identifying the canonicalization algorithm
      params - a mechanism-specific XML structure from which to unmarshal the parameters from (may be null if not required or optional)
      Returns:
      the CanonicalizationMethod
      Throws:
      ClassCastException - if the type of params is inappropriate for this XMLSignatureFactory
      InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
      NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
      NullPointerException - if algorithm is null

    • getKeyInfoFactory

      public final KeyInfoFactory getKeyInfoFactory()
      Returns a KeyInfoFactory that creates KeyInfo objects. The returned KeyInfoFactory has the same mechanism type and provider as this XMLSignatureFactory.
      Returns:
      a KeyInfoFactory
      Throws:
      NoSuchMechanismException - if a KeyFactory implementation with the same mechanism type and provider is not available

    • unmarshalXMLSignature

      public abstract XMLSignature unmarshalXMLSignature​(XMLValidateContext context) throws MarshalException
      Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.
      Parameters:
      context - a mechanism-specific context from which to unmarshal the signature from
      Returns:
      the XMLSignature
      Throws:
      NullPointerException - if context is null
      ClassCastException - if the type of context is inappropriate for this factory
      MarshalException - if an unrecoverable exception occurs during unmarshalling

    • unmarshalXMLSignature

      public abstract XMLSignature unmarshalXMLSignature​(XMLStructure xmlStructure) throws MarshalException
      Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance. This method is useful if you only want to unmarshal (and not validate) an XMLSignature.
      Parameters:
      xmlStructure - a mechanism-specific XML structure from which to unmarshal the signature from
      Returns:
      the XMLSignature
      Throws:
      NullPointerException - if xmlStructure is null
      ClassCastException - if the type of xmlStructure is inappropriate for this factory
      MarshalException - if an unrecoverable exception occurs during unmarshalling

    • isFeatureSupported

      public abstract boolean isFeatureSupported​(String feature)
      Indicates whether a specified feature is supported.
      Parameters:
      feature - the feature name (as an absolute URI)
      Returns:
      true if the specified feature is supported, false otherwise
      Throws:
      NullPointerException - if feature is null

    • getURIDereferencer

      public abstract URIDereferencer getURIDereferencer()
      Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects.
      Returns:
      a reference to the default URIDereferencer (never null)