Java^TM XML Digital Signature API Specification (JSR 105)

Java^TM XML Digital Signature API Specification (JSR 105)

See:
Description

JSR 105 Packages

javax.xml.crypto	Common classes for XML cryptography.
javax.xml.crypto.dom	DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig	Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom	DOM-specific classes for the javax.xml.crypto.dsig package.
javax.xml.crypto.dsig.keyinfo	Classes for parsing and processing KeyInfo elements and structures.
javax.xml.crypto.dsig.spec	Parameter classes for XML digital signatures.

Java^TM XML Digital Signature API Specification (JSR 105)

This is the Proposed Final Draft of the JSR 105 API.

Please send all comments to: jsr-105-comments@sun.com. We appreciate your comments and the time taken to review the API.

Table of Contents

• Introduction
• Acknowledgements
• Requirements
• API Dependencies
• Non-Goals
• Package Overview
• Service Providers
• DOM Mechanism Requirements
• Open API Issues
• Closed API Issues
• API Changes
• Examples

Introduction

This document describes the Java^TM XML Digital Signature API Specification (JSR 105). The purpose of this JSR is to define a standard Java^TM API for generating and validating XML signatures.

When this specification is final, there will be a Reference Implementation which will demonstrate the capabilities of this API and will provide an operational definition of this specification. A Technology Compatibility Kit (TCK) will also be available that will verify whether an implementation of the specification is compliant. These are required as per the Java Community Process ^SM 2.1.

The JSR 105 API is intended to target the following two types of users:

• Java^TM programmers who want to use the JSR 105 API to generate and validate XML signatures.
• Java^TM programmers who want to create a concrete implementation of the JSR 105 API and register it as a cryptographic service of a JCA provider.

Acknowledgements

The JSR 105 Expert Group:

• Nicolas Catania, Hewlett-Packard
• Donald E. Eastlake 3rd, Motorola
• Christian Geuer-Pollmann, Apache Software Foundation
• Hans Granqvist, VeriSign
• Kazuyuki Harada, Fujitsu
• Anthony Ho, DSTC
• Merlin Hughes, Baltimore Technologies
• Joyce Leung, IBM
• Gregor Karlinger, IAIK
• Serge Mister, Entrust Technologies
• Takuya Mori, NEC Corporation
• Sean Mullan, Sun Microsystems (co-specification lead)
• Anthony Nadalin, IBM (co-specification lead)
• Valerie Peng, Sun Microsystems
• Erwin van der Koogh, Apache Software Foundation
• Chris Yeung, XML Asia

Requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

• W3C Recommendation, XML-Signature Syntax and Processing.
  • The API MUST allow a programmer to generate and validate XML Signatures such that all of the SHOULD and MUST requirements specified by the W3C recommendation can be satisfied.
  • The API MUST allow an implementation of the API to be created such that all of the SHOULD and MUST requirements specified by the W3C recommendation can be satisfied.
• An implementation SHOULD support the W3C Recommendation, XML-Signature XPath Filter Transform 2.0.
• An implementation SHOULD support the W3C Recommendation, Exclusive XML Canonicalization Version 1.0.
• DOM-independent API. The API MUST NOT have dependencies on a specific XML representation, such as DOM. It MUST be possible to create implementations of the API for different XML processing and mechanism representations, such as DOM, JDOM or dom4j.
• Extensible, provider-based API. It MUST be possible for a third-party to create and plug in an implementation responsible for managing and creating cryptographic and transform algorithms, dereferencing URIs, and marshalling objects to/from XML.
• Support for a default XML mechanism type: DOM. An implementation MUST minimally support the default mechanism type: DOM. This ensures that all implementations of JSR 105 are guaranteed a minimal level of functionality. Implementations MAY support other mechanism types.
• Interoperability for the default XML mechanism type: DOM. The API SHOULD ensure that applications using a DOM implementation are portable and interoperable.

API Dependencies

• J2SE (JDK) 1.2 or higher
• W3C DOM Level 2 API. This dependency is required by classes of the javax.xml.crypto.dom and javax.xml.crypto.dsig.dom packages.

Non-Goals

• Support for non-DOM implementations. While the API SHOULD allow non-DOM implementations to be created, it is beyond the scope of the first version to ensure interoperability between implementations other than DOM. Additional standard service provider types MAY be added in the future and necessary API enhancements MAY be considered for a maintenance revision of JSR 105.
• Support for a higher-level API. We expect that programmers MAY design high-level APIs which will be built on the JSR 105 API to hide low-level details, address common use-cases or apply profiling constraints. However, it is beyond the scope of the first version to support these requirements. A high-level API MAY be considered for a maintenance release of JSR 105.
• Support for user-pluggable algorithms: Allowing developers to plug in their own implementations of XML Signature algorithms without requiring them to create a complete JSR 105 implementation seems like a worthy goal but SHALL NOT be REQUIRED for this release of JSR 105. A solution we are investigating for a subsequent release of J2SE is to enhance the underlying JCA/JCE to add better support for registering, parsing and processing XML security algorithms, parameters, and key information.

Package Overview

The JSR 105 API consists of 6 packages:

• javax.xml.crypto
• javax.xml.crypto.dom
• javax.xml.crypto.dsig
• javax.xml.crypto.dsig.dom
• javax.xml.crypto.dsig.keyinfo
• javax.xml.crypto.dsig.spec

The javax.xml.crypto package contains common classes that are used to perform XML cryptographic operations, such as generating an XML signature or encrypting XML data. Two notable classes in this package are the KeySelector class, the purpose of which is to allow developers to supply implementations which locate and optionally validate keys using the information contained in a KeyInfo object, and the URIDereferencer class which allows developers to create and specify their own URI dereferencing implementations.

The javax.xml.crypto.dsig package includes interfaces that represent the core elements defined in the W3C XML digital signature specification. Of primary significance is the XMLSignature class, which allows you to sign and validate an XML digital signature. Most of the XML signature structures or elements are represented by a corresponding interface (except for the KeyInfo structures, which are included in their own package, and discussed in the next paragraph). These interfaces include: SignedInfo, CanonicalizationMethod, SignatureMethod, Reference, Transform, DigestMethod, XMLObject, Manifest, SignatureProperty, and SignatureProperties. The XMLSignatureFactory class is an abstract factory that is used to create objects that implement these interfaces.

The javax.xml.crypto.dsig.keyinfo package contains interfaces that represent most of the KeyInfo structures defined in the W3C XML digital signature recommendation, including KeyInfo, KeyName, KeyValue, X509Data, X509IssuerSerial, RetrievalMethod, and PGPData. The KeyInfoFactory class is an abstract factory that is used to create objects that implement these interfaces.

The javax.xml.crypto.dsig.spec package contains interfaces and classes representing input parameters for the digest, signature, transform, or canonicalization algorithms used in the processing of XML signatures.

Finally, the javax.xml.crypto.dom and javax.xml.crypto.dsig.dom packages contains DOM-specific classes for the javax.xml.crypto and javax.xml.crypto.dsig packages, respectively. Only developers and users who are creating or using a DOM-based XMLSignatureFactory or KeyInfoFactory implementation should need to make direct use of these packages.

Service Providers

A JSR 105 cryptographic service 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.

JSR 105 leverages the JCA provider model 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. This JSR supports one standard type: DOM. Support for new standard types (such as JDOM) MAY be added in the future.

A JSR 105 implementation SHOULD use underlying JCA engine classes, such as java.security.Signature and java.security.MessageDigest to perform cryptographic operations.

DOM Mechanism Requirements

The following requirements MUST be abided by when implementing a DOM-based XMLSignatureFactory or KeyInfoFactory, in order to minimize interoperability problems:

• 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 DOMIdMap of the passed-in DOMValidateContext.
• 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.
• The implementation MUST support DOMStructures as the mechanism for the application to specify extensible content (any elements or mixed content).
• If the dereference method of user-specified URIDereferencers returns NodeSetData objects, they MUST be of type DOMNodeSetData.
• URIReference objects passed to the dereference method of user-specified URIDereferencers MUST be of type DOMURIReference and XMLCryptoContext objects MUST implement DOMIdMap.
• The previous 2 requirements also apply to URIDereferencers returned by the getURIDereferencer method of XMLSignatureFactory and KeyInfoFactory.

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.

Open API Issues

The following is a list of open API issues.

1. ID attribute registration of external XML document references is not supported.
   Consider the following reference:

   
     <Reference URI="document.xml">
       <Transforms>
         <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
           <XPath>id("foo")</XPath>
         </Transform>
       </Transforms>
     </Reference>
         

   Dereferencing the external document results in an octet stream which is subsequently converted to a NodeSet by the JSR 105 implementation. But the API does not provide a mechanism for registering ID attributes of external documents and therefore the XPath Transform implementation may be unable to identify the "foo" ID.
   Status: will resolve before final draft

Closed API Issues

The following is a list of closed API issues and their resolutions.

1. Move generic (not XML-Signature specific) XML security classes such as XMLStructure, AlgorithmMethod to a new package (ex: javax.xml.security) for use by other XML security JSRs such as JSR 106, JSR 104, & JSR 183.
   Resolution: Fixed in v0.8 by adding new common package javax.xml.crypto and moving existing packages to the new hierarchy.
2. Use java.net.URI instead of String to represent URIs in API.
   Resolution: Use String to avoid API dependencies on java.net.URI class introduced in J2SE 1.4 (see API dependency requirements).
3. Add a mechanism-specific ID registration mechanism to allow same-document references to be resolved by ID.
   Resolution: Added new interface DOMIdMap to register ID/Element pairs in v0.8.
4. Specify behavior in XMLCryptoContext.setURIDereferencer method for overriding provider's default URIDereferencer implementation.
   Resolution: in v0.8, clarified that user-specified URIDereferencer overrides default. Added methods to XMLSignatureFactory and KeyInfoFactory that return a reference to the default URIDereferencer.
5. Add support for signing "signature templates" (pre-generated Signature elements with empty DigestValue and SignatureValue elements).
   Resolution: no changes necessary - this can be supported by unmarshalling a XMLSignature and re-signing it. If new key info needs to be inserted, it can be specified by constructing a new XMLSignature with the signed info & embedded objects of an unmarshaled signature, along with the new key info structure.
6. Allow user to add/delete KeyInfo types or XMLObjects of an existing XMLSignature.
   Resolution: no changes were made. If the application needs to do this, it should do it in a mechanism-specific manner (ex: by modifying the DOM document).
7. Add classes for DOMKeyValue & RSAKeyValue so that keys of these types can be unmarshalled and processed by a KeySelector that supports resolving RetrievalMethod structures.
   Resolution: this might be better supported by enhancing the existing java.security.KeyFactory class to decode XML key values.
8. Add an XMLSignContext property that allows the user to specify a source of randomness for signing (i.e, a SecureRandom object). Resolution: no changes made
9. Make DOMNodeSetData a class to make it easier to implement DOM-based URIDereferencers. Resolution: fixed in v0.10
10. Add purposes for key agreement to the KeySelector.Purpose class. Resolution: no changes made

Programming Examples

Examples 1-3 below demonstrate how to generate different types of simple XML Digital Signature using the JSR 105 API. Example 1 describes how to generate a detached signature using the DSA signature algorithm. Example 2 describes how to generate an enveloped signature. Example 3 decribes how to generate an enveloping signature. Example 4 describes how to validate an XML Signature. Example 5 is a sample implementation of a KeySelector that finds a trusted key from X.509 content contained in X509Data KeyInfo types. Example 6 demonstrates how to construct, sign and validate a SOAP message using the SAAJ and JSR 105 APIs.

1. Generating a detached XML Digital Signature
2. Generating an enveloped XML Digital Signature.
3. Generating an enveloping XML Digital Signature
4. Validating an XML Digital Signature
5. X.509 KeySelector implementation
6. Signed SOAP message