8349946: Cipher javadoc could describe AEAD reuse better

Reviewed-by: ascarpino

Author: koushikthirupattur

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

@@ -96,49 +96,30 @@
  * provide authenticity assurances for both confidential data and
  * Additional Associated Data (AAD) that is not encrypted.  (Please see
  * <a href="http://www.ietf.org/rfc/rfc5116.txt"> RFC 5116 </a> for more
- * information on AEAD and AAD algorithms such as GCM/CCM.) Both
+ * information on AEAD and AAD algorithms.) Both
  * confidential and AAD data can be used when calculating the
  * authentication tag (similar to a {@link Mac}).  This tag is appended
  * to the ciphertext during encryption, and is verified on decryption.
  * <p>
- * AEAD modes such as GCM/CCM perform all AAD authenticity calculations
+ * AEAD modes perform all AAD authenticity calculations
  * before starting the ciphertext authenticity calculations.  To avoid
  * implementations having to internally buffer ciphertext, all AAD data
- * must be supplied to GCM/CCM implementations (via the {@code updateAAD}
+ * must be supplied to their implementations (via the {@code updateAAD}
  * methods) <b>before</b> the ciphertext is processed (via
  * the {@code update} and {@code doFinal} methods).
  * <p>
- * Note that GCM mode has a uniqueness requirement on IVs used in
- * encryption with a given key. When IVs are repeated for GCM
- * encryption, such usages are subject to forgery attacks. Thus, after
- * each encryption operation using GCM mode, callers should re-initialize
- * the {@code Cipher} objects with GCM parameters which have a different IV
- * value.
- * <pre>
- *     GCMParameterSpec s = ...;
- *     cipher.init(..., s);
- *
- *     // If the GCM parameters were generated by the provider, it can
- *     // be retrieved by:
- *     // cipher.getParameters().getParameterSpec(GCMParameterSpec.class);
- *
- *     cipher.updateAAD(...);  // AAD
- *     cipher.update(...);     // Multi-part update
- *     cipher.doFinal(...);    // conclusion of operation
+ * When a {@code doFinal} method completes the operation, the {@code Cipher} object will attempt
+ * to reset the state to the most recent call to {@code init}, allowing for additional
+ * operations. A successful reset depends on the mode ({@code ENCRYPT_MODE} or
+ * {@code DECRYPT_MODE}) and the algorithm. AEAD algorithms may not reset, in order to prevent
+ * forgery attacks due to Key and IV uniqueness requirements.
+ * <p> An {@link IllegalStateException} will be thrown when calling {@code update}
+ * or {@code doFinal} methods if a reset did not occur. A call to {@code init} will
+ * re-initialize the {@code Cipher} object with new parameters.
  *
- *     // Use a different IV value for every encryption
- *     byte[] newIv = ...;
- *     s = new GCMParameterSpec(s.getTLen(), newIv);
- *     cipher.init(..., s);
- *     ...
+ *  @see javax.crypto.Cipher
+ *  @see javax.crypto.spec.GCMParameterSpec
  *
- * </pre>
- * The ChaCha20 and ChaCha20-Poly1305 algorithms have a similar requirement
- * for unique nonces with a given key.  After each encryption or decryption
- * operation, callers should re-initialize their ChaCha20 or ChaCha20-Poly1305
- * ciphers with parameters that specify a different nonce value.  Please
- * see <a href="https://tools.ietf.org/html/rfc7539">RFC 7539</a> for more
- * information on the ChaCha20 and ChaCha20-Poly1305 algorithms.
  * <p>
  * Every implementation of the Java platform is required to support
  * the following standard {@code Cipher} object transformations with
@@ -167,8 +148,6 @@
  *
  * @spec https://www.rfc-editor.org/info/rfc5116
  *      RFC 5116: An Interface and Algorithms for Authenticated Encryption
- * @spec https://www.rfc-editor.org/info/rfc7539
- *      RFC 7539: ChaCha20 and Poly1305 for IETF Protocols
  * @spec security/standard-names.html Java Security Standard Algorithm Names
  * @author Jan Luehe
  * @see KeyGenerator
@@ -2110,21 +2089,10 @@ public final int update(ByteBuffer input, ByteBuffer output)
      * case of decryption.
      * The result is stored in a new buffer.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * @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, or is not
-     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @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
@@ -2224,23 +2192,12 @@ public final int doFinal(byte[] output, int outputOffset)
      * case of decryption.
      * The result is stored in a new buffer.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * @param input the input buffer
      *
      * @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, or is not
-     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @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
@@ -2280,16 +2237,6 @@ public final byte[] doFinal(byte[] input)
      * case of decryption.
      * The result is stored in a new buffer.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * @param input the input buffer
      * @param inputOffset the offset in {@code input} where the input
      * starts
@@ -2298,8 +2245,7 @@ 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, or is not
-     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @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
@@ -2346,16 +2292,6 @@ public final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
      * {@link #getOutputSize(int) getOutputSize} to determine how big
      * the output buffer should be.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * <p>Note: this method should be copy-safe, which means the
      * {@code input} and {@code output} buffers can reference
      * the same byte array and no unprocessed input data is overwritten
@@ -2370,8 +2306,7 @@ 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, or is not
-     * in  or {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @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
@@ -2425,16 +2360,6 @@ public final int doFinal(byte[] input, int inputOffset, int inputLen,
      * {@link #getOutputSize(int) getOutputSize} to determine how big
      * the output buffer should be.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * <p>Note: this method should be copy-safe, which means the
      * {@code input} and {@code output} buffers can reference
      * the same byte array and no unprocessed input data is overwritten
@@ -2451,8 +2376,7 @@ 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, or is not
-     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @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
@@ -2507,16 +2431,6 @@ public final int doFinal(byte[] input, int inputOffset, int inputLen,
      * {@link #getOutputSize(int) getOutputSize} to determine how big
      * the output buffer should be.
      *
-     * <p>Upon finishing, this method resets this {@code Cipher} object
-     * to the state it was in when previously initialized via a call to
-     * {@code init}.
-     * That is, the object is reset and available to encrypt or decrypt
-     * (depending on the operation mode that was specified in the call to
-     * {@code init}) more data.
-     *
-     * <p>Note: if any exception is thrown, this {@code Cipher} object
-     * may need to be reset before it can be used again.
-     *
      * <p>Note: this method should be copy-safe, which means the
      * {@code input} and {@code output} buffers can reference
      * the same byte array and no unprocessed input data is overwritten
@@ -2528,8 +2442,7 @@ 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, or is not
-     * in {@code ENCRYPT_MODE} or {@code DECRYPT_MODE})
+     * is in an incorrect mode or cannot be reset.
      * @throws IllegalArgumentException if input and output are the
      *   same object
      * @throws ReadOnlyBufferException if the output buffer is read-only