Summary

Copy the normative sections of the "Java XML Digital Signature API Specification" into the javax.xml.crypto.dsig package description so that the external links can be removed.

Problem

The "Java XML Digital Signature API Specification" is an external specification that was published as part of JSR 105: https://jcp.org/aboutJava/communityprocess/final/jsr105/index.html. It was previously bundled with the JDK Security Guide but is no longer included since JDK 10. The current links in the javadoc still point to the JDK 9 guides ( https://docs.oracle.com/javase/9/security/java-xml-digital-signature-api-specification1.htm#JSSEC-GUID-573AFFD2-7232-48F1-A376-DB0555C2F588 ) and need to be removed.

Solution

Copy the normative sections of the "Java XML Digital Signature API Specification" into the javax.xml.crypto.dsig package description so that the external links can be removed.

Specification

The following sections will be added to the package description of the javax.xml.crypto.dsig package. Links in the XMLSignatureFactory, KeyInfoFactory and TransformService classes to the external specification will be replaced with links to the new sections in the package description.

+ * <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.
+ *