This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.


javax.xml.crypto.dsig
class XMLSignatureFactory

java.lang.Object extended by javax.xml.crypto.dsig.XMLSignatureFactory

Most common way to construct:

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

Based on 164 examples


public abstract class XMLSignatureFactory
extends Object

A factory for creating {@link 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 {@link #getInstance 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 section of the API overview. See the Service Providers section of the API overview for a list of standard mechanism types.

XMLSignatureFactory implementations are registered and loaded using the {@link java.security.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 {@link Reference} instance may be created by invoking one of the {@link #newReference newReference} methods.

Unmarshalling XMLSignatures from XML

Alternatively, an XMLSignature may be created from an existing XML representation by invoking the {@link #unmarshalXMLSignature unmarshalXMLSignature} method and passing it a mechanism-specific {@link 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 {@link 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 {@link XMLSignature#sign sign} method of the {@link XMLSignature} object and passing it a mechanism-specific {@link XMLSignContext} object containing the signing key and marshalling parameters (see {@link 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.


Constructor Summary
protected

          Default constructor, for invocation by subclasses.
 
Method Summary
static XMLSignatureFactory

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

          Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
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.
static XMLSignatureFactory
getInstance(String mechanismType, String provider)

          Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
 KeyInfoFactory

          Returns a KeyInfoFactory that creates KeyInfo objects.
 String

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

          Returns the provider of this XMLSignatureFactory.
abstract URIDereferencer

          Returns a reference to the URIDereferencer that is used by default to dereference URIs in javax.xml.crypto.dsig.Reference objects.
abstract boolean

          Indicates whether a specified feature is supported.
abstract CanonicalizationMethod

          Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract CanonicalizationMethod

          Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract DigestMethod

          Creates a DigestMethod for the specified algorithm URI and parameters.
abstract Manifest
newManifest(List references)

          Creates a Manifest containing the specified list of javax.xml.crypto.dsig.References.
abstract Manifest
newManifest(List references, String id)

          Creates a Manifest containing the specified list of javax.xml.crypto.dsig.References and optional id.
abstract Reference

          Creates a Reference with the specified URI and digest method.
abstract Reference
newReference(String uri, DigestMethod dm, List appliedTransforms, Data result, List transforms, String type, String id)

          Creates a Reference with the specified parameters.
abstract Reference
newReference(String uri, DigestMethod dm, List transforms, String type, String id)

          Creates a Reference with the specified parameters.
abstract Reference
newReference(String uri, DigestMethod dm, List transforms, String type, String id, byte[] digestValue)

          Creates a Reference with the specified parameters and pre-calculated digest value.
abstract SignatureMethod

          Creates a SignatureMethod for the specified algorithm URI and parameters.
abstract SignatureProperties

          Creates a SignatureProperties containing the specified list of javax.xml.crypto.dsig.SignaturePropertys and optional id.
abstract SignatureProperty
newSignatureProperty(List content, String target, String id)

          Creates a SignatureProperty containing the specified list of javax.xml.crypto.XMLStructures, target URI and optional id.
abstract SignedInfo

          Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
abstract SignedInfo

          Creates a SignedInfo with the specified parameters.
abstract Transform

          Creates a Transform for the specified algorithm URI and parameters.
abstract Transform
newTransform(String algorithm, XMLStructure params)

          Creates a Transform for the specified algorithm URI and parameters.
abstract XMLObject
newXMLObject(List content, String id, String mimeType, String encoding)

          Creates an XMLObject from the specified parameters.
abstract XMLSignature

          Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
abstract XMLSignature
newXMLSignature(SignedInfo si, KeyInfo ki, List objects, String id, String signatureValueId)

          Creates an XMLSignature and initializes it with the specified parameters.
abstract XMLSignature

          Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance.
abstract XMLSignature

          Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLSignatureFactory

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

Method Detail

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 {@link Security#getProviders() Security.getProviders()} method.

Returns:
a new XMLSignatureFactory

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 {@link Security#getProviders() Security.getProviders()} method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
Returns:
a new XMLSignatureFactory

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 Service Providers section of the API overview for a list of standard mechanism types.
provider - the Provider object
Returns:
a new XMLSignatureFactory

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 {@link Security#getProviders() Security.getProviders()} method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview 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

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

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

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in {@link Reference} objects.

Returns:
a reference to the default URIDereferencer (never null)

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

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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

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: {@link 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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

newManifest

public abstract Manifest newManifest(List references)
Creates a Manifest containing the specified list of {@link Reference}s.

Parameters:
references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
Returns:
a Manifest

newManifest

public abstract Manifest newManifest(List references,
                                     String id)
Creates a Manifest containing the specified list of {@link Reference}s 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

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

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List appliedTransforms,
                                       Data result,
                                       List 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 {@link Transform}s 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 {@link Transform}s 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

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List 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 {@link Transform}s. 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

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List 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 {@link Transform}s. 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

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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

newSignatureProperties

public abstract SignatureProperties newSignatureProperties(List properties,
                                                           String id)
Creates a SignatureProperties containing the specified list of {@link SignatureProperty}s 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

newSignatureProperty

public abstract SignatureProperty newSignatureProperty(List content,
                                                       String target,
                                                       String id)
Creates a SignatureProperty containing the specified list of {@link XMLStructure}s, 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

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List 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 {@link Reference}s. The list is defensively copied to protect against subsequent modification.
Returns:
a SignedInfo

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List 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 {@link Reference}s. The list is defensively copied to protect against subsequent modification.
id - the id (may be null)
Returns:
a SignedInfo

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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

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: {@link 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:
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm

newXMLObject

public abstract XMLObject newXMLObject(List content,
                                       String id,
                                       String mimeType,
                                       String encoding)
Creates an XMLObject from the specified parameters.

Parameters:
content - a list of {@link XMLStructure}s. 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

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

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki,
                                             List 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 {@link XMLObject}s (may be empty or null)
id - the Id (may be null)
signatureValueId - the SignatureValue Id (may be null)
Returns:
an XMLSignature

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:
MarshalException - if an unrecoverable exception occurs during unmarshalling

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:
MarshalException - if an unrecoverable exception occurs during unmarshalling


This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention, which is derived from the offical documentation that contains this copyright notice:
Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
The official Sun™ documentation can be found here at http://java.sun.com/javase/6/docs/api/.