public abstract class XMLSignatureFactory extends Object
XMLSignature
objects from scratch or for unmarshalling an XMLSignature
object from a corresponding XML representation. 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 XMLStructure
s of a particular XMLSignature
that is to be generated. The behavior is undefined if XMLStructure
s from different providers or different mechanism types are used together.
Also, the XMLStructure
s that are created by this factory may contain state specific to the XMLSignature
and are not intended to be reusable.
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.
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. 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.
Modifier | Constructor | Description |
---|---|---|
protected |
Default constructor, for invocation by subclasses. |
Modifier and Type | Method | Description |
---|---|---|
static XMLSignatureFactory |
getInstance() |
Returns an XMLSignatureFactory that supports the default XML processing mechanism and representation type ("DOM"). |
static XMLSignatureFactory |
getInstance |
Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM"). |
static XMLSignatureFactory |
getInstance |
Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. |
static XMLSignatureFactory |
getInstance |
Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. |
final KeyInfoFactory |
getKeyInfoFactory() |
Returns a KeyInfoFactory that creates KeyInfo objects. |
final String |
getMechanismType() |
Returns the type of the XML processing mechanism and representation supported by this XMLSignatureFactory (ex: "DOM"). |
final Provider |
getProvider() |
Returns the provider of this XMLSignatureFactory . |
abstract URIDereferencer |
getURIDereferencer() |
Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects. |
abstract boolean |
isFeatureSupported |
Indicates whether a specified feature is supported. |
abstract CanonicalizationMethod |
newCanonicalizationMethod |
Creates a CanonicalizationMethod for the specified algorithm URI and parameters. |
abstract CanonicalizationMethod |
newCanonicalizationMethod |
Creates a CanonicalizationMethod for the specified algorithm URI and parameters. |
abstract DigestMethod |
newDigestMethod |
Creates a DigestMethod for the specified algorithm URI and parameters. |
abstract Manifest |
newManifest |
Creates a Manifest containing the specified list of Reference s. |
abstract Manifest |
newManifest |
Creates a Manifest containing the specified list of Reference s and optional id. |
abstract Reference |
newReference |
Creates a Reference with the specified URI and digest method. |
abstract Reference |
newReference |
Creates a Reference with the specified parameters. |
abstract Reference |
newReference |
Creates a Reference with the specified parameters and pre-calculated digest value. |
abstract Reference |
newReference |
Creates a Reference with the specified parameters. |
abstract SignatureMethod |
newSignatureMethod |
Creates a SignatureMethod for the specified algorithm URI and parameters. |
abstract SignatureProperties |
newSignatureProperties |
Creates a SignatureProperties containing the specified list of SignatureProperty s and optional id. |
abstract SignatureProperty |
newSignatureProperty |
Creates a SignatureProperty containing the specified list of XMLStructure s, target URI and optional id. |
abstract SignedInfo |
newSignedInfo |
Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references. |
abstract SignedInfo |
newSignedInfo |
Creates a SignedInfo with the specified parameters. |
abstract Transform |
newTransform |
Creates a Transform for the specified algorithm URI and parameters. |
abstract Transform |
newTransform |
Creates a Transform for the specified algorithm URI and parameters. |
abstract XMLObject |
newXMLObject |
Creates an XMLObject from the specified parameters. |
abstract XMLSignature |
newXMLSignature |
Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects. |
abstract XMLSignature |
newXMLSignature |
Creates an XMLSignature and initializes it with the specified parameters. |
abstract XMLSignature |
unmarshalXMLSignature |
Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance. |
abstract XMLSignature |
unmarshalXMLSignature |
Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance. |
protected XMLSignatureFactory()
public static XMLSignatureFactory getInstance(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 Provider
s, 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.
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()
.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.XMLSignatureFactory
NullPointerException
- if mechanismType
is null
NoSuchMechanismException
- if no Provider
supports an XMLSignatureFactory
implementation for the specified mechanismpublic static XMLSignatureFactory getInstance(String mechanismType, 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 XMLSignatureFactory
section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.provider
- the Provider
objectXMLSignatureFactory
NullPointerException
- if provider
or mechanismType
is null
NoSuchMechanismException
- if an XMLSignatureFactory
implementation for the specified mechanism is not available from the specified Provider
objectpublic static XMLSignatureFactory getInstance(String mechanismType, String provider) throws 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 XMLSignatureFactory
section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.provider
- the string name of the providerXMLSignatureFactory
NoSuchProviderException
- if the specified provider is not registered in the security provider listNullPointerException
- if provider
or mechanismType
is null
NoSuchMechanismException
- if an XMLSignatureFactory
implementation for the specified mechanism is not available from the specified providerpublic 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 Provider
s, 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 mechanismpublic final String getMechanismType()
XMLSignatureFactory
(ex: "DOM").XMLSignatureFactory
public final Provider getProvider()
XMLSignatureFactory
.XMLSignatureFactory
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 infoki
- the key info (may be null
)XMLSignature
NullPointerException
- if si
is null
public abstract XMLSignature newXMLSignature(SignedInfo si, KeyInfo ki, List<? extends XMLObject> objects, String id, String signatureValueId)
XMLSignature
and initializes it with the specified parameters.si
- the signed infoki
- the key info (may be null
)objects
- a list of XMLObject
s (may be empty or null
)id
- the Id (may be null
)signatureValueId
- the SignatureValue Id (may be null
)XMLSignature
NullPointerException
- if si
is null
ClassCastException
- if any of the objects
are not of type XMLObject
public abstract Reference newReference(String uri, DigestMethod dm)
Reference
with the specified URI and digest method.uri
- the reference URI (may be null
)dm
- the digest methodReference
IllegalArgumentException
- if uri
is not RFC 2396 compliantNullPointerException
- if dm
is null
public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id)
Reference
with the specified parameters.uri
- the reference URI (may be null
)dm
- the digest methodtransforms
- a list of 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
)Reference
ClassCastException
- if any of the transforms
are not of type Transform
IllegalArgumentException
- if uri
is not RFC 2396 compliantNullPointerException
- if dm
is null
public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, 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 methodtransforms
- a list of 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.Reference
ClassCastException
- if any of the transforms
are not of type Transform
IllegalArgumentException
- if uri
is not RFC 2396 compliantNullPointerException
- if dm
or digestValue
is null
public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> appliedTransforms, Data result, List<? extends Transform> transforms, String type, 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 methodappliedTransforms
- a list of 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 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
)Reference
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 emptyNullPointerException
- if dm
, appliedTransforms
or result
is null
public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references)
SignedInfo
with the specified canonicalization and signature methods, and list of one or more references.cm
- the canonicalization methodsm
- the signature methodreferences
- a list of one or more Reference
s. The list is defensively copied to protect against subsequent modification.SignedInfo
ClassCastException
- if any of the references are not of type Reference
IllegalArgumentException
- if references
is emptyNullPointerException
- if any of the parameters are null
public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references, String id)
SignedInfo
with the specified parameters.cm
- the canonicalization methodsm
- the signature methodreferences
- a list of one or more Reference
s. The list is defensively copied to protect against subsequent modification.id
- the id (may be null
)SignedInfo
ClassCastException
- if any of the references are not of type Reference
IllegalArgumentException
- if references
is emptyNullPointerException
- if cm
, sm
, or references
are null
public abstract XMLObject newXMLObject(List<? extends XMLStructure> content, String id, String mimeType, String encoding)
XMLObject
from the specified parameters.content
- a list of 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
)XMLObject
ClassCastException
- if content
contains any entries that are not of type XMLStructure
public abstract Manifest newManifest(List<? extends Reference> references)
Manifest
containing the specified list of Reference
s.references
- a list of one or more Reference
s. The list is defensively copied to protect against subsequent modification.Manifest
NullPointerException
- if references
is null
IllegalArgumentException
- if references
is emptyClassCastException
- if references
contains any entries that are not of type Reference
public abstract Manifest newManifest(List<? extends Reference> references, String id)
Manifest
containing the specified list of Reference
s and optional id.references
- a list of one or more Reference
s. The list is defensively copied to protect against subsequent modification.id
- the id (may be null
)Manifest
NullPointerException
- if references
is null
IllegalArgumentException
- if references
is emptyClassCastException
- if references
contains any entries that are not of type Reference
public abstract SignatureProperty newSignatureProperty(List<? extends XMLStructure> content, String target, String id)
SignatureProperty
containing the specified list of XMLStructure
s, target URI and optional id.content
- a list of one or more XMLStructure
s. The list is defensively copied to protect against subsequent modification.target
- the target URI of the Signature that this property applies toid
- the id (may be null
)SignatureProperty
NullPointerException
- if content
or target
is null
IllegalArgumentException
- if content
is emptyClassCastException
- if content
contains any entries that are not of type XMLStructure
public abstract SignatureProperties newSignatureProperties(List<? extends SignatureProperty> properties, String id)
SignatureProperties
containing the specified list of SignatureProperty
s and optional id.properties
- a list of one or more SignatureProperty
s. The list is defensively copied to protect against subsequent modification.id
- the id (may be null
)SignatureProperties
NullPointerException
- if properties
is null
IllegalArgumentException
- if properties
is emptyClassCastException
- if properties
contains any entries that are not of type SignatureProperty
public abstract DigestMethod newDigestMethod(String algorithm, DigestMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
DigestMethod
for the specified algorithm URI and parameters.algorithm
- the URI identifying the digest algorithmparams
- algorithm-specific digest parameters (may be null
)DigestMethod
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
public abstract SignatureMethod newSignatureMethod(String algorithm, SignatureMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
SignatureMethod
for the specified algorithm URI and parameters.algorithm
- the URI identifying the signature algorithmparams
- algorithm-specific signature parameters (may be null
)SignatureMethod
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
public abstract Transform newTransform(String algorithm, TransformParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
Transform
for the specified algorithm URI and parameters.algorithm
- the URI identifying the transform algorithmparams
- algorithm-specific transform parameters (may be null
)Transform
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
public abstract Transform newTransform(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, 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 algorithmparams
- a mechanism-specific XML structure from which to unmarshal the parameters from (may be null
if not required or optional)Transform
ClassCastException
- if the type of params
is inappropriate for this XMLSignatureFactory
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
CanonicalizationMethod
for the specified algorithm URI and parameters.algorithm
- the URI identifying the canonicalization algorithmparams
- algorithm-specific canonicalization parameters (may be null
)CanonicalizationMethod
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, 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 algorithmparams
- a mechanism-specific XML structure from which to unmarshal the parameters from (may be null
if not required or optional)CanonicalizationMethod
ClassCastException
- if the type of params
is inappropriate for this XMLSignatureFactory
InvalidAlgorithmParameterException
- if the specified parameters are inappropriate for the requested algorithmNoSuchAlgorithmException
- if an implementation of the specified algorithm cannot be foundNullPointerException
- if algorithm
is null
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 availablepublic 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 fromXMLSignature
NullPointerException
- if context
is null
ClassCastException
- if the type of context
is inappropriate for this factoryMarshalException
- if an unrecoverable exception occurs during unmarshallingpublic 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 fromXMLSignature
NullPointerException
- if xmlStructure
is null
ClassCastException
- if the type of xmlStructure
is inappropriate for this factoryMarshalException
- if an unrecoverable exception occurs during unmarshallingpublic abstract boolean isFeatureSupported(String feature)
feature
- the feature name (as an absolute URI)true
if the specified feature is supported, false
otherwiseNullPointerException
- if feature
is null
public abstract URIDereferencer getURIDereferencer()
URIDereferencer
that is used by default to dereference URIs in Reference
objects.URIDereferencer
(never null
)
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.xml.crypto/javax/xml/crypto/dsig/XMLSignatureFactory.html