On Thu, 12 Jun 2025 17:04:22 GMT, Koushik Muthukrishnan Thirupattur
<[email protected]> 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
