RFR: 8349946: Cipher javadoc could describe AEAD reuse better

[Sebastian Stenzel]

On Thu, 22 May 2025 19:30:44 GMT, Koushik Muthukrishnan Thirupattur <duke at openjdk.org> wrote:

> The class documentation in javax.crypto.Cipher could better describe AEAD and reuse. The current class description example is outdated as GCM encryption does not allow resets. The doc should state that reset() may not be possible with some algorithms or providers and that an InvalidAlgorithmParameterException is thrown

Changes requested by overheadhunter at github.com (no known OpenJDK username).

src/java.base/share/classes/javax/crypto/Cipher.java line 117:

> 115:  * forgery attacks due to Key and IV uniqueness requirements.
> 116:  * An {@link IllegalStateException} will be thrown when calling {@code update}
> 117:  * or {@code doFinal} methods when a reset did not occur.

It might be helpful to describe what to do instead:

When reset is not possible, you don't need to dispose the cipher object. Instead you can call init again with a different key/nonce.

-------------

PR Review: https://git.openjdk.org/jdk/pull/25399#pullrequestreview-2906814350
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2133386033