RFR: 8285827: Describe the keystore.pkcs12.legacy system property in the java.security file

[Sean Mullan]

On Fri, 29 Apr 2022 13:28:11 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> I think the text above might still make some users concerned that they should always set this property.
>> Maybe we can be less specific, and just say: "If you encounter compatibility issues with software that doesn't support the stronger algorithms, the system property ..."
>
> Can we say both? All these properties are only used when creating the file (key-related ones when creating the key). If a compatibility issue already happens, users need to downgrade their keystore.
> 
> So, the full text will be something like
> 
> Some legacy PKCS #12 tools or libraries do not support the new algorithms based on
> PBES2 and AES. In order to create a PKCS #12 keystore for them, the system property
> "keystore.pkcs12.legacy" can be set which overrides the properties defined here with
> legacy algorithm. Setting this system property is equivalent to
> 
>   ....
> 
> Also, you can downgrade an existing PKCS #12 keystore that already uses new algorithms
> to use legacy algorithms with
> 
>    keytool -J-Dkeystore.pkcs12.legacy -importkeystore -srckeystore ks -destkeystore ks
> 
> This system property should be used at your own risk. Please note there is
> no value defined for this system property, i.e. "-Dkeystore.pkcs12.legacy"
> has the same effect as "-Dkeystore.pkcs12.legacy=<any value>".
> 
> I'll double check if the command can indeed downgrade key algorithms as well. *Update*: it works. All 3 algorithms (key, cert, mac) downgraded to legacy ones.

It's a little long, but I can see why it is useful, so I think it's good. I would avoid the word "new" as this won't be new in a few years time. Here is an edit where I removed words which I thought were not essential:

> Some PKCS #12 tools and libraries may not support algorithms based on PBES2 and AES. 
> To create a PKCS #12 keystore which they can load, set the system property
> "keystore.pkcs12.legacy" which overrides the values of the properties defined below with
> legacy algorithms. Setting this system property is equivalent to
> 
>   ....
> 
> Also, you can downgrade an existing PKCS #12 keystore created with stronger algorithms
> to legacy algorithms with
> 
>    keytool -J-Dkeystore.pkcs12.legacy -importkeystore -srckeystore ks -destkeystore ks
> 
> This system property should be used at your own risk. 

Don't think you really need the sentence below, as you have already given several examples:

> Please note there is
> no value defined for this system property, i.e. "-Dkeystore.pkcs12.legacy"
> has the same effect as "-Dkeystore.pkcs12.legacy=<any value>".

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

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