From 991ce84e0984414386e2f4dcefecf8da14cc1db3 Mon Sep 17 00:00:00 2001 From: Ben Perez Date: Fri, 6 Oct 2023 03:07:23 +0000 Subject: [PATCH] 4964430: (spec) missing IllegalStateException exception requirement for javax.crypto.Cipher.doFinal Reviewed-by: mullan, valeriep --- .../share/classes/javax/crypto/Cipher.java | 75 +++++++++++-------- .../classes/javax/crypto/NullCipher.java | 6 +- 2 files changed, 49 insertions(+), 32 deletions(-) diff --git a/src/java.base/share/classes/javax/crypto/Cipher.java b/src/java.base/share/classes/javax/crypto/Cipher.java index 3e692b37b79..82242658c64 100644 --- a/src/java.base/share/classes/javax/crypto/Cipher.java +++ b/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 class Cipher { /** * 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 @@ public class Cipher { * 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 class Cipher { * 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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * @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 class Cipher { * * @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 class Cipher { * @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 class Cipher { * {@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 class Cipher { * @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 diff --git a/src/java.base/share/classes/javax/crypto/NullCipher.java b/src/java.base/share/classes/javax/crypto/NullCipher.java index fd240f39156..f1072fb936b 100644 --- a/src/java.base/share/classes/javax/crypto/NullCipher.java +++ b/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 @@ package javax.crypto; * "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