Copyright information
Note: Before using this information and the product it supports, read the general information under
Notices.
© Copyright Oracle and/or its affiliates 1998, 2011. All rights reserved.
© Copyright International Business Machines Corporation, 1998, 2011. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Acknowledgements
The JSR 106 Expert Group:
- Nicolas Catania, Hewlett-Packard
- Fred Chen, Netegrity Inc.
- Peter Dapkus, BEA Systems
- Kevin Driver, IBM
- Donald E. Eastlake 3rd, Motorola
- Merlin Hughes, Baltimore Technologies
- Mario Lamberger, IAIK
- Berin Lautenbach, Apache
- Eamonn Maher, Baltimore Technologies
- Serge Mister, Entrust Technologies
- Sean Mullan, Sun Microsystems
- Anthony Nadalin, IBM (specification lead)
- Samir Nigam, Sybase
- Ramana Turlapati, Oracle
- 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 Encryption Syntax and Processing
-
- The API MUST allow a programmer to encrypt and decrypt XML 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.
- 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 106 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.
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 106.
- Support for a higher-level API
- We expect that programmers MAY design high-level APIs which will be built on the JSR 106 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 106.
- Support for user-pluggable algorithms
- Allowing developers to plug in their own implementations of XML Encryption algorithms without requiring them to create a complete JSR 106 implementation seems like a worthy goal but SHALL NOT be REQUIRED for this release of JSR 106. 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 106 API consists of 4 packages:
- javax.xml.crypto.enc
- javax.xml.crypto.enc.dom
- javax.xml.crypto.enc.keyinfo
- javax.xml.crypto.enc.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 javax.xml.crypto.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 javax.xml.crypto.URIDereferencer class which allows developers to create and specify their own URI dereferencing implementations.
The javax.xml.crypto.enc package includes interfaces that represent the core elements defined in the W3C XML encryption specification. Of primary significance is the javax.xml.crypto.enc.EncryptedType class, which allows you to encrypt and decrypt an XML. Most of the XML encryption structures or elements are represented by a corresponding interface (except for the javax.xml.crypto.enc.keyinfo.EncryptedKey and javax.xml.crypto.enc.keyinfo.AgreementMethod structures, which are included in their own package, and discussed in the next paragraph). These interfaces include: EncryptedData, CipherData, CipherReference, CipherValue, EncryptionMethod, DataReference, KeyReference, EncryptionProperties and EncryptionProperty. The XMLEncryptionFactory class is an abstract factory that is used to create objects that implement these interfaces.
The javax.xml.crypto.enc.keyinfo package contains interfaces that represent most of the KeyInfo related structures defined in the W3C XML encryption recommendation, including EncryptedKey and AgreementMethod. The XMLEncryptionFactory class is an abstract factory that is used to create objects that implement these interfaces.
The javax.xml.crypto.enc.spec package contains interfaces and classes representing input parameters for the encryption algorithms used in the processing of XML encryption.
Finally, the javax.xml.crypto.enc.dom package contains DOM-specific classes for the javax.xml.crypto.enc package. Only developers and users who are creating or using a DOM-based XMLEncryptionFactory implementation should need to make direct use of these packages.
Service Providers
A JSR 106 cryptographic service is a concrete implementation of the abstract XMLEncryptionFactory class and is responsible for creating objects and algorithms that parse, encrypt and decrypt XML. A concrete implementation of XMLEncryptionFactory MUST provide support for each of the REQUIRED algorithms as specified by the W3C recommendation for XML Encryption. It MAY support other algorithms as defined by the W3C recommendation or other specifications.
JSR 106 leverages the 
JCA provider model for registering and loading XMLEncryptionFactory implementations.
Each concrete XMLEncryptionFactory implementation supports a specific XML mechanism type that identifies the XML processing mechanism that an implementation uses internally to encrypt and decrypt XML structures. This JSR supports one standard type: DOM. Support for new standard types (such as JDOM) MAY be added in the future.
A JSR 106 implementation SHOULD use underlying JCE engine classes, such as javax.crypto.Cipher to perform cryptographic operations.
DOM Mechanism Requirements
The following requirements MUST be abided by when implementing a DOM-based
XMLEncryptionFactory or
KeyInfoFactory, in order to minimize interoperability problems:
- The unmarshalEncryptedType method of XMLEncryptionFactory MUST support DOMDecryptContext types. If the type is DOMDecryptContext, it SHOULD contain an org.w3c.dom.Element of type that extends EncryptedType. Additionally, the unmarshalEncryptedType method MAY populate the DOMIdMap of the passed-in DOMDecryptContext.
- The encrypt method of EncryptedTypes produced by XMLEncryptionFactory MUST support DOMEncryptContext types and the decrypt method MUST support DOMDecryptContext types. This requirement also applies to the decryptAndReplace method of EncryptedData and the decryptKey method of EncryptedKey.
- The implementation MUST support DOMStructures as the mechanism for the application to specify extensible content (any elements or mixed content).
Note: 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 XMLEncryptionFactory might use a SAX parser internally to canonicalize data.
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
JIMMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) contact]
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
Trademarks
IBM® is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
