4958071: (spec) confusing exception list for javax.crypto.Cipher.init(...) for

Reviewed-by: valeriep, wetmore

src/java.base/share/classes/javax/crypto/Cipher.java

@@ -1239,6 +1239,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Key key) throws InvalidKeyException {
         init(opmode, key, JCAUtil.getDefSecureRandom());
@@ -1294,6 +1296,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Key key, SecureRandom random)
             throws InvalidKeyException
@@ -1379,6 +1383,9 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
+     *
      */
     public final void init(int opmode, Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException
@@ -1441,6 +1448,9 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
+     *
      */
     public final void init(int opmode, Key key, AlgorithmParameterSpec params,
                            SecureRandom random)
@@ -1522,6 +1532,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Key key, AlgorithmParameters params)
             throws InvalidKeyException, InvalidAlgorithmParameterException
@@ -1584,6 +1596,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Key key, AlgorithmParameters params,
                            SecureRandom random)
@@ -1671,6 +1685,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Certificate certificate)
             throws InvalidKeyException
@@ -1740,6 +1756,8 @@ public class Cipher {
      * @throws UnsupportedOperationException if {@code opmode} is
      * {@code WRAP_MODE} or {@code UNWRAP_MODE} but the mode is not implemented
      * by the underlying {@code CipherSpi}
+     * @throws InvalidParameterException if {@code opmode} is not one of the
+     * recognized values
      */
     public final void init(int opmode, Certificate certificate,
                            SecureRandom random)

test/jdk/com/sun/crypto/provider/Cipher/Test4958071.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2022, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @library /test/lib
+ * @bug 4958071
+ * @summary verify InvalidParameterException for Cipher.init
+ */
+
+import jdk.test.lib.Utils;
+
+import javax.crypto.Cipher;
+import javax.crypto.KeyGenerator;
+import javax.crypto.SecretKey;
+import java.security.AlgorithmParameters;
+import java.security.InvalidParameterException;
+import java.security.SecureRandom;
+import java.security.cert.Certificate;
+import java.security.spec.AlgorithmParameterSpec;
+
+public class Test4958071 {
+
+    public boolean execute() throws Exception {
+
+        KeyGenerator aesKey = KeyGenerator.getInstance("AES");
+        aesKey.init(128);
+        SecretKey generatedAESKey = aesKey.generateKey();
+
+        Cipher c = Cipher.getInstance("AES");
+
+        SecureRandom nullSR = null;
+        AlgorithmParameters nullAP = null;
+        AlgorithmParameterSpec nullAPS = null;
+        Certificate nullCert = null;
+
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey, nullAP), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey, nullAP), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey, nullAP, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey, nullAP, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey, nullAPS), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey, nullAPS), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                generatedAESKey, nullAPS, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                generatedAESKey, nullAPS, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                nullCert), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                nullCert), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.ENCRYPT_MODE - 1),
+                nullCert, nullSR), InvalidParameterException.class);
+        Utils.runAndCheckException(() -> c.init((Cipher.UNWRAP_MODE + 1),
+                nullCert, nullSR), InvalidParameterException.class);
+
+        return true;
+    }
+
+    public static void main(String[] args) throws Exception {
+
+        Test4958071 test = new Test4958071();
+
+        if (test.execute()) {
+            System.out.println(test.getClass().getName() + ": passed!");
+        }
+
+    }
+}