RFR: 8254935: Deprecate the PSSParameterSpec(int) constructor

[Weijun Wang]

On Wed, 23 Mar 2022 00:29:16 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

> Can someone help review this update to the PSSParameterSpec class regarding the constructor with int argument and the DEFAULT static field? Just added @Deprecate javadoc tag and caution about their usage as suggested in the bug record.
> 
> A CSR will be filed once the wording changes are reviewed.
> 
> Thanks,
> Valerie

src/java.base/share/classes/java/security/spec/PSSParameterSpec.java line 114:

> 112:      *         recommended to explicitly specify all desired parameter
> 113:      *         values with
> 114:      *         {@link #PSSParameterSpec(String, String, AlgorithmParameterSpec, int, int) PSSParameterSpec}.

We are deprecating a field so I would say "This field uses default values defined in ... which may become...".

Do we need to write "PKCS #1" with a blank inside? Same below.

Also, the "all desired parameter values" phrase is perfect for the constructor below but this is for a field not a method so "parameters" does not make sense to me. How about something like "Instead of using this field, user should create a new `PSSParameterSpec` object by calling..." or we can just not mention it. User would need to create one anyway.

src/java.base/share/classes/java/security/spec/PSSParameterSpec.java line 118:

> 116:      * @since 1.5
> 117:      */
> 118:     @Deprecated(since="19", forRemoval=true)

Do we really want to remove it in the future? It's awkward but probably not so harmful. Removing it may unnecessarily break existing codes. Same with the constructor below.

src/java.base/share/classes/java/security/spec/PSSParameterSpec.java line 178:

> 176:      *         less than 0
> 177:      * @deprecated This constructor uses the default values as defined in
> 178:      *         ASN.1 encoding in PKCS#1 except for the salt length. These

Add "the" before "ASN.1 encoding".

src/java.base/share/classes/sun/security/rsa/PSSParameters.java line 83:

> 81:     @Override
> 82:     protected void engineInit(byte[] encoded) throws IOException {
> 83:         // first initialize with the ASN.1 DEFAULT defined in PKCS#1 v2.2

"DEFAULT values"? Also, "PKCS #1".

-------------

PR: https://git.openjdk.java.net/jdk/pull/7913