Home » openjdk-7 » javax » xml » crypto » dsig » [javadoc | source]
javax.xml.crypto.dsig
abstract public class: XMLSignatureFactory [javadoc | source]
java.lang.Object
   javax.xml.crypto.dsig.XMLSignatureFactory
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 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 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 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.

Constructor:
 protected XMLSignatureFactory() 
Method from javax.xml.crypto.dsig.XMLSignatureFactory Summary:
getInstance,   getInstance,   getInstance,   getInstance,   getKeyInfoFactory,   getMechanismType,   getProvider,   getURIDereferencer,   isFeatureSupported,   newCanonicalizationMethod,   newCanonicalizationMethod,   newDigestMethod,   newManifest,   newManifest,   newReference,   newReference,   newReference,   newReference,   newSignatureMethod,   newSignatureProperties,   newSignatureProperty,   newSignedInfo,   newSignedInfo,   newTransform,   newTransform,   newXMLObject,   newXMLSignature,   newXMLSignature,   unmarshalXMLSignature,   unmarshalXMLSignature
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from javax.xml.crypto.dsig.XMLSignatureFactory Detail:
 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.

 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.

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

 public final KeyInfoFactory getKeyInfoFactory() 
    Returns a KeyInfoFactory that creates KeyInfo objects. The returned KeyInfoFactory has the same mechanism type and provider as this XMLSignatureFactory.
 public final String getMechanismType() 
    Returns the type of the XML processing mechanism and representation supported by this XMLSignatureFactory (ex: "DOM").
 public final Provider getProvider() 
    Returns the provider of this XMLSignatureFactory.
 abstract public URIDereferencer getURIDereferencer()
    Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects.
 abstract public boolean isFeatureSupported(String feature)
    Indicates whether a specified feature is supported.
 abstract public CanonicalizationMethod newCanonicalizationMethod(String algorithm,
    C14NMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
 abstract public 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.
 abstract public DigestMethod newDigestMethod(String algorithm,
    DigestMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a DigestMethod for the specified algorithm URI and parameters.
 abstract public Manifest newManifest(List references)
    Creates a Manifest containing the specified list of Reference s.
 abstract public Manifest newManifest(List references,
    String id)
    Creates a Manifest containing the specified list of Reference s and optional id.
 abstract public Reference newReference(String uri,
    DigestMethod dm)
    Creates a Reference with the specified URI and digest method.
 abstract public Reference newReference(String uri,
    DigestMethod dm,
    List transforms,
    String type,
    String id)
    Creates a Reference with the specified parameters.
 abstract public 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.

 abstract public 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.

 abstract public SignatureMethod newSignatureMethod(String algorithm,
    SignatureMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a SignatureMethod for the specified algorithm URI and parameters.
 abstract public SignatureProperties newSignatureProperties(List properties,
    String id)
    Creates a SignatureProperties containing the specified list of SignatureProperty s and optional id.
 abstract public SignatureProperty newSignatureProperty(List content,
    String target,
    String id)
    Creates a SignatureProperty containing the specified list of XMLStructure s, target URI and optional id.
 abstract public 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.
 abstract public SignedInfo newSignedInfo(CanonicalizationMethod cm,
    SignatureMethod sm,
    List references,
    String id)
    Creates a SignedInfo with the specified parameters.
 abstract public Transform newTransform(String algorithm,
    TransformParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a Transform for the specified algorithm URI and parameters.
 abstract public 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.
 abstract public XMLObject newXMLObject(List content,
    String id,
    String mimeType,
    String encoding)
    Creates an XMLObject from the specified parameters.
 abstract public XMLSignature newXMLSignature(SignedInfo si,
    KeyInfo ki)
    Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
 abstract public XMLSignature newXMLSignature(SignedInfo si,
    KeyInfo ki,
    List objects,
    String id,
    String signatureValueId)
    Creates an XMLSignature and initializes it with the specified parameters.
 abstract public XMLSignature unmarshalXMLSignature(XMLValidateContext context) throws MarshalException
    Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.
 abstract public 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.