Summary

Update the specification of KeyAgreement::generateSecret method to clarify the acceptable algorithm name arguments.

Problem

The current specification lacks a description of the valid algorithm names. Additionally, there is undocumented behavior - where the output key material may consist of only partial shared secrets - that needs to be clarified.

Also, the current specification states that a NoSuchAlgorithmException is thrown if the specified algorithm "is not available", which is ambiguous. Update it to “is not supported” for clarity.

Solution

With the proposed new Key Algorithms section in the Java Security Standard Algorithm Names Specification, we can link this method to the section to specify the algorithm names that users can provide. Additionally, we will clarify the potential truncation of the shared secret length to align with the specified algorithm name. An implementation can decide which secret key algorithms from the Key Algorithms section to support and may throw an exception if an unsupported algorithm is specified.

Specification

Apply the following change in javax.crypto.KeyAgreement::generateSecret and javax.crypto.KeyAgreementSpi::engineGenerateSecret methods that accept a String algorithm argument:

-     * @param algorithm the requested secret key algorithm
+     * @param algorithm the requested secret key algorithm. This is different
+     *      from the {@code KeyAgreement} algorithm provided to the
+     *      {@code getInstance} method. 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 the shared secret key
+     * @return the shared secret key. The length of the key material
+     *      may be adjusted to be compatible with the specified algorithm,
+     *      regardless of whether the key is extractable. If {@code algorithm}
+     *      is specified as "Generic" and it is supported by the implementation,
+     *      the full shared secret is returned.
-     * @exception NoSuchAlgorithmException if the requested secret key
-     * algorithm is not available
+     * @exception NoSuchAlgorithmException if the specified secret key
+     * algorithm is not supported
+     * @spec security/standard-names.html Java Security Standard Algorithm Names