javax.xml.crypto.dsig
Class XMLSignatureFactory
- java.lang.Object
javax.xml.crypto.dsig.XMLSignatureFactory
- public abstract class XMLSignatureFactory
- extends java.lang.Object
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 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
EachXMLSignature 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 Summary
| Modifier | Constructor and Description |
|---|---|
|
XMLSignatureFactory()
Default constructor, for invocation by subclasses.
|
Method Summary
| Modifier and Type | Method and Description |
|---|---|
|
getInstance()
Returns an
XMLSignatureFactory that supports the
default XML processing mechanism and representation type ("DOM").
|
|
getInstance(java.lang.String mechanismType)
Returns an
XMLSignatureFactory that supports the
specified XML processing mechanism and representation type (ex: "DOM").
|
|
getInstance(java.lang.String mechanismType,java.security.Provider provider)
Returns an
XMLSignatureFactory that supports the
requested XML processing mechanism and representation type (ex: "DOM"),
as supplied by the specified provider.
|
|
getInstance(java.lang.String mechanismType,java.lang.String provider)
Returns an
XMLSignatureFactory that supports the
requested XML processing mechanism and representation type (ex: "DOM"),
as supplied by the specified provider.
|
getKeyInfoFactory()
Returns a
KeyInfoFactory that creates KeyInfo
objects.
|
|
|
getMechanismType()
Returns the type of the XML processing mechanism and representation
supported by this
XMLSignatureFactory (ex: "DOM").
|
|
getProvider()
Returns the provider of this
XMLSignatureFactory.
|
|
getURIDereferencer()
Returns a reference to the
URIDereferencer that is used by
default to dereference URIs in Reference objects.
|
|
isFeatureSupported(java.lang.String feature)
Indicates whether a specified feature is supported.
|
|
newCanonicalizationMethod(java.lang.String algorithm,C14NMethodParameterSpec params)
Creates a
CanonicalizationMethod for the specified
algorithm URI and parameters.
|
|
newCanonicalizationMethod(java.lang.String algorithm,XMLStructure params)
Creates a
CanonicalizationMethod for the specified
algorithm URI and parameters.
|
|
newDigestMethod(java.lang.String algorithm,DigestMethodParameterSpec params)
Creates a
DigestMethod for the specified algorithm URI
and parameters.
|
|
newManifest(java.util.List references)
Creates a
Manifest containing the specified
list of References.
|
|
newManifest(java.util.List references,java.lang.String id)
Creates a
Manifest containing the specified
list of References and optional id.
|
|
newReference(java.lang.String uri,DigestMethod dm)
Creates a
Reference with the specified URI and digest
method.
|
|
newReference(java.lang.String uri,DigestMethod dm,java.util.List appliedTransforms,Data result,java.util.List transforms,java.lang.String type,java.lang.String id)
Creates a
Reference with the specified parameters.
|
|
newReference(java.lang.String uri,DigestMethod dm,java.util.List transforms,java.lang.String type,java.lang.String id)
Creates a
Reference with the specified parameters.
|
|
newReference(java.lang.String uri,DigestMethod dm,java.util.List transforms,java.lang.String type,java.lang.String id,byte[] digestValue)
Creates a
Reference with the specified parameters and
pre-calculated digest value.
|
|
newSignatureMethod(java.lang.String algorithm,SignatureMethodParameterSpec params)
Creates a
SignatureMethod for the specified algorithm URI
and parameters.
|
|
newSignatureProperties(java.util.List properties,java.lang.String id)
Creates a
SignatureProperties containing the specified
list of SignaturePropertys and optional id.
|
|
newSignatureProperty(java.util.List content,java.lang.String target,java.lang.String id)
Creates a
SignatureProperty containing the specified
list of XMLStructures, target URI and optional id.
|
|
newSignedInfo(CanonicalizationMethod cm,SignatureMethod sm,java.util.List references)
Creates a
SignedInfo with the specified canonicalization
and signature methods, and list of one or more references.
|
|
newSignedInfo(CanonicalizationMethod cm,SignatureMethod sm,java.util.List references,java.lang.String id)
Creates a
SignedInfo with the specified parameters.
|
|
newTransform(java.lang.String algorithm,TransformParameterSpec params)
Creates a
Transform for the specified algorithm URI
and parameters.
|
|
newTransform(java.lang.String algorithm,XMLStructure params)
Creates a
Transform for the specified algorithm URI
and parameters.
|
|
newXMLObject(java.util.List content,java.lang.String id,java.lang.String mimeType,java.lang.String encoding)
Creates an
XMLObject from the specified parameters.
|
|
newXMLSignature(SignedInfo si,KeyInfo ki)
Creates an
XMLSignature and initializes it with the contents
of the specified SignedInfo and KeyInfo
objects.
|
|
newXMLSignature(SignedInfo si,KeyInfo ki,java.util.List objects,java.lang.String id,java.lang.String signatureValueId)
Creates an
XMLSignature and initializes it with the
specified parameters.
|
|
unmarshalXMLSignature(XMLStructure xmlStructure)
Unmarshals a new
XMLSignature instance from a
mechanism-specific XMLStructure instance.
|
|
unmarshalXMLSignature(XMLValidateContext context)
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()
Method Detail
getInstance
- public static XMLSignatureFactory getInstance( java.lang.String mechanismType)
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.
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. XMLSignatureFactory java.lang.NullPointerException - if mechanismType is
null NoSuchMechanismException - if no Provider supports an
XMLSignatureFactory implementation for the specified
mechanism ProvidergetInstance
- public static XMLSignatureFactory getInstance( java.lang.String mechanismType,
- java.security.Provider provider)
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.
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 XMLSignatureFactory java.lang.NullPointerException - if provider or
mechanismType is null NoSuchMechanismException - if an XMLSignatureFactory
implementation for the specified mechanism is not available
from the specified Provider object ProvidergetInstance
- public static XMLSignatureFactory getInstance( java.lang.String mechanismType,
- java.lang.String provider)
- throws java.security.NoSuchProviderException
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.
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 XMLSignatureFactory java.security.NoSuchProviderException - if the specified provider is not
registered in the security provider list java.lang.NullPointerException - if provider or
mechanismType is null NoSuchMechanismException - if an XMLSignatureFactory
implementation for the specified mechanism is not
available from the specified provider ProvidergetInstance
- public static XMLSignatureFactory getInstance( )
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.
XMLSignatureFactory NoSuchMechanismException - if no Provider supports an
XMLSignatureFactory implementation for the DOM
mechanism ProvidergetMechanismType
- public final java.lang.String getMechanismType( )
XMLSignatureFactory (ex: "DOM").
XMLSignatureFactory getProvider
- public final java.security.Provider getProvider( )
XMLSignatureFactory.
XMLSignatureFactory newXMLSignature
- public abstract XMLSignature newXMLSignature( SignedInfo si,
- KeyInfo ki)
XMLSignature and initializes it with the contents
of the specified SignedInfo and KeyInfo
objects.
si - the signed info ki - the key info (may be null) XMLSignature java.lang.NullPointerException - if si is null newXMLSignature
- public abstract XMLSignature newXMLSignature( SignedInfo si,
- KeyInfo ki,
- java.util.List objects,
- java.lang.String id,
- java.lang.String signatureValueId)
XMLSignature and initializes it with the
specified parameters.
si - the signed info ki - the key info (may be null) id - the Id (may be null) signatureValueId - the SignatureValue Id (may be null) XMLSignature java.lang.NullPointerException - if si is null java.lang.ClassCastException - if any of the objects are not of
type XMLObject newReference
- public abstract Reference newReference( java.lang.String uri,
- DigestMethod dm)
Reference with the specified URI and digest
method.
uri - the reference URI (may be null) dm - the digest method Reference java.lang.IllegalArgumentException - if uri is not RFC 2396
compliant java.lang.NullPointerException - if dm is null newReference
- public abstract Reference newReference( java.lang.String uri,
- DigestMethod dm,
- java.util.List transforms,
- java.lang.String type,
- java.lang.String id)
Reference with the specified 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) Reference java.lang.ClassCastException - if any of the transforms are
not of type Transform java.lang.IllegalArgumentException - if uri is not RFC 2396
compliant java.lang.NullPointerException - if dm is null newReference
- public abstract Reference newReference( java.lang.String uri,
- DigestMethod dm,
- java.util.List transforms,
- java.lang.String type,
- java.lang.String id,
- byte[] digestValue)
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.
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. Reference java.lang.ClassCastException - if any of the transforms are
not of type Transform java.lang.IllegalArgumentException - if uri is not RFC 2396
compliant java.lang.NullPointerException - if dm or
digestValue is null newReference
- public abstract Reference newReference( java.lang.String uri,
- DigestMethod dm,
- java.util.List appliedTransforms,
- Data result,
- java.util.List transforms,
- java.lang.String type,
- java.lang.String id)
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.
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) Reference java.lang.ClassCastException - if any of the transforms (in either list)
are not of type Transform java.lang.IllegalArgumentException - if uri is not RFC 2396
compliant or appliedTransforms is empty java.lang.NullPointerException - if dm,
appliedTransforms or result is
null newSignedInfo
- public abstract SignedInfo newSignedInfo( CanonicalizationMethod cm,
- SignatureMethod sm,
- java.util.List references)
SignedInfo with the specified canonicalization
and signature methods, and list of one or more references.
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. SignedInfo java.lang.ClassCastException - if any of the references are not of
type Reference java.lang.IllegalArgumentException - if references is empty java.lang.NullPointerException - if any of the parameters
are null newSignedInfo
- public abstract SignedInfo newSignedInfo( CanonicalizationMethod cm,
- SignatureMethod sm,
- java.util.List references,
- java.lang.String id)
SignedInfo with the specified 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) SignedInfo java.lang.ClassCastException - if any of the references are not of
type Reference java.lang.IllegalArgumentException - if references is empty java.lang.NullPointerException - if cm, sm, or
references are null newXMLObject
- public abstract XMLObject newXMLObject( java.util.List content,
- java.lang.String id,
- java.lang.String mimeType,
- java.lang.String encoding)
XMLObject from the specified 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) XMLObject newManifest
- public abstract Manifest newManifest( java.util.List references)
Manifest containing the specified
list of References.
references - a list of one or more References. The list
is defensively copied to protect against subsequent modification. Manifest java.lang.NullPointerException - if references is
null java.lang.IllegalArgumentException - if references is empty newManifest
- public abstract Manifest newManifest( java.util.List references,
- java.lang.String id)
Manifest containing the specified
list of References and optional id.
references - a list of one or more References. The list
is defensively copied to protect against subsequent modification. id - the id (may be null) Manifest java.lang.NullPointerException - if references is
null java.lang.IllegalArgumentException - if references is empty newSignatureProperty
- public abstract SignatureProperty newSignatureProperty( java.util.List content,
- java.lang.String target,
- java.lang.String id)
SignatureProperty containing the specified
list of XMLStructures, target URI and optional id.
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) SignatureProperty java.lang.NullPointerException - if content or
target is null java.lang.IllegalArgumentException - if content is empty newSignatureProperties
- public abstract SignatureProperties newSignatureProperties( java.util.List properties,
- java.lang.String id)
SignatureProperties containing the specified
list of SignaturePropertys and optional id.
properties - a list of one or more SignaturePropertys.
The list is defensively copied to protect against subsequent
modification. id - the id (may be null) SignatureProperties java.lang.NullPointerException - if properties
is null java.lang.IllegalArgumentException - if properties is empty java.lang.ClassCastException - if properties contains any
entries that are not of type SignaturePropertynewDigestMethod
- public abstract DigestMethod newDigestMethod( java.lang.String algorithm,
- DigestMethodParameterSpec params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
DigestMethod for the specified algorithm URI
and parameters.
algorithm - the URI identifying the digest algorithm params - algorithm-specific digest parameters (may be
null) DigestMethod java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null newSignatureMethod
- public abstract SignatureMethod newSignatureMethod( java.lang.String algorithm,
- SignatureMethodParameterSpec params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
SignatureMethod for the specified algorithm URI
and parameters.
algorithm - the URI identifying the signature algorithm params - algorithm-specific signature parameters (may be
null) SignatureMethod java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null newTransform
- public abstract Transform newTransform( java.lang.String algorithm,
- TransformParameterSpec params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
Transform for the specified algorithm URI
and parameters.
algorithm - the URI identifying the transform algorithm params - algorithm-specific transform parameters (may be
null) Transform java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null newTransform
- public abstract Transform newTransform( java.lang.String algorithm,
- XMLStructure params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
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.
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) Transform java.lang.ClassCastException - if the type of params is
inappropriate for this XMLSignatureFactory java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null newCanonicalizationMethod
- public abstract CanonicalizationMethod newCanonicalizationMethod( java.lang.String algorithm,
- C14NMethodParameterSpec params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
CanonicalizationMethod for the specified
algorithm URI and parameters.
algorithm - the URI identifying the canonicalization algorithm params - algorithm-specific canonicalization parameters (may be
null) CanonicalizationMethod java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null newCanonicalizationMethod
- public abstract CanonicalizationMethod newCanonicalizationMethod( java.lang.String algorithm,
- XMLStructure params)
- throws java.security.NoSuchAlgorithmException
- java.security.InvalidAlgorithmParameterException
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.
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) CanonicalizationMethod java.lang.ClassCastException - if the type of params is
inappropriate for this XMLSignatureFactory java.security.InvalidAlgorithmParameterException - if the specified parameters
are inappropriate for the requested algorithm java.security.NoSuchAlgorithmException - if an implementation of the
specified algorithm cannot be found java.lang.NullPointerException - if algorithm is
null getKeyInfoFactory
- public final KeyInfoFactory getKeyInfoFactory( )
KeyInfoFactory that creates KeyInfo
objects. The returned KeyInfoFactory has the same
mechanism type and provider as this XMLSignatureFactory.
KeyInfoFactory NoSuchMechanismException - if a KeyFactory
implementation with the same mechanism type and provider
is not available unmarshalXMLSignature
- public abstract XMLSignature unmarshalXMLSignature( XMLValidateContext context)
- throws MarshalException
XMLSignature instance from a
mechanism-specific XMLValidateContext instance.
context - a mechanism-specific context from which to unmarshal the
signature from XMLSignature java.lang.NullPointerException - if context is
null java.lang.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
XMLSignature instance from a
mechanism-specific XMLStructure instance.
This method is useful if you only want to unmarshal (and not
validate) an XMLSignature.
xmlStructure - a mechanism-specific XML structure from which to
unmarshal the signature from XMLSignature java.lang.NullPointerException - if xmlStructure is
null java.lang.ClassCastException - if the type of xmlStructure is
inappropriate for this factory MarshalException - if an unrecoverable exception occurs
during unmarshalling isFeatureSupported
- public abstract boolean isFeatureSupported( java.lang.String feature)
feature - the feature name (as an absolute URI) true if the specified feature is supported,
false otherwise java.lang.NullPointerException - if feature is null getURIDereferencer
- public abstract URIDereferencer getURIDereferencer( )
URIDereferencer that is used by
default to dereference URIs in Reference objects.
URIDereferencer (never
null)