Summary

Cipher javadoc could better describe AEAD reuse.

Problem

The class documentation in javax.crypto.Cipher could better explain AEAD modes and their behavior regarding reuse. The current example is too specific to GCM and does not clarify how exceptions may occur.

Solution

The javadoc should state that a call to Cipher.doFinal() may not reset the object's state when used with an AEAD algorithm. The class-level Javadoc should more clearly explain why an IllegalStateException is thrown when the Cipher object has not been reinitialized, rather than relying solely on per-method documentation

Specification