Deprecate the PSSParameterSpec(int) constructor and DEFAULT static field

Summary

Deprecating the 1-arg constructor and static field "DEFAULT" of the java.security.spec.PSSParameterSpec class since both use most if not all of the default values in the ASN.1 encoding from PKCS #1 standard.

Problem

PSSParameterSpec.DEFAULT is constructed using all the default values in the ASN.1 encoding from PKCS #1 standard and may become obsolete as time progresses. Similarly, PSSParameterSpec(int) constructor uses these default values except for the supplied salt length argument.

This field and constructor uses SHA-1 as the default hash algorithm. Although SHA-1 is the default algorithm as specified by RFC 8017, SHA-1 is weak and not recommended anymore. Using this constructor without understanding the security risks or that SHA-1 is the default is not recommended. Thus, this field and constructor should be deprecated with an appropriate warning.

Solution

Deprecating both the static field and the 1-arg constructor, callers should construct the PSSParameterSpec object with their desired values and algorithms.

Specification

Update the javadoc of java.security.spec.PSSParameterSpec class as below:

1) class description:

@@ -26,15 +26,15 @@
 package java.security.spec;

 import java.util.Objects;

 /**
- * This class specifies a parameter spec for RSASSA-PSS signature scheme,
+ * This class specifies a parameter spec for the RSASSA-PSS signature scheme,
  * as defined in the
  * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard.
  *
- * <p>Its ASN.1 definition in PKCS#1 standard is described below:
+ * <p>Its ASN.1 definition in the PKCS #1 standard is described below:
  * <pre>
  * RSASSA-PSS-params ::= SEQUENCE {
  *   hashAlgorithm      [0] HashAlgorithm      DEFAULT sha1,
  *   maskGenAlgorithm   [1] MaskGenAlgorithm   DEFAULT mgf1SHA1,
  *   saltLength         [2] INTEGER            DEFAULT 20,
@@ -62,16 +62,10 @@
  * PKCS1MGFAlgorithms    ALGORITHM-IDENTIFIER ::= {
  *   { OID id-mgf1 PARAMETERS HashAlgorithm },
  *   ...  -- Allows for future expansion --
  * }
  * </pre>
- * <p>Note: the PSSParameterSpec.DEFAULT uses the following:
- *     message digest  -- "SHA-1"
- *     mask generation function (mgf) -- "MGF1"
- *     parameters for mgf -- MGF1ParameterSpec.SHA1
- *     SaltLength   -- 20
- *     TrailerField -- 1
  *
  * @see MGF1ParameterSpec
  * @see AlgorithmParameterSpec
  * @see java.security.Signature
  *
@@ -92,11 +86,11 @@
     private final int saltLen;

     private final int trailerField;

     /**
-     * The {@code TrailerFieldBC} constant as defined in PKCS#1
+     * The {@code TrailerFieldBC} constant as defined in the PKCS #1 standard.
      *
      * @since 11
      */
     public static final int TRAILER_FIELD_BC = 1;

2) DEFAULT static field description:

@@ -99,14 +93,23 @@
      * @since 11
      */
     public static final int TRAILER_FIELD_BC = 1;

     /**
-     * The PSS parameter set with all default values
+     * The PSS parameter set with all default values.
+     * @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
+     *         <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a>
+     *         standard for more details. Thus, it is recommended to create
+     *         a new {@code PSSParameterSpec} with the desired parameter values
+     *         using the
+     *         {@link #PSSParameterSpec(String, String, AlgorithmParameterSpec, int, int)} constructor.
      *
      * @since 1.5
      */
+    @Deprecated(since="19")
     public static final PSSParameterSpec DEFAULT = new PSSParameterSpec
         ("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, 20, TRAILER_FIELD_BC);

3) PSSParameterSpec(int) constructor description:

@@ -124,11 +127,11 @@
      * @param mdName       the algorithm name of the hash function
      * @param mgfName      the algorithm name of the mask generation function
      * @param mgfSpec      the parameters for the mask generation function.
      *         If null is specified, null will be returned by
      *         getMGFParameters().
-     * @param saltLen      the length of salt
+     * @param saltLen      the length of salt in bytes
      * @param trailerField the value of the trailer field
      * @throws    NullPointerException if {@code mdName}, or {@code mgfName}
      *         is null
      * @throws    IllegalArgumentException if {@code saltLen} or
      *         {@code trailerField} is less than 0

    @@ -155,17 +158,25 @@
         }

         /**
          * Creates a new {@code PSSParameterSpec}
          * using the specified salt length and other default values as
    -     * defined in PKCS#1.
    +     * defined in the PKCS #1 standard.
          *
    -     * @param saltLen the length of salt in bytes to be used in PKCS#1
    -     *         PSS encoding
    +     * @param saltLen the length of salt in bytes
          * @throws    IllegalArgumentException if {@code saltLen} is
          *         less than 0
    +     * @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
    +     *         cryptanalysis -- see the
    +     *         <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a>
    +     *         standard for more details. Thus, it is recommended to explicitly
    +     *         specify all desired parameter values with the
    +     *         {@link #PSSParameterSpec(String, String, AlgorithmParameterSpec, int, int)} constructor.
          */
    +    @Deprecated(since="19")
         public PSSParameterSpec(int saltLen) {
             this("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, saltLen, TRAILER_FIELD_BC);
         }