| /* | |
| * Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code is distributed in the hope that it will be useful, but WITHOUT | |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| /** | |
| * 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: | |
| * {@link javax.xml.crypto.dsig.XMLSignature XMLSignature}, | |
| * {@link javax.xml.crypto.dsig.SignedInfo SignedInfo}, | |
| * {@link javax.xml.crypto.dsig.CanonicalizationMethod CanonicalizationMethod}, | |
| * {@link javax.xml.crypto.dsig.SignatureMethod SignatureMethod}, | |
| * {@link javax.xml.crypto.dsig.Reference Reference}, | |
| * {@link javax.xml.crypto.dsig.DigestMethod DigestMethod}, | |
| * {@link javax.xml.crypto.dsig.XMLObject XMLObject}, | |
| * {@link javax.xml.crypto.dsig.Manifest Manifest}, | |
| * {@link javax.xml.crypto.dsig.SignatureProperties SignatureProperties}, and | |
| * {@link javax.xml.crypto.dsig.SignatureProperty SignatureProperty}. | |
| * {@code KeyInfo} types are defined in the | |
| * {@link javax.xml.crypto.dsig.keyinfo} subpackage. | |
| * {@link javax.xml.crypto.dsig.XMLSignatureFactory XMLSignatureFactory} | |
| * is an abstract factory that creates | |
| * {@link javax.xml.crypto.dsig.XMLSignature XMLSignature} objects from scratch | |
| * or from a pre-existing XML representation, such as a DOM node. | |
| * {@link javax.xml.crypto.dsig.TransformService} is a service provider | |
| * interface for creating and plugging in implementations of | |
| * transform and canonicalization algorithms. | |
| * | |
| * <p>Of primary significance in this package is the | |
| * {@link javax.xml.crypto.dsig.XMLSignature XMLSignature} class, | |
| * which allows you to sign and validate an XML digital signature. | |
| * | |
| * <h2><a id="service_providers"></a>Service Providers</h2> | |
| * A service provider is a concrete implementation of the abstract | |
| * {@link javax.xml.crypto.dsig.XMLSignatureFactory XMLSignatureFactory} and | |
| * {@link javax.xml.crypto.dsig.keyinfo.KeyInfoFactory KeyInfoFactory} classes | |
| * and is responsible for creating objects and algorithms that parse, generate | |
| * and validate XML Signatures and KeyInfo structures. A concrete implementation | |
| * of {@code 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. | |
| * | |
| * <p>The API leverages the JCA provider model (see | |
| * {@link java.security.Provider the Provider class}) for registering and | |
| * loading {@code XMLSignatureFactory} and {@code KeyInfoFactory} | |
| * implementations. | |
| * | |
| * <p>Each concrete {@code XMLSignatureFactory} or {@code 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. | |
| * | |
| * <p>A service provider implementation SHOULD use underlying JCA engine | |
| * classes, such as {@link java.security.Signature} and | |
| * {@link java.security.MessageDigest} to perform cryptographic operations. | |
| * | |
| * <p>In addition to the {@code XMLSignatureFactory} and {@code KeyInfoFactory} | |
| * classes, the API supports a service provider interface for transform and | |
| * canonicalization algorithms. The {@link | |
| * javax.xml.crypto.dsig.TransformService 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 {@code | |
| * TransformService} class uses the standard JCA provider model for registering | |
| * and loading implementations. Each service provider implementation SHOULD use | |
| * the {@code TransformService} class to find a provider that supports transform | |
| * and canonicalization algorithms in XML Signatures that it is generating or | |
| * validating. | |
| * | |
| * <h3><a id="dom_req"></a>DOM Mechanism Requirements</h3> | |
| * The following requirements MUST be abided by when implementing a DOM-based | |
| * {@code XMLSignatureFactory}, {@code KeyInfoFactory} or {@code | |
| * TransformService} in order to minimize interoperability problems: | |
| * <ol> | |
| * <li>The {@code unmarshalXMLSignature} method of {@code XMLSignatureFactory} | |
| * MUST support {@code DOMValidateContext} types. If the type is | |
| * {@code DOMValidateContext}, it SHOULD contain an {@code Element} of type | |
| * Signature. Additionally, the {@code unmarshalXMLSignature} method MAY | |
| * populate the Id/Element mappings of the passed-in {@code DOMValidateContext}. | |
| * </li> | |
| * | |
| * <li>The {@code sign} method of {@code XMLSignature}s produced by | |
| * {@code XMLSignatureFactory} MUST support {@code DOMSignContext} types and the | |
| * {@code validate} method MUST support {@code DOMValidateContext} types. This | |
| * requirement also applies to the {@code validate} method of {@code | |
| * SignatureValue} and the {@code validate} method of {@code Reference}.</li> | |
| * | |
| * <li>The implementation MUST support {@code DOMStructure}s as the mechanism | |
| * for the application to specify extensible content (any elements or mixed | |
| * content).</li> | |
| * | |
| * <li>If the {@code dereference} method of user-specified {@code | |
| * URIDereferencer}s returns {@code NodeSetData} objects, the {@code iterator} | |
| * method MUST return an iteration over objects of type {@code | |
| * org.w3c.dom.Node}.</li> | |
| * | |
| * <li>{@code URIReference} objects passed to the {@code dereference} method of | |
| * user-specified {@code URIDereferencer}s MUST be of type {@code | |
| * DOMURIReference} and {@code XMLCryptoContext} objects MUST implement {@code | |
| * DOMCryptoContext}.</li> | |
| * | |
| * <li>The previous 2 requirements also apply to {@code URIDereferencer}s | |
| * returned by the {@code getURIDereferencer} method of {@code | |
| * XMLSignatureFactory} and {@code KeyInfoFactory}.</li> | |
| * | |
| * <li>The {@code unmarshalKeyInfo} method of {@code KeyInfoFactory} MUST | |
| * support {@code DOMStructure} types. If the type is {@code DOMStructure}, it | |
| * SHOULD contain an {@code Element} of type {@code KeyInfo}.</li> | |
| * | |
| * <li>The {@code transform} method of {@code Transform} MUST support | |
| * {@code DOMCryptoContext} context parameter types.</li> | |
| * | |
| * <li>The {@code newtransform} and {@code newCanonicalizationMethod} methods of | |
| * {@code XMLSignatureFactory} MUST support {@code DOMStructure} parameter | |
| * types.</li> | |
| * | |
| * <li>The {@code init}, and {@code marshalParams} methods of | |
| * {@code TransformService} MUST support {@code DOMStructure} and | |
| * {@code DOMCryptoContext} types.</li> | |
| * | |
| * <li>The {@code unmarshalXMLSignature} method of {@code XMLSignatureFactory} | |
| * MUST support {@code DOMStructure} types. If the type is {@code DOMStructure}, | |
| * it SHOULD contain an {@code Element} of type {@code Signature}.</li> | |
| * | |
| * <li>The {@code marshal} method of {@code KeyInfo} MUST support | |
| * {@code DOMStructure} and {@code DOMCryptoContext} parameter types.</li> | |
| * </ol> | |
| * | |
| * <p>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 {@code XMLSignatureFactory} might use a SAX parser | |
| * internally to canonicalize data. | |
| * | |
| * <h2>Package Specification</h2> | |
| * | |
| * <ul> | |
| * <li> | |
| * <a href="http://www.w3.org/TR/xmldsig-core/"> | |
| * XML-Signature Syntax and Processing: W3C Recommendation</a> | |
| * <li> | |
| * <a href="http://www.ietf.org/rfc/rfc3275.txt"> | |
| * RFC 3275: XML-Signature Syntax and Processing</a> | |
| * </ul> | |
| * | |
| * @since 1.6 | |
| */ | |
| package javax.xml.crypto.dsig; |