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

[Weijun Wang]

On Fri, 29 Apr 2022 20:35:14 GMT, Sean Mullan <mullan at openjdk.org> wrote:

>> 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>".

The reason I added the last sentence is because this property has no value. Someone might think they can set it to false to disable it, but that is equivalent to set it to true.

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

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