Module java.xml.crypto

Package javax.xml.crypto.dsig

Classes for generating and validating XML digital signatures. This package includes classes that represent the core elements defined in the W3C XML digital signature specification: XMLSignature, SignedInfo, CanonicalizationMethod, SignatureMethod, Reference, DigestMethod, XMLObject, Manifest, SignatureProperties, and SignatureProperty. KeyInfo types are defined in the javax.xml.crypto.dsig.keyinfo subpackage. XMLSignatureFactory is an abstract factory that creates XMLSignature objects from scratch or from a pre-existing XML representation, such as a DOM node. TransformService is a service provider interface for creating and plugging in implementations of transform and canonicalization algorithms.

Of primary significance in this package is the XMLSignature class, which allows you to sign and validate an XML digital signature.

Service Providers

A service provider is a concrete implementation of the abstract XMLSignatureFactory and KeyInfoFactory classes and is responsible for creating objects and algorithms that parse, generate and validate XML Signatures and KeyInfo structures. A concrete implementation of XMLSignatureFactory MUST provide support for each of the REQUIRED algorithms as specified by the W3C recommendation for XML Signatures. It MAY support other algorithms as defined by the W3C recommendation or other specifications.

The API leverages the JCA provider model (see the Provider class) for registering and loading XMLSignatureFactory and KeyInfoFactory implementations.

Each concrete XMLSignatureFactory or KeyInfoFactory implementation supports a specific XML mechanism type that identifies the XML processing mechanism that an implementation uses internally to parse and generate XML signature and KeyInfo structures.

A service provider implementation SHOULD use underlying JCA engine classes, such as Signature and MessageDigest to perform cryptographic operations.

In addition to the XMLSignatureFactory and KeyInfoFactory classes, the API supports a service provider interface for transform and canonicalization algorithms. The TransformService class allows you to develop and plug in an implementation of a specific transform or canonicalization algorithm for a particular XML mechanism type. The TransformService class uses the standard JCA provider model for registering and loading implementations. Each service provider implementation SHOULD use the TransformService class to find a provider that supports transform and canonicalization algorithms in XML Signatures that it is generating or validating.

DOM Mechanism Requirements

The following requirements MUST be abided by when implementing a DOM-based XMLSignatureFactory, KeyInfoFactory or TransformService in order to minimize interoperability problems:
  1. The unmarshalXMLSignature method of XMLSignatureFactory MUST support DOMValidateContext types. If the type is DOMValidateContext, it SHOULD contain an Element of type Signature. Additionally, the unmarshalXMLSignature method MAY populate the Id/Element mappings of the passed-in DOMValidateContext.
  2. The sign method of XMLSignatures produced by XMLSignatureFactory MUST support DOMSignContext types and the validate method MUST support DOMValidateContext types. This requirement also applies to the validate method of SignatureValue and the validate method of Reference.
  3. The implementation MUST support DOMStructures as the mechanism for the application to specify extensible content (any elements or mixed content).
  4. If the dereference method of user-specified URIDereferencers returns NodeSetData objects, the iterator method MUST return an iteration over objects of type org.w3c.dom.Node.
  5. URIReference objects passed to the dereference method of user-specified URIDereferencers MUST be of type DOMURIReference and XMLCryptoContext objects MUST implement DOMCryptoContext.
  6. The previous 2 requirements also apply to URIDereferencers returned by the getURIDereferencer method of XMLSignatureFactory and KeyInfoFactory.
  7. The unmarshalKeyInfo method of KeyInfoFactory MUST support DOMStructure types. If the type is DOMStructure, it SHOULD contain an Element of type KeyInfo.
  8. The transform method of Transform MUST support DOMCryptoContext context parameter types.
  9. The newtransform and newCanonicalizationMethod methods of XMLSignatureFactory MUST support DOMStructure parameter types.
  10. The init, and marshalParams methods of TransformService MUST support DOMStructure and DOMCryptoContext types.
  11. The unmarshalXMLSignature method of XMLSignatureFactory MUST support DOMStructure types. If the type is DOMStructure, it SHOULD contain an Element of type Signature.
  12. The marshal method of KeyInfo MUST support DOMStructure and DOMCryptoContext parameter types.

Note that a DOM implementation MAY internally use other XML parsing APIs other than DOM as long as it doesn't affect interoperability. For example, a DOM implementation of XMLSignatureFactory might use a SAX parser internally to canonicalize data.

Package Specification

Since:
1.6