4964430: (spec) missing IllegalStateException exception requirement for javax.crypto.Cipher.doFinal

Reviewed-by: mullan, valeriep

Author: blperez01

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, 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
@@ -1815,8 +1815,8 @@ public final void init(int opmode, Certificate certificate,
 
     /**
      * Ensures that {@code Cipher} object is in a valid state for update() and
-     * doFinal() calls - should be initialized and in ENCRYPT_MODE or
-     * DECRYPT_MODE.
+     * doFinal() calls - should be initialized and in {@code ENCRYPT_MODE} or
+     * {@code DECRYPT_MODE}.
      * @throws IllegalStateException if this {@code Cipher} object is not in
      * valid state
      */
@@ -1851,7 +1851,8 @@ private void checkCipherState() {
      * new block
      *
      * @throws IllegalStateException if this {@code Cipher} object is in a
-     * wrong state (e.g., has not been initialized)
+     * wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      */
     public final byte[] update(byte[] input) {
         checkCipherState();
@@ -1890,7 +1891,8 @@ public final byte[] update(byte[] input) {
      * new block.
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      */
     public final byte[] update(byte[] input, int inputOffset, int inputLen) {
         checkCipherState();
@@ -1940,7 +1942,8 @@ public final byte[] update(byte[] input, int inputOffset, int inputLen) {
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws ShortBufferException if the given output buffer is too small
      * to hold the result
      */
@@ -1998,7 +2001,8 @@ public final int update(byte[] input, int inputOffset, int inputLen,
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws ShortBufferException if the given output buffer is too small
      * to hold the result
      */
@@ -2052,7 +2056,8 @@ public final int update(byte[] input, int inputOffset, int inputLen,
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalArgumentException if input and output are the
      *   same object
      * @throws ReadOnlyBufferException if the output buffer is read-only
@@ -2104,7 +2109,8 @@ public final int update(ByteBuffer input, ByteBuffer output)
      * @return the new buffer with the result
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2161,7 +2167,8 @@ public final byte[] doFinal()
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     *  is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2218,7 +2225,8 @@ public final int doFinal(byte[] output, int outputOffset)
      * @return the new buffer with the result
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2276,7 +2284,8 @@ public final byte[] doFinal(byte[] input)
      * @return the new buffer with the result
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2347,7 +2356,8 @@ public final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in  or {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2427,7 +2437,8 @@ public final int doFinal(byte[] input, int inputOffset, int inputLen,
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalBlockSizeException if this cipher is a block cipher,
      * no padding has been requested (only in encryption mode), and the total
      * input length of the data processed by this cipher is not a multiple of
@@ -2503,7 +2514,8 @@ public final int doFinal(byte[] input, int inputOffset, int inputLen,
      * @return the number of bytes stored in {@code output}
      *
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized)
+     * is in a wrong state (e.g., has not been initialized, or is not
+     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
      * @throws IllegalArgumentException if input and output are the
      *   same object
      * @throws ReadOnlyBufferException if the output buffer is read-only
@@ -2551,7 +2563,7 @@ public final int doFinal(ByteBuffer input, ByteBuffer output)
      * @return the wrapped key
      *
      * @throws IllegalStateException if this {@code Cipher} object is in a wrong
-     * state (e.g., has not been initialized)
+     * state (e.g., has not been initialized, or is not in {@code WRAP_MODE})
      *
      * @throws IllegalBlockSizeException if this cipher is a block
      * cipher, no padding has been requested, and the length of the
@@ -2595,8 +2607,8 @@ public final byte[] wrap(Key key)
      *
      * @return the unwrapped key
      *
-     * @throws IllegalStateException if this {@code Cipher} object
-     *  is in a wrong state (e.g., has not been initialized)
+     * @throws IllegalStateException if this {@code Cipher} object is in a wrong
+     * state (e.g., has not been initialized, or is not in {@code UNWRAP_MODE})
      *
      * @throws NoSuchAlgorithmException if no installed providers
      * can create keys of type {@code wrappedKeyType} for the
@@ -2732,10 +2744,11 @@ public static final AlgorithmParameterSpec getMaxAllowedParameterSpec(
      * @throws IllegalArgumentException if the {@code src}
      * byte array is {@code null}
      * @throws IllegalStateException if this {@code Cipher} object
-     *  is in a wrong state (e.g., has not been initialized),
-     * does not accept AAD, or if operating in either GCM or CCM mode and
-     * one of the {@code update} methods has already been called for the active
-     * encryption/decryption operation
+     * is in a wrong state (e.g., has not been initialized, or is not in
+     * {@code ENCRYPT_MODE} or {@code DECRYPT_MODE}), does not accept AAD,
+     * or if operating in either GCM or CCM mode and one of the {@code update}
+     * methods has already been called for the active encryption/decryption
+     * operation
      * @throws UnsupportedOperationException if the corresponding method
      * in the {@code CipherSpi} has not been overridden by an
      * implementation
@@ -2770,10 +2783,11 @@ public final void updateAAD(byte[] src) {
      * {@code len} is greater than the length of the
      * {@code src} byte array
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized),
-     * does not accept AAD, or if operating in either GCM or CCM mode and
-     * one of the {@code update} methods has already been called for the active
-     * encryption/decryption operation
+     * is in a wrong state (e.g., has not been initialized, or is not in
+     * {@code ENCRYPT_MODE} or {@code DECRYPT_MODE}), does not accept AAD,
+     * or if operating in either GCM or CCM mode and one of the {@code update}
+     * methods has already been called for the active encryption/decryption
+     * operation
      * @throws UnsupportedOperationException if the corresponding method
      * in the {@code CipherSpi} has not been overridden by an
      * implementation
@@ -2816,10 +2830,11 @@ public final void updateAAD(byte[] src, int offset, int len) {
      * @throws IllegalArgumentException if the {@code src ByteBuffer}
      * is {@code null}
      * @throws IllegalStateException if this {@code Cipher} object
-     * is in a wrong state (e.g., has not been initialized),
-     * does not accept AAD, or if operating in either GCM or CCM mode and
-     * one of the {@code update} methods has already been called for the active
-     * encryption/decryption operation
+     * is in a wrong state (e.g., has not been initialized, or is not in
+     * {@code ENCRYPT_MODE} or {@code DECRYPT_MODE}), does not accept AAD,
+     * or if operating in either GCM or CCM mode and one of the {@code update}
+     * methods has already been called for the active encryption/decryption
+     * operation
      * @throws UnsupportedOperationException if the corresponding method
      * in the {@code CipherSpi} has not been overridden by an
      * implementation

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, 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
@@ -30,7 +30,9 @@
  * "identity cipher" -- one that does not transform the plain text.  As
  * a consequence, the ciphertext is identical to the plaintext.  All
  * initialization methods do nothing, while the blocksize is set to 1
- * byte.
+ * byte.  Unlike other ciphers, the {@code NullCipher} has no state, and
+ * will never throw an {@code IllegalStateException} when {@code Cipher}
+ * methods are called.
  *
  * @author  Li Gong
  * @since 1.4