RFR: 8349946: Cipher javadoc could describe AEAD reuse better [v2]

[Anthony Scarpino]

On Thu, 12 Jun 2025 17:04:22 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
>
> Koushik Muthukrishnan Thirupattur has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8349946:Cipher javadoc could describe AEAD reuse better

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} methods completes the operation, the {@code Cipher} object will attempt

Rephrasing:  "When a {@code doFinal} method completes ..."

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

> 112:  * to reset the state to the most recent call to {@code init}, allowing for additional
> 113:  * operations. A successful reset depends on the mode ({@code ENCRYPT_MODE} or
> 114:  * {@code DECRYPT_MODE}) and the algorithm. AEAD algorithms may not reset to prevent

rephrase:  replace "to prevent" with ", in order to prevent"

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

> 114:  * {@code DECRYPT_MODE}) and the algorithm. AEAD algorithms may not reset to prevent
> 115:  * forgery attacks due to Key and IV uniqueness requirements.
> 116:  * An {@link IllegalStateException} will be thrown when calling {@code update}

insert a `<p>` at the start of this line to separate the exception explanation.

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. {@code init} may

"methods when a" -> "methods if a"
Also  change the next sentence to:  "A call to {@code init} will reinitialize"

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

> 2087:      *
> 2088:      * @throws IllegalStateException if this {@code Cipher} object
> 2089:      * is in a wrong state or cannot be reset.

We should probably have said "mode", not "state"  .  How about "a wrong state" -> "an incorrect mode".
The others below should be changed as well

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2165205525
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2165207935
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2165205941
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2165215568
PR Review Comment: https://git.openjdk.org/jdk/pull/25399#discussion_r2165219599