8180635: (doc) Clarify the compatibility and interoperability issue when using provider default values

Updated the javadoc of KeyPairGenerator, KeyGenerator, AlgorithmParameterGenerator and their Spi classes

Reviewed-by: mullan

jdk/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java

@@ -61,11 +61,17 @@ import java.util.Objects;
  * </ul>
  *
  * <P>In case the client does not explicitly initialize the
- * AlgorithmParameterGenerator
- * (via a call to an {@code init} method), each provider must supply (and
- * document) a default initialization. For example, the Sun provider uses a
- * default modulus prime size of 1024 bits for the generation of DSA
- * parameters.
+ * AlgorithmParameterGenerator (via a call to an {@code init} method),
+ * each provider must supply (and document) a default initialization.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the AlgorithmParameterGenerator defaults
+ * used by JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * AlgorithmParameterGenerator instead of relying on provider-specific defaults.
  *
  * <p> Every implementation of the Java platform is required to support the
  * following standard {@code AlgorithmParameterGenerator} algorithms and

jdk/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,8 +39,15 @@ import java.security.spec.AlgorithmParameterSpec;
  * <p> In case the client does not explicitly initialize the
  * AlgorithmParameterGenerator (via a call to an {@code engineInit}
  * method), each provider must supply (and document) a default initialization.
- * For example, the Sun provider uses a default modulus prime size of 1024
- * bits for the generation of DSA parameters.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the AlgorithmParameterGenerator defaults
+ * used by JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * AlgorithmParameterGenerator instead of relying on provider-specific defaults.
  *
  * @author Jan Luehe
  *

jdk/src/java.base/share/classes/java/security/KeyPairGenerator.java

@@ -95,8 +95,15 @@ import sun.security.util.Debug;
  * <p>In case the client does not explicitly initialize the KeyPairGenerator
  * (via a call to an {@code initialize} method), each provider must
  * supply (and document) a default initialization.
- * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
- * of 1024 bits for DSA key pairs.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the KeyPairGenerator defaults used by
+ * JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * KeyPairGenerator instead of relying on provider-specific defaults.
  *
  * <p>Note that this class is abstract and extends from
  * {@code KeyPairGeneratorSpi} for historical reasons.

jdk/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,8 +39,15 @@ import java.security.spec.AlgorithmParameterSpec;
  * <p> In case the client does not explicitly initialize the KeyPairGenerator
  * (via a call to an {@code initialize} method), each provider must
  * supply (and document) a default initialization.
- * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
- * of 1024 bits.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the KeyPairGenerator defaults used by
+ * JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * KeyPairGenerator instead of relying on provider-specific defaults.
  *
  * @author Benjamin Renaud
  * @since 1.2

jdk/src/java.base/share/classes/javax/crypto/KeyGenerator.java

@@ -83,6 +83,15 @@ import sun.security.util.Debug;
  * <p>In case the client does not explicitly initialize the KeyGenerator
  * (via a call to an {@code init} method), each provider must
  * supply (and document) a default initialization.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the KeyGenerator defaults used by
+ * JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * KeyGenerator instead of relying on provider-specific defaults.
  *
  * <p> Every implementation of the Java platform is required to support the
  * following standard {@code KeyGenerator} algorithms with the keysizes in

jdk/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,6 +35,19 @@ import java.security.spec.*;
  * cryptographic service provider who wishes to supply the implementation
  * of a key generator for a particular algorithm.
  *
+ * <p>In case the client does not explicitly initialize the KeyGenerator
+ * (via a call to an {@code init} method), each provider must
+ * supply (and document) a default initialization.
+ * See the Keysize Restriction sections of the
+ * <a href="{@docRoot}/../technotes/guides/security/SunProviders.html">
+ * JDK Providers</a>
+ * document for information on the KeyGenerator defaults used by
+ * JDK providers.
+ * However, note that defaults may vary across different providers.
+ * Additionally, the default value for a provider may change in a future
+ * version. Therefore, it is recommended to explicitly initialize the
+ * KeyGenerator instead of relying on provider-specific defaults.
+ *
  * @author Jan Luehe
  *
  * @see SecretKey