8285827: Describe the keystore.pkcs12.legacy system property in the j…

…ava.security file

Reviewed-by: mullan

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

@@ -1166,10 +1166,30 @@ jceks.key.serialFilter = java.base/java.lang.Enum;java.base/java.security.KeyRep
 # If a system property of the same name is also specified, it supersedes the
 # security property value defined here.
 #
-# If the property is set to an illegal value,
-# an iteration count that is not a positive integer, or an unknown algorithm
-# 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.
+# If the property is set to an illegal value, an iteration count that is not
+# a positive integer, or an unknown algorithm 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.
+#
+# Some PKCS12 tools and libraries may not support algorithms based on PBES2
+# and AES. To create a PKCS12 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 (which can
+# only be enabled and has no value) is equivalent to
+#
+#   -Dkeystore.pkcs12.certProtectionAlgorithm=PBEWithSHA1AndRC2_40
+#   -Dkeystore.pkcs12.keyProtectionAlgorithm=PBEWithSHA1AndDESede
+#   -Dkeystore.pkcs12.macAlgorithm=HmacPBESHA1
+#   -Dkeystore.pkcs12.certPbeIterationCount=50000
+#   -Dkeystore.pkcs12.keyPbeIterationCount=50000
+#   -Dkeystore.pkcs12.macIterationCount=100000
+#
+# Also, you can downgrade an existing PKCS12 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.
 #
 # Note: These properties are currently used by the JDK Reference implementation.
 # They are not guaranteed to be examined and used by other implementations.