RFR: 8349946: Cipher javadoc could describe AEAD reuse better

[Anthony Scarpino]

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

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

> 109:  * the {@code update} and {@code doFinal} methods).
> 110:  * <p>
> 111:  * When {@code doFinal} completes the operation, the {@code Cipher} object will attempt

Please change to "{@code doFinal} methods complete"

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} when a reset did not occur.

Please change to "or {@code doFinal} methods when"

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

> 117:  * or {@code doFinal} when a reset did not occur.
> 118:  *
> 119:  * <p><b>Important:</b> Reusing the same IV (nonce) with the same key in AEAD modes like GCM is a serious security risk.

I would remove this, only because it's a broad statement about algorithm security that may not be proper for the javadoc.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2132766944
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2132769581
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2132785620