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

wangweij · 2022-04-28T14:35:54Z

We added a new system property back in https://bugs.openjdk.java.net/browse/JDK-8153005 but it's better to describe it in the java.security file as well.

Please review the text. I especially added the last sentence so that people won't set -Dkeystore.pkcs12.legacy=false.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

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

Reviewers

Sean Mullan (@seanjmullan - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/8452/head:pull/8452
$ git checkout pull/8452

Update a local copy of the PR:
$ git checkout pull/8452
$ git pull https://git.openjdk.java.net/jdk pull/8452/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 8452

View PR using the GUI difftool:
$ git pr show -t 8452

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/8452.diff

bridgekeeper · 2022-04-28T14:36:36Z

👋 Welcome back weijun! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2022-04-28T14:39:24Z

@wangweij The following label will be automatically applied to this pull request:

security

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2022-04-28T14:44:04Z

Webrevs

01: Full - Incremental (8a24c745)
00: Full (08700389)

seanjmullan · 2022-04-28T19:48:38Z

src/java.base/share/conf/security/java.security

@@ -1171,6 +1171,19 @@ jceks.key.serialFilter = java.base/java.lang.Enum;java.base/java.security.KeyRep
 # name, an exception will be thrown when the property is used.
 # If the property is not set or empty, a default value will be used.
 #
+# For compatibility, the system property "keystore.pkcs12.legacy" can be set


Was wondering if we should add why you might want to set this property, ex: "For compatibility with JDK or PKCS12 implementations that do not support the stronger algorithms ..."

Compatibility with prior JDK versions should be less of an issue over time as these stronger settings and algs have been backported to prior JDKs.

OpenSSL's help page shows

-legacy Use legacy encryption: 3DES_CBC for keys, RC2_CBC for certs

Can we also say "To work with legacy PKCS #12 files"?

But isn't it mostly an issue when creating new keystores and not reading existing ones? I would want to avoid users thinking that they had to set this in more cases than needed.

How about this?

To work with legacy PKCS #12 tools that does not support the new algorithms, the system property "keystore.pkcs12.legacy" can be set which will override the properties defined here with old settings. This system property is equivalent to

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

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.

Ah I see. Maybe put in the previous sentence, ex: "When set, this system property (which can only be enabled and has no value) is equivalent to:"

Just a suggestion.

Suggested accepted. I just pushed a new commit. I modified "PKCS #12" to "PKCS12" because that's the word we used throughout the file.

openjdk · 2022-05-02T13:25:25Z

@wangweij This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: mullan

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 51 new commits pushed to the master branch:

7020595: 8284435: Add dedicated filler objects for known dead Java heap areas
1f9f873: 8285980: Several tests in compiler/c2/irTests miss @requires vm.compiler2.enabled
cf81f6c: 8285712: LogMessageBuffer doesn't check vsnprintf return value
9795ef5: 8285851: Cleanup C2AtomicParseAccess::needs_pinning()
3eb661b: 8285890: Fix some @param tags
d9541c5: 8276202: LogFileOutput.invalid_file_vm asserts when being executed from a read only working directory
df7fba1: 8284981: Support the vectorization of some counting-down loops in SLP
e54f26a: 8284992: Fix misleading Vector API doc for LSHR operator
2dd882a: 8254759: [TEST_BUG] [macosx] javax/swing/JInternalFrame/4202966/IntFrameCoord.html fails
23f022b: 8285945: [BACKOUT] JDK-8285802 AArch64: Consistently handle offsets in MacroAssembler as 64-bit quantities
... and 41 more: https://git.openjdk.java.net/jdk/compare/c1173c24bff271e26013126ff1746c480e2fe1a9...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

wangweij · 2022-05-02T14:01:29Z

/integrate

openjdk · 2022-05-02T14:03:40Z

Going to push as commit cfcba1f.
Since your change was applied there have been 51 commits pushed to the master branch:

7020595: 8284435: Add dedicated filler objects for known dead Java heap areas
1f9f873: 8285980: Several tests in compiler/c2/irTests miss @requires vm.compiler2.enabled
cf81f6c: 8285712: LogMessageBuffer doesn't check vsnprintf return value
9795ef5: 8285851: Cleanup C2AtomicParseAccess::needs_pinning()
3eb661b: 8285890: Fix some @param tags
d9541c5: 8276202: LogFileOutput.invalid_file_vm asserts when being executed from a read only working directory
df7fba1: 8284981: Support the vectorization of some counting-down loops in SLP
e54f26a: 8284992: Fix misleading Vector API doc for LSHR operator
2dd882a: 8254759: [TEST_BUG] [macosx] javax/swing/JInternalFrame/4202966/IntFrameCoord.html fails
23f022b: 8285945: [BACKOUT] JDK-8285802 AArch64: Consistently handle offsets in MacroAssembler as 64-bit quantities
... and 41 more: https://git.openjdk.java.net/jdk/compare/c1173c24bff271e26013126ff1746c480e2fe1a9...master

Your commit was automatically rebased without conflicts.

openjdk · 2022-05-02T14:03:54Z

@wangweij Pushed as commit cfcba1f.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

add description

0870038

openjdk bot added the rfr Pull request is ready for review label Apr 28, 2022

openjdk bot added the security security-dev@openjdk.org label Apr 28, 2022

seanjmullan reviewed Apr 28, 2022

View changes

clearer text

8a24c74

seanjmullan approved these changes May 2, 2022

View changes

openjdk bot added the ready Pull request is ready to be integrated label May 2, 2022

openjdk bot added the integrated Pull request has been integrated label May 2, 2022

openjdk bot closed this May 2, 2022

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels May 2, 2022

wangweij deleted the 8285827 branch May 2, 2022 14:16

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

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

wangweij commented Apr 28, 2022 •

edited by openjdk bot

bridgekeeper bot commented Apr 28, 2022

openjdk bot commented Apr 28, 2022

mlbridge bot commented Apr 28, 2022 •

edited

seanjmullan Apr 28, 2022

wangweij Apr 28, 2022

seanjmullan Apr 28, 2022

wangweij Apr 28, 2022 •

edited

seanjmullan Apr 29, 2022

wangweij Apr 29, 2022 •

edited

seanjmullan Apr 29, 2022

wangweij Apr 29, 2022

seanjmullan Apr 29, 2022

wangweij Apr 29, 2022

openjdk bot commented May 2, 2022

wangweij commented May 2, 2022

openjdk bot commented May 2, 2022

openjdk bot commented May 2, 2022

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

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

Conversation

wangweij commented Apr 28, 2022 • edited by openjdk bot

Progress

Issue

Reviewers

Reviewing

bridgekeeper bot commented Apr 28, 2022

openjdk bot commented Apr 28, 2022

mlbridge bot commented Apr 28, 2022 • edited

Webrevs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wangweij Apr 28, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wangweij Apr 29, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openjdk bot commented May 2, 2022

wangweij commented May 2, 2022

openjdk bot commented May 2, 2022

openjdk bot commented May 2, 2022

wangweij commented Apr 28, 2022 •

edited by openjdk bot

mlbridge bot commented Apr 28, 2022 •

edited

wangweij Apr 28, 2022 •

edited

wangweij Apr 29, 2022 •

edited