8346736: Java Security Standard Algorithm Names spec should include key algorithm names

Reviewed-by: mullan, hchao

Author: wangweij

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2025, 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
@@ -120,10 +120,9 @@ public interface Key extends java.io.Serializable {
 
     /**
      * Returns the standard algorithm name for this key. For
-     * example, "DSA" would indicate that this key is a DSA key.
-     * See the key related sections (KeyFactory, KeyGenerator,
-     * KeyPairGenerator, and SecretKeyFactory) in the <a href=
-     * "{@docRoot}/../specs/security/standard-names.html">
+     * example, "RSA" would indicate that this key is an RSA key.
+     * See the Key Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#key-algorithms">
      * Java Security Standard Algorithm Names Specification</a>
      * for information about standard key algorithm names.
      *

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

@@ -74,16 +74,17 @@ public EncodedKeySpec(byte[] encodedKey) {
      *
      * @param encodedKey the encoded key. The contents of the
      * array are copied to protect against subsequent modification.
-     * @param algorithm the algorithm name of the encoded key
-     * See the KeyFactory section in the <a href=
-     * "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
+     * @param algorithm the algorithm name of the encoded key.
+     * See the AsymmetricKey Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
      * Java Security Standard Algorithm Names Specification</a>
-     * for information about standard algorithm names.
+     * for information about standard asymmetric key algorithm names.
      * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @throws NullPointerException if {@code encodedKey}
      * or {@code algorithm} is null.
      * @throws IllegalArgumentException if {@code algorithm} is
      * the empty string {@code ""}
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @since 9
      */
     protected EncodedKeySpec(byte[] encodedKey, String algorithm) {

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

@@ -83,16 +83,17 @@ public PKCS8EncodedKeySpec(byte[] encodedKey) {
      * @param encodedKey the key, which is assumed to be
      * encoded according to the PKCS #8 standard. The contents of
      * the array are copied to protect against subsequent modification.
-     * @param algorithm the algorithm name of the encoded private key
-     * See the KeyFactory section in the <a href=
-     * "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
+     * @param algorithm the algorithm name of the encoded private key.
+     * See the AsymmetricKey Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
      * Java Security Standard Algorithm Names Specification</a>
-     * for information about standard algorithm names.
+     * for information about standard asymmetric key algorithm names.
      * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @throws NullPointerException if {@code encodedKey}
      * or {@code algorithm} is null.
      * @throws IllegalArgumentException if {@code algorithm} is
      * the empty string {@code ""}
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @since 9
      */
     public PKCS8EncodedKeySpec(byte[] encodedKey, String algorithm) {

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

@@ -73,16 +73,17 @@ public X509EncodedKeySpec(byte[] encodedKey) {
      * @param encodedKey the key, which is assumed to be
      * encoded according to the X.509 standard. The contents of the
      * array are copied to protect against subsequent modification.
-     * @param algorithm the algorithm name of the encoded public key
-     * See the KeyFactory section in the <a href=
-     * "{@docRoot}/../specs/security/standard-names.html#keyfactory-algorithms">
+     * @param algorithm the algorithm name of the encoded public key.
+     * See the AsymmetricKey Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#asymmetrickey-algorithms">
      * Java Security Standard Algorithm Names Specification</a>
-     * for information about standard algorithm names.
+     * for information about standard asymmetric key algorithm names.
      * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @throws NullPointerException if {@code encodedKey}
      * or {@code algorithm} is null.
      * @throws IllegalArgumentException if {@code algorithm} is
      * the empty string {@code ""}
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      * @since 9
      */
     public X509EncodedKeySpec(byte[] encodedKey, String algorithm) {

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

@@ -483,7 +483,11 @@ private static KDF handleException(NoSuchAlgorithmException e)
      * Derives a key, returned as a {@code SecretKey} object.
      *
      * @param alg
-     *         the algorithm of the resultant {@code SecretKey} object
+     *         the algorithm of the resultant {@code SecretKey} object.
+     *         See the SecretKey Algorithms section in the
+     *         <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+     *         Java Security Standard Algorithm Names Specification</a>
+     *         for information about standard secret key algorithm names.
      * @param derivationSpec
      *         the object describing the inputs to the derivation function
      *
@@ -500,6 +504,7 @@ private static KDF handleException(NoSuchAlgorithmException e)
      *
      * @see <a href="#DelayedProviderSelection">Delayed Provider
      *         Selection</a>
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      *
      */
     public SecretKey deriveKey(String alg,

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2024, 2025, 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
@@ -115,7 +115,11 @@ protected KDFSpi(KDFParameters kdfParameters)
      *         result of {@code deriveData}.
      *
      * @param alg
-     *         the algorithm of the resultant {@code SecretKey} object
+     *         the algorithm of the resultant {@code SecretKey} object.
+     *         See the SecretKey Algorithms section in the
+     *         <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+     *         Java Security Standard Algorithm Names Specification</a>
+     *         for information about standard secret key algorithm names.
      * @param derivationSpec
      *         derivation parameters
      *
@@ -129,6 +133,7 @@ protected KDFSpi(KDFParameters kdfParameters)
      *         if {@code alg} is empty or invalid
      * @throws NullPointerException
      *         if {@code alg} or {@code derivationSpec} is null
+     * @spec security/standard-names.html Java Security Standard Algorithm Names
      */
     protected abstract SecretKey engineDeriveKey(String alg,
                                                  AlgorithmParameterSpec derivationSpec)
@@ -154,4 +159,4 @@ protected abstract byte[] engineDeriveData(
             AlgorithmParameterSpec derivationSpec)
             throws InvalidAlgorithmParameterException;
 
-}
+}

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

@@ -222,7 +222,13 @@ public Encapsulated encapsulate() {
          *          to be returned, inclusive
          * @param to the final index of the shared secret byte array
          *          to be returned, exclusive
-         * @param algorithm the algorithm name for the secret key that is returned
+         * @param algorithm the algorithm name for the secret key that is returned.
+         *          See the SecretKey Algorithms section in the
+         *          <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+         *          Java Security Standard Algorithm Names Specification</a>
+         *          for information about standard secret key algorithm names.
+         *          Specify "Generic" if the output will be used as the input keying
+         *          material of a key derivation function (KDF).
          * @return a {@link Encapsulated} object containing a portion of
          *          the shared secret, key encapsulation message, and optional
          *          parameters. The portion of the shared secret is a
@@ -237,6 +243,7 @@ public Encapsulated encapsulate() {
          * @throws UnsupportedOperationException if the combination of
          *          {@code from}, {@code to}, and {@code algorithm}
          *          is not supported by the encapsulator
+         * @spec security/standard-names.html Java Security Standard Algorithm Names
          */
         public Encapsulated encapsulate(int from, int to, String algorithm) {
             return e.engineEncapsulate(from, to, algorithm);
@@ -345,7 +352,13 @@ public SecretKey decapsulate(byte[] encapsulation) throws DecapsulateException {
          *          to be returned, inclusive
          * @param to the final index of the shared secret byte array
          *          to be returned, exclusive
-         * @param algorithm the algorithm name for the secret key that is returned
+         * @param algorithm the algorithm name for the secret key that is returned.
+         *          See the SecretKey Algorithms section in the
+         *          <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+         *          Java Security Standard Algorithm Names Specification</a>
+         *          for information about standard secret key algorithm names.
+         *          Specify "Generic" if the output will be used as the input keying
+         *          material of a key derivation function (KDF).
          * @return a portion of the shared secret as a {@code SecretKey}
          *          containing the bytes of the secret ranging from {@code from}
          *          to {@code to}, exclusive, and an algorithm name as specified.
@@ -361,6 +374,7 @@ public SecretKey decapsulate(byte[] encapsulation) throws DecapsulateException {
          * @throws UnsupportedOperationException if the combination of
          *          {@code from}, {@code to}, and {@code algorithm}
          *          is not supported by the decapsulator
+         * @spec security/standard-names.html Java Security Standard Algorithm Names
          */
         public SecretKey decapsulate(byte[] encapsulation,
                 int from, int to, String algorithm)

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2025, 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
@@ -129,7 +129,13 @@ interface EncapsulatorSpi {
          *          to be returned, inclusive
          * @param to the final index of the shared secret byte array
          *          to be returned, exclusive
-         * @param algorithm the algorithm name for the secret key that is returned
+         * @param algorithm the algorithm name for the secret key that is returned.
+         *          See the SecretKey Algorithms section in the
+         *          <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+         *          Java Security Standard Algorithm Names Specification</a>
+         *          for information about standard secret key algorithm names.
+         *          Specify "Generic" if the output will be used as the input keying
+         *          material of a key derivation function (KDF).
          * @return an {@link KEM.Encapsulated} object containing a portion of
          *          the shared secret as a key with the specified algorithm,
          *          key encapsulation message, and optional parameters.
@@ -141,6 +147,7 @@ interface EncapsulatorSpi {
          *          is not supported by the encapsulator
          * @see KEM.Encapsulated
          * @see KEM.Encapsulator#encapsulate(int, int, String)
+         * @spec security/standard-names.html Java Security Standard Algorithm Names
          */
         KEM.Encapsulated engineEncapsulate(int from, int to, String algorithm);
 
@@ -188,7 +195,13 @@ interface DecapsulatorSpi {
          *          to be returned, inclusive
          * @param to the final index of the shared secret byte array
          *          to be returned, exclusive
-         * @param algorithm the algorithm name for the secret key that is returned
+         * @param algorithm the algorithm name for the secret key that is returned.
+         *          See the SecretKey Algorithms section in the
+         *          <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+         *          Java Security Standard Algorithm Names Specification</a>
+         *          for information about standard secret key algorithm names.
+         *          Specify "Generic" if the output will be used as the input keying
+         *          material of a key derivation function (KDF).
          * @return a portion of the shared secret as a {@code SecretKey} with
          *          the specified algorithm
          * @throws DecapsulateException if an error occurs during the
@@ -201,6 +214,7 @@ interface DecapsulatorSpi {
          *          {@code from}, {@code to}, and {@code algorithm}
          *          is not supported by the decapsulator
          * @see KEM.Decapsulator#decapsulate(byte[], int, int, String)
+         * @spec security/standard-names.html Java Security Standard Algorithm Names
          */
         SecretKey engineDecapsulate(byte[] encapsulation, int from, int to, String algorithm)
                 throws DecapsulateException;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2025, 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
@@ -93,9 +93,10 @@ public class SecretKeySpec implements KeySpec, SecretKey {
      * the array are copied to protect against subsequent modification.
      * @param algorithm the name of the secret-key algorithm to be associated
      * with the given key material.
-     * See the <a href="{@docRoot}/../specs/security/standard-names.html">
-     * Java Security Standard Algorithm Names</a> document
-     * for information about standard algorithm names.
+     * See the SecretKey Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+     * Java Security Standard Algorithm Names Specification</a>
+     * for information about standard secret key algorithm names.
      * @exception IllegalArgumentException if <code>algorithm</code>
      * is null or <code>key</code> is null or empty.
      *
@@ -137,9 +138,10 @@ public SecretKeySpec(byte[] key, String algorithm) {
      * @param len the length of the key material.
      * @param algorithm the name of the secret-key algorithm to be associated
      * with the given key material.
-     * See the <a href="{@docRoot}/../specs/security/standard-names.html">
-     * Java Security Standard Algorithm Names</a> document
-     * for information about standard algorithm names.
+     * See the SecretKey Algorithms section in the
+     * <a href="{@docRoot}/../specs/security/standard-names.html#secretkey-algorithms">
+     * Java Security Standard Algorithm Names Specification</a>
+     * for information about standard secret key algorithm names.
      * @exception IllegalArgumentException if <code>algorithm</code>
      * is null or <code>key</code> is null, empty, or too short,
      * i.e. {@code key.length-offset<len}.