Summary

Support parameters for the MessageDigest API.

Problem

When MessageDigest were designed, none of the existing algorithms required parameters. This has changed recently. For example, the SHAKE family of message digests allows choosing arbitrary digest output lengths.

Solution

Add new getInstance methods that take an AlgorithmParameterSpec argument. Add a new getParameters method that returns the parameters of a message digest object as an AlgorithmParameters object.

Now that the MessageDigest class contains getInstance methods with params and without params, any invalid argument combination results in a NoSuchMethodException, whether it's because parameters are provided to an implementation that does not require parameters, or no (or illegal) parameters are provided to an implementation that requires parameters. This is consistent to SecureRandom, which is the only other JCA/JCE class that has both styles of constructors.

Implement the SHAKE128-LEN and SHAKE256-LEN message digest algorithms that can be instantiated with an integer as its digest output length in bits -- through a new IntegerParameterSpec object.

Specification

Changes to MessageDigest

Add these new methods:

/**
 * Returns a {@code MessageDigest} object that implements the specified
 * digest algorithm and is initialized with the specified parameters.
 *
 * <p> This method traverses the list of registered security Providers,
 * starting with the most preferred Provider.
 * A new {@code MessageDigest} object encapsulating the
 * {@code MessageDigestSpi} implementation from the first
 * provider that supports the specified algorithm is returned.
 *
 * <p> Note that the list of registered providers may be retrieved via
 * the {@link Security#getProviders() Security.getProviders()} method.
 *
 * @implNote
 * The JDK Reference Implementation additionally uses the
 * {@code jdk.security.provider.preferred}
 * {@link Security#getProperty(String) Security} property to determine
 * the preferred provider order for the specified algorithm. This
 * may be different from the order of providers returned by
 * {@link Security#getProviders() Security.getProviders()}.
 *
 * @param algorithm the name of the algorithm requested.
 * See the MessageDigest section in the <a href=
 * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms">
 * Java Security Standard Algorithm Names Specification</a>
 * for information about standard algorithm names.
 * @param params the initialization parameters (may be {@code null}).
 *
 * @return a {@code MessageDigest} object that implements the
 *         specified algorithm
 *
 * @throws NoSuchAlgorithmException if no {@code Provider} supports a
 *         {@code MessageDigestSpi} implementation for the
 *         specified algorithm and parameters
 *
 * @throws NullPointerException if {@code algorithm} is {@code null}
 *
 * @see Provider
 * @since 22
 */
public static MessageDigest getInstance(String algorithm,
        AlgorithmParameterSpec params)
        throws NoSuchAlgorithmException, InvalidAlgorithmParameterException;


/**
 * Returns a {@code MessageDigest} object that implements the specified
 * digest algorithm and is initialized with the specified parameters.
 *
 * <p> A new {@code MessageDigest} object encapsulating the
 * {@code MessageDigestSpi} implementation from the specified provider
 * is returned.  The specified provider must be registered
 * in the security provider list.
 *
 * <p> Note that the list of registered providers may be retrieved via
 * the {@link Security#getProviders() Security.getProviders()} method.
 *
 * @param algorithm the name of the algorithm requested.
 * See the MessageDigest section in the <a href=
 * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms">
 * Java Security Standard Algorithm Names Specification</a>
 * for information about standard algorithm names.
 * @param params the initialization parameters (may be {@code null}).
 * @param provider the name of the provider.
 *
 * @return a {@code MessageDigest} object that implements the
 *         specified algorithm
 *
 * @throws IllegalArgumentException if the provider name is {@code null}
 *         or empty
 *
 * @throws NoSuchAlgorithmException if a {@code MessageDigestSpi}
 *         implementation for the specified algorithm and parameters
 *         is not available from the specified provider
 *
 * @throws NoSuchProviderException if the specified provider is not
 *         registered in the security provider list
 *
 * @throws NullPointerException if {@code algorithm} is {@code null}
 *
 * @see Provider
 * @since 22
 */
public static MessageDigest getInstance(String algorithm,
        AlgorithmParameterSpec params, String provider)
        throws NoSuchAlgorithmException, InvalidAlgorithmParameterException,
                NoSuchProviderException;

/**
 * Returns a {@code MessageDigest} object that implements the specified
 * digest algorithm and is initialized with the specified parameters.
 *
 * <p> A new {@code MessageDigest} object encapsulating the
 * {@code MessageDigestSpi} implementation from the specified provider
 * is returned.  Note that the specified provider does not
 * have to be registered in the provider list.
 *
 * @param algorithm the name of the algorithm requested.
 * See the MessageDigest section in the <a href=
 * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms">
 * Java Security Standard Algorithm Names Specification</a>
 * for information about standard algorithm names.
 * @param params the initialization parameters (may be {@code null}).
 * @param provider the provider.
 *
 * @return a {@code MessageDigest} object that implements the
 *         specified algorithm
 *
 * @throws IllegalArgumentException if the specified provider is
 *         {@code null}
 *
 * @throws NoSuchAlgorithmException if a {@code MessageDigestSpi}
 *         implementation for the specified algorithm and parameters
 *         is not available from the specified {@code Provider} object
 *
 * @throws NullPointerException if {@code algorithm} is {@code null}
 *
 * @see Provider
 * @since 22
 */
public static MessageDigest getInstance(String algorithm,
        AlgorithmParameterSpec params, Provider provider)
        throws NoSuchAlgorithmException, InvalidAlgorithmParameterException;


/**
 * Returns the parameters used with this {@code MessageDigest} object.
 *
 * <p>The returned parameters may be the same that were used to instantiate
 * this {@code MessageDigest} object, or may contain additional default
 * parameter values used by the underlying message digest implementation.
 * If the required parameters were not supplied and can be generated by
 * the {@code MessageDigest} object, the generated parameters are returned;
 * otherwise {@code null} is returned.
 *
 * <p>If the message digest implementation does not support returning
 * the parameters as {@code AlgorithmParameters}, {@code null} is always
 * returned.
 *
 * @return the parameters used with this {@code MessageDigest} object,
 * or {@code null}.
 *
 * @since 22
 */
public AlgorithmParameters getParameters();

Slight modifications to existing getInstance methods without parameters. Append or the implementation requires parameters to the end of @throws NoSuchAlgorithmException. For example

      * @throws NoSuchAlgorithmException if a {@code MessageDigestSpi}
      *         implementation for the specified algorithm is not
-     *         available from the specified provider
+     *         available from the specified provider or the implementation
+     *         requires parameters

Changes to MessageDigestSpi

Add this paragragh into the class specification:

* <p>If an implementation does not require parameters, it must contain
* a public constructor that takes no argument, and an {@code MessageDigest}
* object must be instantiated with one of the {@code getInstance} methods
* without an {@code AlgorithmParameterSpec} argument. Otherwise, if an
* implementation requires parameters, it must contain a public constructor
* that takes an {@code AlgorithmParameterSpec} argument, and an
* {@code MessageDigest} object must be instantiated with one of the
* {@code getInstance} methods with an {@code AlgorithmParameterSpec} argument.

Add this new method:

/**
 * Returns the parameters used with this {@code MessageDigest} object.
 *
 * <p>The returned parameters may be the same that were used to initialize
 * this {@code MessageDigest} object, or may contain additional default
 * parameter values used by the underlying message digest implementation.
 * If the required parameters were not supplied and can be generated by
 * the {@code MessageDigest} object, the generated parameters are returned;
 * otherwise {@code null} is returned.
 *
 * <p>If the message digest implementation does not support returning
 * the parameters as {@code AlgorithmParameters}, {@code null} is always
 * returned.
 *
 * @return the parameters used with this {@code MessageDigest} object, or
 * {@code null}. If this method is not overridden by a provider,
 * {@code null} is returned.
 *
 * @since 22
 */
protected AlgorithmParameters engineGetParameters();

A New IntegerParameterSpec Class

/**
 * This record class specifies a parameters set that contains an integer.
 *
 * @param n the integer parameter
 * @see AlgorithmParameterSpec
 * @since 22
 */
public record IntegerParameterSpec(int n) implements AlgorithmParameterSpec { }

New MessageDigest and AlgorithmParameters Algorithms

The following algorithms will be added to the MessageDigest section of the Java Security Standard Names document:

SHAKE128:
    SHAKE128 produces a 256 bit digest.

SHAKE128-LEN:
    The digest length of SHAKE128-LEN is customizable with a parameter,
    namely, an `IntegerParameterSpec`.

SHAKE256:
    SHAKE256 produces a 512 bit digest.

SHAKE256-LEN:
    The digest length of SHAKE256-LEN is customizable with a parameter,
    namely, an `IntegerParameterSpec`.

The following algorithm will be added to the AlgorithmParameters section of the Java Security Standard Names document:

SHAKE128-LEN:
    Parameters for use with the SHAKE128-LEN message digest algorithm.

SHAKE256-LEN:
    Parameters for use with the SHAKE256-LEN message digest algorithm.