8180635: (doc) Clarify the compatibility and interoperability issue when using provider default values
authorvaleriep
Thu, 01 Jun 2017 03:26:30 +0000
changeset 45435 7a91c865edd4
parent 45434 4582657c7260
child 45436 152ed642e379
8180635: (doc) Clarify the compatibility and interoperability issue when using provider default values Summary: updated the javadoc of KeyPairGenerator, KeyGenerator, AlgorithmParameterGenerator and their Spi classes Reviewed-by: mullan
jdk/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java
jdk/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java
jdk/src/java.base/share/classes/java/security/KeyPairGenerator.java
jdk/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java
jdk/src/java.base/share/classes/javax/crypto/KeyGenerator.java
jdk/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java
--- a/jdk/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java	Thu Jun 01 03:26:30 2017 +0000
@@ -61,11 +61,17 @@
  * </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
--- a/jdk/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/AlgorithmParameterGeneratorSpi.java	Thu Jun 01 03:26:30 2017 +0000
@@ -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 @@
  * <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
  *
--- a/jdk/src/java.base/share/classes/java/security/KeyPairGenerator.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/KeyPairGenerator.java	Thu Jun 01 03:26:30 2017 +0000
@@ -95,8 +95,15 @@
  * <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.
--- a/jdk/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/security/KeyPairGeneratorSpi.java	Thu Jun 01 03:26:30 2017 +0000
@@ -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 @@
  * <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
--- a/jdk/src/java.base/share/classes/javax/crypto/KeyGenerator.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/KeyGenerator.java	Thu Jun 01 03:26:30 2017 +0000
@@ -83,6 +83,15 @@
  * <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
--- a/jdk/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java	Wed May 31 19:54:16 2017 -0700
+++ b/jdk/src/java.base/share/classes/javax/crypto/KeyGeneratorSpi.java	Thu Jun 01 03:26:30 2017 +0000
@@ -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 @@
  * 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