/*

 * 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;