Summary

Add a new "Key Algorithms" section into the Java Security Standard Algorithm Names Specification. Add a new algorithm name "Generic" into the new section.

Problem

The Java Security Standard Algorithm Names Specification has traditionally been organized by JCA/JCE services, such as KeyFactory and Signature, for their getInstance methods. However, there has been no dedicated section for listing standard key algorithm names.

This omission creates ambiguity when specifying algorithm names in contexts outside getInstance methods. For example:

1. When creating a SecretKeySpec, the specification vaguely points to the document without specifying which part to reference for valid algorithm names.
2. When using KeyAgreement to generate a shared secret key, the specification does not clarify what value the key algorithm should take.

Additionally, recent additions like KEM and KDF (introduced in preview as of JDK 24) describe "Generic" secret keys used as KEM output and KDF input. These keys are not used for cryptographic operations but serve as input keying material for a KDF. The algorithm name for such keys also needs to be defined explicitly in the specification. This is especially useful in PKCS #11 security providers since key usages are restricted by their algorithms and the algorithm names must be specified precisely.

Solution

Add a new section named "Key Algorithms" into the Java Security Standard Algorithm Names Specification. It contains two sub-sections: "SecretKey Algorithms" and "AsymmetricKey Algorithms".

Add a new algorithm name "Generic" into the "SecretKey Algorithms" sub-section.

Add links to this section in multiple places inside JDK where key algorithms need to be specified.

Add a new algorithm name "Generic" into the "SecretKeyFactory Algorithms" sub-section to describe its usage in a PKCS #11 provider and possible abuse.

Note: change to the KeyAgreement API involve behavior change and they are addressed in JDK-8189441 with a separate CSR.

Specification

First, add a new section in the Java Security Standard Algorithm Names Specification:

## `Key` Algorithms

The algorithm names returned by `Key.getAlgorithm()`.

**Note:** The algorithm names of keys generated or created by the
`KeyFactory`, `SecretKeyFactory`, `KeyGenerator`, or `KeyPairGenerator` APIs
should use the standard names listed below, even if an alias or a standard
parameter set name was used to instantiate the service. For example,
`KeyPairGenerator.getInstance("DiffieHellman")` should generate a key with
the "DH" algorithm name, and `KeyPairGenerator.getInstance("ML-KEM-768")`
should generate a key with the "ML-KEM" algorithm name. However, some
third-party providers may use the alias or a non-standard name as the
algorithm name.

### `SecretKey` Algorithms

----------------------------------  ------------------------------------------------------
Algorithm Name                      Description
----------------------------------  ------------------------------------------------------
AES                                 The Advanced Encryption Standard (AES) algorithm.

ARCFOUR                             The ARCFOUR (RC4) algorithm.

Blowfish                            The Blowfish algorithm.

ChaCha20                            The ChaCha20 algorithm.

DES                                 The Data Encryption Standard (DES) algorithm.

DESede                              The Triple Data Encryption Algorithm
                                    (DESede or Triple-DES).

Generic                             This algorithm defines a general-purpose secret key.
                                    This key is not intended to be used for cryptographic
                                    operations; rather it is typically used as input keying
                                    material for deriving other keys. This algorithm is
                                    also used to represent PKCS #11 generic secret key
                                    objects (key type CKK_GENERIC_SECRET_TYPE).

PBEWith\<digest\>And\<encryption\>\ PKCS \#5 password-based encryption, where
PBEWith\<prf\>And\<encryption\>     \<digest\> is a message digest, \<prf\>
                                    is a pseudo-random function, and
                                    \<encryption\> is an encryption
                                    algorithm.
                                    Examples: **PBEWithMD5AndDES**,
                                    and **PBEWithHmacSHA256AndAES**.

PBKDF2With\<prf\>                   Password-based key-derivation algorithm
                                    defined in [PKCS \#5: Password-Based
                                    Cryptography Specification, Version 2.1](
                                    https://tools.ietf.org/html/rfc8018)
                                    using the specified pseudo-random
                                    function (\<prf\>). Example:
                                    **PBKDF2WithHmacSHA256**.

RC2                                 The RC2 algorithm.
----------------------------------  ------------------------------------------------------

### `AsymmetricKey` Algorithms

----------------------------------  ------------------------------------------------------
Algorithm Name                      Description
----------------------------------  ------------------------------------------------------
DH                                  The Diffie-Hellman KeyAgreement algorithm.

DSA                                 The (original) Digital Signature Algorithm.

EC                                  The Elliptic Curve algorithm.

EdDSA                               The Edwards-Curve signature algorithm with
                                    elliptic curves as defined in
                                    [RFC 8032](https://tools.ietf.org/html/rfc8032).

HSS/LMS                             The Leighton-Micali Signature (LMS) system with
                                    the Hierarchical Signature System (HSS) as defined in
                                    [RFC 8554](https://tools.ietf.org/html/rfc8554).

ML-DSA                              The Module-Lattice-Based Digital Signature Algorithm
                                    (ML-DSA) as defined in
                                    [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final).

ML-KEM                              The Module-Lattice-Based Key-Encapsulation Mechanism
                                    (ML-KEM) as defined in
                                    [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final).

RSA                                 The Rivest-Shamir-Adleman (RSA) algorithm.

RSASSA-PSS                          The RSA Signature Scheme with Appendix -
                                    Probabilistic Signature Scheme
                                    (RSASSA-PSS) signature algorithm.

XDH                                 The Diffie-Hellman key agreement with
                                    elliptic curves as defined in
                                    [RFC 7748](https://tools.ietf.org/html/rfc7748).
----------------------------------  ------------------------------------------------------

Add a new row into the "SecretKeyFactory Algorithms" table, which looks like

Generic                               Constructs general-purpose secret keys.
                                      This `SecretKeyFactory` is primarily useful when
                                      working with hardware-based security modules or
                                      PKCS #11 tokens where keys are non-extractable.
                                      For PKCS#11, these are CKK_GENERIC_SECRET keys
                                      used for purposes such as Mac algorithms, HKDF
                                      Initial Key Material (IKM), HKDF Salt, and other
                                      cryptographic operations in a PKCS #11 token. \
                                      **Important:** Using this factory in software-based
                                      environments can lead to unexpected behavior.
                                      If the provider is PKCS #11, the key created may
                                      not be extractable and could fail when used with
                                      software-based cryptographic operations. For most
                                      software-based security providers, creating
                                      a `SecretKeySpec` object is a safer and more
                                      convenient option.

We also want to take this chance to add a note to the "KeyPairGenerator Algorithms", which looks like

**Note:** For `KeypairGenerator` algorithms that use `NamedParameterSpec` names,
the `key.getAlgorithm()` for generated keys will return the "family" algorithm
name instead of the specific parameter set name. For example,
`KeyPairGenerator.getInstance("ML-KEM-768")` will generate a key with the
algorithm name "ML-KEM".

Second, update the specification of the following JDK APIs to link to the new sections. A @spec security/standard-names.html Java Security Standard Algorithm Names tag will also be added to each method that does not currently have such tag.

1. java.security.Key::getAlgorithm:

   * Returns the standard algorithm name for this key. For
   * 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.

2. java.security.spec.EncodedKeySpec, java.security.spec.PKCS8EncodedKeySpec, and java.security.spec.X509EncodedKeySpec. In all three classes where the constructor takes a String algorithm argument:

   * @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 asymmetric key algorithm names.

3. In javax.crypto.KDF::deriveKey and javax.crypto.KDFSpi::engineDeriveKey where there is a String alg argument:

   * @param alg
   *         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.

4. In javax.crypto.spec.SecretKeySpec for the 2 constructors that take a String algorithm argument:

   * @param algorithm the name of the secret-key algorithm to be associated
   * with the given key material.
   * 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.

5. In javax.crypto.KEM$Encapsulator::encapsulate, javax.crypto.KEM$Decapsulator::decapsulate, javax.crypto.KEMSpi$EncapsulatorSpi::engineEncapsulate, and javax.crypto.KEMSpi$DecapsulatorSpi::engineDecapsulate that take a String algorithm argument:

   * @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).