8305406: Add @spec tags in java.base/java.* (part 2)

Co-authored-by: Daniel Jeliński <djelinski@openjdk.org>
Co-authored-by: Hannes Wallnöfer <hannesw@openjdk.org>
Reviewed-by: valeriep

src/java.base/share/classes/com/sun/crypto/provider/AESKeyWrap.java

@@ -37,6 +37,9 @@ import static com.sun.crypto.provider.KWUtil.*;
  * <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
  * "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"</a>
  * and represents AES cipher in KW mode.
+ *
+ * @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
+ *      Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
  */
 class AESKeyWrap extends FeedbackCipher {
 

src/java.base/share/classes/com/sun/crypto/provider/AESKeyWrapPadded.java

@@ -39,6 +39,9 @@ import static com.sun.crypto.provider.KWUtil.*;
  * <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
  * "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"</a>
  * and represents AES cipher in KWP mode.
+ *
+ * @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
+ *      Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
  */
 class AESKeyWrapPadded extends FeedbackCipher {
 

src/java.base/share/classes/com/sun/crypto/provider/KWUtil.java

@@ -31,6 +31,9 @@ import java.util.Arrays;
  * This class acts as the base class for AES KeyWrap algorithms as defined
  * in <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
  * "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"
+ *
+ * @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
+ *      Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
  */
 class KWUtil {
 

src/java.base/share/classes/com/sun/crypto/provider/KeyWrapCipher.java

@@ -36,6 +36,9 @@ import static com.sun.crypto.provider.KWUtil.*;
  * This class is the impl class for AES KeyWrap algorithms as defined in
  * <a href=https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>
  * "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping"
+ *
+ * @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf
+ *      Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping
  */
 abstract class KeyWrapCipher extends CipherSpi {
 

src/java.base/share/classes/java/security/DrbgParameters.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2024, 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
@@ -227,6 +227,9 @@ import java.util.Objects;
  * Calling {@link SecureRandom#generateSeed(int)} will directly read
  * from this system default entropy source.
  *
+ * @spec https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf
+ *      Recommendation for Random Number Generation Using Deterministic Random Bit Generators
+ *
  * @since 9
  */
 public class DrbgParameters {

src/java.base/share/classes/java/security/Key.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2024, 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
@@ -86,6 +86,10 @@ package java.security;
  * Security Appendix</a>
  * of the <cite>Java Object Serialization Specification</cite> for more information.
  *
+ * @spec serialization/index.html Java Object Serialization Specification
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @see PublicKey
  * @see PrivateKey
  * @see KeyPair
@@ -124,6 +128,7 @@ public interface Key extends java.io.Serializable {
      * Java Security Standard Algorithm Names Specification</a>
      * for information about standard key algorithm names.
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @return the name of the algorithm associated with this key.
      */
     String getAlgorithm();

src/java.base/share/classes/java/security/KeyRep.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -44,6 +44,7 @@ import java.util.Locale;
  * Security Appendix</a>
  * of the <cite>Java Object Serialization Specification</cite> for more information.
  *
+ * @spec serialization/index.html Java Object Serialization Specification
  * @see Key
  * @see KeyFactory
  * @see javax.crypto.spec.SecretKeySpec

src/java.base/share/classes/java/security/SecureRandom.java

@@ -140,6 +140,11 @@ import java.util.regex.Pattern;
  * <li>{@link SecureRandomSpi#engineReseed(SecureRandomParameters)}
  * </ul>
  *
+ * @spec https://www.rfc-editor.org/info/rfc4086
+ *      RFC 4086: Randomness Requirements for Security
+ * @spec https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-2.pdf
+ *      Security Requirements for Cryptographic Modules
+ *
  * @see java.security.SecureRandomSpi
  * @see java.util.Random
  *

src/java.base/share/classes/java/security/Security.java

@@ -423,6 +423,7 @@ public final class Security {
      *
      * @return the value of the specified property.
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @deprecated This method used to return the value of a proprietary
      * property in the master file of the "SUN" Cryptographic Service
      * Provider in order to determine how to parse algorithm-specific
@@ -657,6 +658,7 @@ public final class Security {
      *         if the filter is not in the required format
      * @throws NullPointerException if filter is {@code null}
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @see #getProviders(java.util.Map)
      * @since 1.3
      */
@@ -734,6 +736,7 @@ public final class Security {
      *         if the filter is not in the required format
      * @throws NullPointerException if filter is {@code null}
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @see #getProviders(java.lang.String)
      * @since 1.3
      */

src/java.base/share/classes/java/security/cert/CRL.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -56,6 +56,8 @@ public abstract class CRL {
      * "{@docRoot}/../specs/security/standard-names.html">
      * Java Security Standard Algorithm Names</a> document
      * for information about standard CRL types.
+     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     protected CRL(String type) {
         this.type = type;

src/java.base/share/classes/java/security/cert/CRLReason.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2024, 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
@@ -31,6 +31,9 @@ package java.security.cert;
  * RFC 5280: Internet X.509 Public Key Infrastructure Certificate and CRL
  * Profile</a>.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @author Sean Mullan
  * @since 1.7
  * @see X509CRLEntry#getRevocationReason

src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -81,14 +81,13 @@ import java.util.*;
  * necessary locking. Multiple threads each manipulating separate objects
  * need not synchronize.
  *
+ * @spec https://www.rfc-editor.org/info/rfc2560
+ *      RFC 2560: X.509 Internet Public Key Infrastructure Online Certificate
+ *              Status Protocol - OCSP
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @since 1.8
- *
- * @see <a href="http://www.ietf.org/rfc/rfc2560.txt"><i>RFC&nbsp;2560: X.509
- * Internet Public Key Infrastructure Online Certificate Status Protocol -
- * OCSP</i></a>
- * @see <a href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280:
- * Internet X.509 Public Key Infrastructure Certificate and Certificate
- * Revocation List (CRL) Profile</i></a>
  */
 public abstract class PKIXRevocationChecker extends PKIXCertPathChecker {
     private URI ocspResponder;

src/java.base/share/classes/java/security/cert/TrustAnchor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, 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
@@ -125,6 +125,10 @@ public class TrustAnchor {
      * decoded
      * @throws NullPointerException if the specified
      * {@code X509Certificate} is {@code null}
+     *
+     * @spec https://www.rfc-editor.org/info/rfc5280
+     *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+     *              and Certificate Revocation List (CRL) Profile
      */
     public TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints)
     {
@@ -207,6 +211,10 @@ public class TrustAnchor {
      * or incorrectly formatted or the name constraints cannot be decoded
      * @throws NullPointerException if the specified {@code caName} or
      * {@code pubKey} parameter is {@code null}
+     *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      */
     public TrustAnchor(String caName, PublicKey pubKey, byte[] nameConstraints)
     {

src/java.base/share/classes/java/security/cert/X509CRL.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -95,6 +95,9 @@ import java.util.Set;
  * }
  * }</pre>
  *
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @author Hemma Prafullchandra
  * @since 1.2
  *
@@ -457,6 +460,11 @@ public abstract class X509CRL extends CRL implements X509Extension {
      * relevant ASN.1 definitions.
      *
      * @return the signature algorithm OID string.
+     *
+     * @spec https://www.rfc-editor.org/info/rfc3279
+     *      RFC 3279: Algorithms and Identifiers for the Internet X.509
+     *              Public Key Infrastructure Certificate and Certificate
+     *              Revocation List (CRL) Profile
      */
     public abstract String getSigAlgOID();
 

src/java.base/share/classes/java/security/cert/X509CRLSelector.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2024, 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
@@ -65,6 +65,9 @@ import sun.security.x509.X500Name;
  * provide the necessary locking. Multiple threads each manipulating
  * separate objects need not synchronize.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @see CRLSelector
  * @see X509CRL
  *
@@ -193,6 +196,10 @@ public class X509CRLSelector implements CRLSelector {
      *
      * @param names a {@code Collection} of names (or {@code null})
      * @throws IOException if a parsing error occurs
+     *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @see #getIssuerNames
      */
     public void setIssuerNames(Collection<?> names) throws IOException {
@@ -238,6 +245,9 @@ public class X509CRLSelector implements CRLSelector {
      *     <a href="http://www.ietf.org/rfc/rfc2253.txt">RFC 2253</a> form
      * @throws IOException if a parsing error occurs
      *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @deprecated Use {@link #addIssuer(X500Principal)} or
      * {@link #addIssuerName(byte[])} instead. This method should not be
      * relied on as it can fail to match some CRLs because of a loss of
@@ -493,6 +503,10 @@ public class X509CRLSelector implements CRLSelector {
      * protect against subsequent modifications.
      *
      * @return a {@code Collection} of names (or {@code null})
+     *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @see #setIssuerNames
      */
     public Collection<Object> getIssuerNames() {

src/java.base/share/classes/java/security/cert/X509CertSelector.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2024, 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
@@ -74,6 +74,9 @@ import sun.security.x509.*;
  * provide the necessary locking. Multiple threads each manipulating
  * separate objects need not synchronize.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @see CertSelector
  * @see X509Certificate
  *
@@ -194,6 +197,9 @@ public class X509CertSelector implements CertSelector {
      *                 (or {@code null})
      * @throws IOException if a parsing error occurs (incorrect form for DN)
      *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @deprecated Use {@link #setIssuer(X500Principal)} or
      * {@link #setIssuer(byte[])} instead. This method should not be relied on
      * as it can fail to match some certificates because of a loss of encoding
@@ -286,6 +292,9 @@ public class X509CertSelector implements CertSelector {
      *                  (or {@code null})
      * @throws IOException if a parsing error occurs (incorrect form for DN)
      *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @deprecated Use {@link #setSubject(X500Principal)} or
      * {@link #setSubject(byte[])} instead. This method should not be relied
      * on as it can fail to match some certificates because of a loss of
@@ -728,6 +737,12 @@ public class X509CertSelector implements CertSelector {
      *             RFC 5280, section 4.2.1.6)
      * @param name the name in string form (not {@code null})
      * @throws IOException if a parsing error occurs
+     *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
+     * @spec https://www.rfc-editor.org/info/rfc822
+     *      RFC 822: STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES
      */
     public void addSubjectAlternativeName(int type, String name)
             throws IOException {
@@ -1269,6 +1284,9 @@ public class X509CertSelector implements CertSelector {
      * @return the required issuer distinguished name in RFC 2253 format
      *         (or {@code null})
      *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @deprecated Use {@link #getIssuer()} or {@link #getIssuerAsBytes()}
      * instead. This method should not be relied on as it can fail to match
      * some certificates because of a loss of encoding information in the
@@ -1328,6 +1346,9 @@ public class X509CertSelector implements CertSelector {
      * @return the required subject distinguished name in RFC 2253 format
      *         (or {@code null})
      *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
      * @deprecated Use {@link #getSubject()} or {@link #getSubjectAsBytes()}
      * instead. This method should not be relied on as it can fail to match
      * some certificates because of a loss of encoding information in the

src/java.base/share/classes/java/security/cert/X509Certificate.java

@@ -95,6 +95,9 @@ import java.util.List;
  * }
  * </pre>
  *
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @author Hemma Prafullchandra
  * @since 1.2
  *
@@ -386,6 +389,11 @@ implements X509Extension {
      * relevant ASN.1 definitions.
      *
      * @return the signature algorithm OID string.
+     *
+     * @spec https://www.rfc-editor.org/info/rfc3279
+     *      RFC 3279: Algorithms and Identifiers for the Internet X.509
+     *              Public Key Infrastructure Certificate and Certificate
+     *              Revocation List (CRL) Profile
      */
     public abstract String getSigAlgOID();
 
@@ -614,6 +622,12 @@ implements X509Extension {
      * @return an immutable {@code Collection} of subject alternative
      * names (or {@code null})
      * @throws CertificateParsingException if the extension cannot be decoded
+     *
+     * @spec https://www.rfc-editor.org/info/rfc2253
+     *      RFC 2253: Lightweight Directory Access Protocol (v3):
+     *              UTF-8 String Representation of Distinguished Names
+     * @spec https://www.rfc-editor.org/info/rfc822
+     *      RFC 822: STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES
      * @since 1.4
      */
     public Collection<List<?>> getSubjectAlternativeNames()

src/java.base/share/classes/java/security/cert/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -52,6 +52,13 @@
  *   <li> {@extLink security_guide_pki Java PKI Programmer's Guide}
  * </ul>
  *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names
+ * @spec https://www.rfc-editor.org/info/rfc2560
+ *      RFC 2560: X.509 Internet Public Key Infrastructure Online Certificate
+ *              Status Protocol - OCSP
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @since 1.2
  */
 package java.security.cert;

src/java.base/share/classes/java/security/interfaces/EdECKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2024, 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
@@ -35,6 +35,8 @@ import java.security.spec.NamedParameterSpec;
  * This interface allows access to the algorithm parameters associated with
  * the key.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 public interface EdECKey {

src/java.base/share/classes/java/security/interfaces/EdECPrivateKey.java

@@ -40,6 +40,8 @@ import java.util.Optional;
  * string lengths that are a multiple of 8, and the key is represented using
  * a byte array.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 public interface EdECPrivateKey extends EdECKey, PrivateKey {

src/java.base/share/classes/java/security/interfaces/EdECPublicKey.java

@@ -38,6 +38,8 @@ import java.security.spec.NamedParameterSpec;
  * An Edwards-Curve public key is a point on the curve, which is represented using an
  * EdECPoint.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 public interface EdECPublicKey extends EdECKey, PublicKey {

src/java.base/share/classes/java/security/interfaces/RSAKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2024, 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
@@ -33,6 +33,8 @@ import java.security.spec.AlgorithmParameterSpec;
  * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard,
  * such as those for RSA, or RSASSA-PSS algorithms.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Jan Luehe
  *
  * @see RSAPublicKey

src/java.base/share/classes/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, 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
@@ -33,6 +33,8 @@ import java.security.spec.RSAOtherPrimeInfo;
  * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard,
  * using the <i>Chinese Remainder Theorem</i> (CRT) information values.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Valerie Peng
  *
  *

src/java.base/share/classes/java/security/interfaces/RSAPrivateCrtKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -32,6 +32,8 @@ import java.math.BigInteger;
  * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard,
  * using the <i>Chinese Remainder Theorem</i> (CRT) information values.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Jan Luehe
  * @since 1.2
  *

src/java.base/share/classes/java/security/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -79,6 +79,7 @@
  *
  * </ul>
  *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names
  * @since 1.1
  */
 package java.security;

src/java.base/share/classes/java/security/spec/DSAGenParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -29,6 +29,9 @@ package java.security.spec;
  * generating DSA parameters as specified in
  * <a href="http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf">FIPS 186-3 Digital Signature Standard (DSS)</a>.
  *
+ * @spec  https://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf
+ *      FIPS 186-3 Digital Signature Standard (DSS)
+ *
  * @see AlgorithmParameterSpec
  *
  * @since 1.8

src/java.base/share/classes/java/security/spec/EdDSAParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, 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
@@ -41,6 +41,8 @@ import java.util.Optional;
  * <li>Otherwise, the mode is Ed25519 or Ed448</li>
  * </ul>
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 

src/java.base/share/classes/java/security/spec/EdECPoint.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2024, 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
@@ -42,6 +42,8 @@ import java.util.Objects;
  * {@code BigInteger}, and implementations that consume objects of this class
  * may reject integer values which are not in the range [0, p).
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 

src/java.base/share/classes/java/security/spec/EdECPrivateKeySpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2024, 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
@@ -34,6 +34,8 @@ import java.util.Objects;
  * a byte array. This class only supports bit string lengths that are a
  * multiple of 8.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 public final class EdECPrivateKeySpec implements KeySpec {

src/java.base/share/classes/java/security/spec/EdECPublicKeySpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2024, 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
@@ -33,6 +33,8 @@ import java.util.Objects;
  * algorithm parameters. The public key is a point on the curve, which is
  * represented using an {@code EdECPoint}.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8032
+ *      RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  * @since 15
  */
 public final class EdECPublicKeySpec implements KeySpec {

src/java.base/share/classes/java/security/spec/MGF1ParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -55,6 +55,8 @@ package java.security.spec;
  *   ...  -- Allows for future expansion --
  * }
  * </pre>
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @see PSSParameterSpec
  * @see javax.crypto.spec.OAEPParameterSpec
  *

src/java.base/share/classes/java/security/spec/PSSParameterSpec.java

@@ -65,6 +65,8 @@ import java.util.Objects;
  * }
  * </pre>
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @see MGF1ParameterSpec
  * @see AlgorithmParameterSpec
  * @see java.security.Signature
@@ -96,6 +98,8 @@ public class PSSParameterSpec implements AlgorithmParameterSpec {
 
     /**
      * The PSS parameter set with all default values.
+     * @spec https://www.rfc-editor.org/info/rfc8017
+     *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
      * @deprecated This field uses the default values defined in the PKCS #1
      *         standard. Some of these defaults are no longer recommended due
      *         to advances in cryptanalysis -- see the
@@ -170,6 +174,8 @@ public class PSSParameterSpec implements AlgorithmParameterSpec {
      * @param saltLen the length of salt in bytes
      * @throws    IllegalArgumentException if {@code saltLen} is
      *         less than 0
+     * @spec https://www.rfc-editor.org/info/rfc8017
+     *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
      * @deprecated This constructor uses the default values defined in
      *         the PKCS #1 standard except for the salt length. Some of these
      *         defaults are no longer recommended due to advances in

src/java.base/share/classes/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, 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
@@ -34,6 +34,8 @@ import java.util.Objects;
  * using the Chinese Remainder Theorem (CRT) information values
  * for efficiency.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Valerie Peng
  *
  *

src/java.base/share/classes/java/security/spec/RSAOtherPrimeInfo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, 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
@@ -42,6 +42,8 @@ import java.math.BigInteger;
  *
  * </pre>
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Valerie Peng
  *
  *

src/java.base/share/classes/java/security/spec/RSAPrivateCrtKeySpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -32,6 +32,8 @@ import java.math.BigInteger;
  * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard,
  * using the Chinese Remainder Theorem (CRT) information values for efficiency.
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Jan Luehe
  * @since 1.2
  *

src/java.base/share/classes/javax/crypto/Cipher.java

@@ -164,6 +164,10 @@ import sun.security.util.KnownOIDs;
  * Consult the release documentation for your implementation to see if any
  * other transformations are supported.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5116
+ *      RFC 5116: An Interface and Algorithms for Authenticated Encryption
+ * @spec https://www.rfc-editor.org/info/rfc7539
+ *      RFC 7539: ChaCha20 and Poly1305 for IETF Protocols
  * @author Jan Luehe
  * @see KeyGenerator
  * @see SecretKey

src/java.base/share/classes/javax/crypto/EncryptedPrivateKeyInfo.java

@@ -137,6 +137,8 @@ public class EncryptedPrivateKeyInfo {
      * is empty, i.e. 0-length.
      * @exception NoSuchAlgorithmException if the specified algName is
      * not supported.
+     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     public EncryptedPrivateKeyInfo(String algName, byte[] encryptedData)
         throws NoSuchAlgorithmException {
@@ -226,6 +228,8 @@ public class EncryptedPrivateKeyInfo {
      * for information about standard Cipher algorithm names.
      *
      * @return the encryption algorithm name.
+     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     public String getAlgName() {
         return algid == null ? params.getAlgorithm() : algid.getName();

src/java.base/share/classes/javax/crypto/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2024, 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
@@ -59,6 +59,7 @@
  *       How to Implement a Provider in the Java Cryptography Architecture}</li>
  * </ul>
  *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names
  * @since 1.4
  */
 package javax.crypto;

src/java.base/share/classes/javax/crypto/spec/ChaCha20ParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024, 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
@@ -39,6 +39,8 @@ import java.util.Objects;
  * <p> This class can be used to initialize a {@code Cipher} object that
  * implements the <i>ChaCha20</i> algorithm.
  *
+ * @spec https://www.rfc-editor.org/info/rfc7539
+ *      RFC 7539: ChaCha20 and Poly1305 for IETF Protocols
  * @since 11
  */
 public final class ChaCha20ParameterSpec implements AlgorithmParameterSpec {

src/java.base/share/classes/javax/crypto/spec/GCMParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024, 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
@@ -56,6 +56,12 @@ import java.security.spec.AlgorithmParameterSpec;
  * applications.  Other values can be specified for this class, but not
  * all CSP implementations will support them.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5116
+ *      RFC 5116: An Interface and Algorithms for Authenticated Encryption
+ * @spec https://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf
+ *      Recommendation for Block Cipher Modes of Operation: Galois/Counter
+ *      Mode (GCM) and GMAC
+ *
  * @see javax.crypto.Cipher
  *
  * @since 1.7

src/java.base/share/classes/javax/crypto/spec/OAEPParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -72,6 +72,8 @@ import java.security.spec.MGF1ParameterSpec;
  * EncodingParameters ::= OCTET STRING(SIZE(0..MAX))
  * </pre>
  *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @see java.security.spec.MGF1ParameterSpec
  * @see PSource
  *

src/java.base/share/classes/javax/crypto/spec/PBEKeySpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -54,6 +54,8 @@ import java.util.Arrays;
  * this class requests the password as a char array, so it can be overwritten
  * when done.
  *
+ * @spec https://www.rfc-editor.org/info/rfc2898
+ *      RFC 2898: PKCS #5: Password-Based Cryptography Specification Version 2.0
  * @author Jan Luehe
  * @author Valerie Peng
  *

src/java.base/share/classes/javax/crypto/spec/PBEParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -33,6 +33,8 @@ import java.security.spec.AlgorithmParameterSpec;
  * <a href="http://www.ietf.org/rfc/rfc2898.txt">PKCS #5</a>
  * standard.
  *
+ * @spec https://www.rfc-editor.org/info/rfc2898
+ *      RFC 2898: PKCS #5: Password-Based Cryptography Specification Version 2.0
  * @author Jan Luehe
  *
  * @since 1.4

src/java.base/share/classes/javax/crypto/spec/PSource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -42,6 +42,9 @@ package javax.crypto.spec;
  * }
  * EncodingParameters ::= OCTET STRING(SIZE(0..MAX))
  * </pre>
+ *
+ * @spec https://www.rfc-editor.org/info/rfc8017
+ *      RFC 8017: PKCS #1: RSA Cryptography Specifications Version 2.2
  * @author Valerie Peng
  *
  * @since 1.5

src/java.base/share/classes/javax/crypto/spec/RC2ParameterSpec.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -39,6 +39,8 @@ import java.util.Arrays;
  * <p> This class can be used to initialize a {@code Cipher} object that
  * implements the <i>RC2</i> algorithm.
  *
+ * @spec https://www.rfc-editor.org/info/rfc2268
+ *      RFC 2268: A Description of the RC2(r) Encryption Algorithm
  * @author Jan Luehe
  *
  * @since 1.4

src/java.base/share/classes/javax/crypto/spec/RC5ParameterSpec.java

@@ -39,6 +39,8 @@ import java.util.Arrays;
  * <p> This class can be used to initialize a {@code Cipher} object that
  * implements the <i>RC5</i> algorithm.
  *
+ * @spec https://www.rfc-editor.org/info/rfc2040
+ *      RFC 2040: The RC5, RC5-CBC, RC5-CBC-Pad, and RC5-CTS Algorithms
  * @author Jan Luehe
  *
  * @since 1.4

src/java.base/share/classes/javax/crypto/spec/SecretKeySpec.java

@@ -98,6 +98,8 @@ public class SecretKeySpec implements KeySpec, SecretKey {
      * for information about standard algorithm names.
      * @exception IllegalArgumentException if <code>algorithm</code>
      * is null or <code>key</code> is null or empty.
+     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     public SecretKeySpec(byte[] key, String algorithm) {
         String errMsg = doSanityCheck(key, algorithm);
@@ -144,6 +146,8 @@ public class SecretKeySpec implements KeySpec, SecretKey {
      * @exception ArrayIndexOutOfBoundsException is thrown if
      * <code>offset</code> or <code>len</code> index bytes outside the
      * <code>key</code>.
+     *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     public SecretKeySpec(byte[] key, int offset, int len, String algorithm) {
         if (key == null || algorithm == null) {

src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2024, 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
@@ -63,6 +63,7 @@ public abstract class ExtendedSSLSession implements SSLSession {
      *     order of preference.  The return value is an empty array if
      *     no signature algorithm is supported.
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @see SSLParameters#getAlgorithmConstraints
      */
     public abstract String[] getLocalSupportedSignatureAlgorithms();
@@ -86,6 +87,7 @@ public abstract class ExtendedSSLSession implements SSLSession {
      *     order of preference.  The return value is an empty array if
      *     the peer has not sent the supported signature algorithms.
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @see X509KeyManager
      * @see X509ExtendedKeyManager
      */

src/java.base/share/classes/javax/net/ssl/SNIHostName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -53,6 +53,11 @@ import java.util.regex.PatternSyntaxException;
  * <P>
  * Note that {@code SNIHostName} objects are immutable.
  *
+ * @spec https://www.rfc-editor.org/info/rfc5890
+ *      RFC 5890: Internationalized Domain Names for Applications (IDNA):
+ *              Definitions and Document Framework
+ * @spec https://www.rfc-editor.org/info/rfc6066
+ *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
  * @see SNIServerName
  * @see StandardConstants#SNI_HOST_NAME
  *
@@ -92,6 +97,15 @@ public final class SNIHostName extends SNIServerName {
      *
      * @throws NullPointerException if {@code hostname} is {@code null}
      * @throws IllegalArgumentException if {@code hostname} is illegal
+     *
+     * @spec https://www.rfc-editor.org/info/rfc1122
+     *      RFC 1122: Requirements for Internet Hosts - Communication Layers
+     * @spec https://www.rfc-editor.org/info/rfc1123
+     *      RFC 1123: Requirements for Internet Hosts - Application and Support
+     * @spec https://www.rfc-editor.org/info/rfc3490
+     *      RFC 3490: Internationalizing Domain Names in Applications (IDNA)
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      */
     public SNIHostName(String hostname) {
         // IllegalArgumentException will be thrown if {@code hostname} is
@@ -159,6 +173,17 @@ public final class SNIHostName extends SNIServerName {
      *
      * @throws NullPointerException if {@code encoded} is {@code null}
      * @throws IllegalArgumentException if {@code encoded} is illegal
+     *
+     * @spec https://www.rfc-editor.org/info/rfc1122
+     *      RFC 1122: Requirements for Internet Hosts - Communication Layers
+     * @spec https://www.rfc-editor.org/info/rfc1123
+     *      RFC 1123: Requirements for Internet Hosts - Application and Support
+     * @spec https://www.rfc-editor.org/info/rfc3490
+     *      RFC 3490: Internationalizing Domain Names in Applications (IDNA)
+     * @spec https://www.rfc-editor.org/info/rfc4366
+     *      RFC 4366: Transport Layer Security (TLS) Extensions
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      */
     public SNIHostName(byte[] encoded) {
         // NullPointerException will be thrown if {@code encoded} is null
@@ -198,6 +223,11 @@ public final class SNIHostName extends SNIServerName {
      *
      * @return the {@link StandardCharsets#US_ASCII}-compliant hostname
      *         of this {@code SNIHostName} object
+     *
+     * @spec https://www.rfc-editor.org/info/rfc5890
+     *      RFC 5890: Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      */
     public String getAsciiName() {
         return hostname;
@@ -215,6 +245,9 @@ public final class SNIHostName extends SNIServerName {
      *         the other server name object to compare with.
      * @return true if, and only if, the {@code other} is considered
      *         equal to this instance
+     *
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      */
     @Override
     public boolean equals(Object other) {

src/java.base/share/classes/javax/net/ssl/SNIServerName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -41,6 +41,8 @@ import java.util.List;
  * {@code SNIServerName} objects are immutable.  Subclasses should not provide
  * methods that can change the state of an instance once it has been created.
  *
+ * @spec https://www.rfc-editor.org/info/rfc6066
+ *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
  * @see SSLParameters#getServerNames()
  * @see SSLParameters#setServerNames(List)
  *

src/java.base/share/classes/javax/net/ssl/SSLEngine.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -413,6 +413,8 @@ import java.util.function.BiFunction;
  *      because there is no way to guarantee the eventual packet ordering.
  * </OL>
  *
+ * @spec https://www.rfc-editor.org/info/rfc2246
+ *      RFC 2246: The TLS Protocol Version 1.0
  * @see SSLContext
  * @see SSLSocket
  * @see SSLServerSocket
@@ -859,6 +861,8 @@ public abstract class SSLEngine {
      *          if this engine has not received the proper SSL/TLS/DTLS close
      *          notification message from the peer.
      *
+     * @spec https://www.rfc-editor.org/info/rfc2246
+     *      RFC 2246: The TLS Protocol Version 1.0
      * @see     #isInboundDone()
      * @see     #isOutboundDone()
      */
@@ -1351,6 +1355,8 @@ public abstract class SSLEngine {
      * Application-Layer Protocol Negotiation (ALPN), can negotiate
      * application-level values between peers.
      *
+     * @spec https://www.rfc-editor.org/info/rfc7301
+     *      RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
      * @implSpec
      * The implementation in this class throws
      * {@code UnsupportedOperationException} and performs no other action.

src/java.base/share/classes/javax/net/ssl/SSLParameters.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2024, 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
@@ -300,6 +300,7 @@ public class SSLParameters {
      *     Java Security Standard Algorithm Names</a> document
      *     for information about standard algorithm names.
      *
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @see X509ExtendedTrustManager
      *
      * @since 1.7
@@ -674,6 +675,9 @@ public class SSLParameters {
      * @throws IllegalArgumentException if protocols is null, or if
      *                    any element in a non-empty array is null or an
      *                    empty (zero-length) string
+     *
+     * @spec https://www.rfc-editor.org/info/rfc7301
+     *      RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
      * @see #getApplicationProtocols
      * @since 9
      */

src/java.base/share/classes/javax/net/ssl/SSLSocket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -770,6 +770,9 @@ public abstract class SSLSocket extends Socket
      *         if a value was successfully negotiated.
      * @throws UnsupportedOperationException if the underlying provider
      *         does not implement the operation.
+     *
+     * @spec https://www.rfc-editor.org/info/rfc7301
+     *      RFC 7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension
      * @since 9
      */
     public String getApplicationProtocol() {

src/java.base/share/classes/javax/net/ssl/SSLSocketFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -198,6 +198,8 @@ public abstract class SSLSocketFactory extends SocketFactory {
      *         does not implement the operation
      * @throws NullPointerException if {@code s} is {@code null}
      *
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      * @since 1.8
      */
     public Socket createSocket(Socket s, InputStream consumed,

src/java.base/share/classes/javax/net/ssl/StandardConstants.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -49,6 +49,8 @@ public final class StandardConstants {
      * <P>
      * The value of this constant is {@value}.
      *
+     * @spec https://www.rfc-editor.org/info/rfc6066
+     *      RFC 6066: Transport Layer Security (TLS) Extensions: Extension Definitions
      * @see SNIServerName
      * @see SNIHostName
      */

src/java.base/share/classes/javax/net/ssl/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2024, 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
@@ -36,6 +36,7 @@
  * </b></a></li>
  * </ul>
  *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names
  * @since 1.4
  */
 package javax.net.ssl;

src/java.base/share/classes/javax/security/auth/login/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2024, 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
@@ -33,6 +33,7 @@
  *     </b></a></li>
  * </ul>
  *
+ * @spec security/standard-names.html Java Security Standard Algorithm Names
  * @since 1.4
  */
 package javax.security.auth.login;

src/java.base/share/classes/javax/security/auth/x500/X500Principal.java

@@ -60,6 +60,14 @@ import sun.security.util.*;
  * {@code X509Certificate} return X500Principals representing the
  * issuer and subject fields of the certificate.
  *
+ * @spec https://www.rfc-editor.org/info/rfc1779
+ *      RFC 1779: A String Representation of Distinguished Names
+ * @spec https://www.rfc-editor.org/info/rfc2253
+ *      RFC 2253: Lightweight Directory Access Protocol (v3):
+ *              UTF-8 String Representation of Distinguished Names
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @see java.security.cert.X509Certificate
  * @since 1.4
  */
@@ -141,6 +149,10 @@ public final class X500Principal implements Principal, java.io.Serializable {
      *                  is {@code null}
      * @exception IllegalArgumentException if the {@code name}
      *                  is improperly specified
+     *
+     * @spec https://www.rfc-editor.org/info/rfc4512
+     *      RFC 4512: Lightweight Directory Access Protocol (LDAP):
+     *              Directory Information Models
      */
     public X500Principal(String name) {
         this(name, Collections.emptyMap());
@@ -181,6 +193,10 @@ public final class X500Principal implements Principal, java.io.Serializable {
      * @exception IllegalArgumentException if the {@code name} is
      *   improperly specified or a keyword in the {@code name} maps to an
      *   OID that is not in the correct form
+     *
+     * @spec https://www.rfc-editor.org/info/rfc4512
+     *      RFC 4512: Lightweight Directory Access Protocol (LDAP):
+     *              Directory Information Models
      * @since 1.6
      */
     public X500Principal(String name, Map<String, String> keywordMap) {

src/java.base/share/classes/javax/security/auth/x500/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2024, 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
@@ -44,6 +44,17 @@
  *     Directory Information Models</a></li>
  * </ul>
  *
+ * @spec https://www.rfc-editor.org/info/rfc1779
+ *      RFC 1779: A String Representation of Distinguished Names
+ * @spec https://www.rfc-editor.org/info/rfc2253
+ *      RFC 2253: Lightweight Directory Access Protocol (v3):
+ *              UTF-8 String Representation of Distinguished Names
+ * @spec https://www.rfc-editor.org/info/rfc4512
+ *      RFC 4512: Lightweight Directory Access Protocol (LDAP):
+ *              Directory Information Models
+ * @spec https://www.rfc-editor.org/info/rfc5280
+ *      RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+ *              and Certificate Revocation List (CRL) Profile
  * @since 1.4
  */
 package javax.security.auth.x500;