Add notes about accuracy of output size calculations of AEADBlockCipher and appropriate handling of plaintext output during decryption prior to authentication.

Author: timw

core/src/main/java/org/bouncycastle/crypto/modes/AEADBlockCipher.java

@@ -7,6 +7,15 @@
 
 /**
  * A block cipher mode that includes authenticated encryption with a streaming mode and optional associated data.
+ * <p/>
+ * Implementations of this interface may operate in a packet mode (where all input data is buffered and 
+ * processed dugin the call to {@link #doFinal(byte[], int)}), or in a streaming mode (where output data is
+ * incrementally produced with each call to {@link #processByte(byte, byte[], int)} or 
+ * {@link #processBytes(byte[], int, int, byte[], int)}.
+ * <br/>This is important to consider during decryption: in a streaming mode, unauthenticated plaintext data
+ * may be output prior to the call to {@link #doFinal(byte[], int)} that results in an authentication
+ * failure. The higher level protocol utilising this cipher must ensure the plaintext data is handled 
+ * appropriately until the end of data is reached and the entire ciphertext is authenticated.
  * @see org.bouncycastle.crypto.params.AEADParameters
  */
 public interface AEADBlockCipher
@@ -101,7 +110,11 @@ public int doFinal(byte[] out, int outOff)
     /**
      * return the size of the output buffer required for a processBytes
      * an input of len bytes.
-     *
+     * <p/>
+     * The returned size may be dependent on the initialisation of this cipher
+     * and may not be accurate once subsequent input data is processed - this method
+     * should be invoked immediately prior to input data being processed.
+     * 
      * @param len the length of the input.
      * @return the space required to accommodate a call to processBytes
      * with len bytes of input.
@@ -111,7 +124,12 @@ public int doFinal(byte[] out, int outOff)
     /**
      * return the size of the output buffer required for a processBytes plus a
      * doFinal with an input of len bytes.
-     *
+     * <p/>
+     * The returned size may be dependent on the initialisation of this cipher
+     * and may not be accurate once subsequent input data is processed - this method
+     * should be invoked immediately prior to a call to final processing of input data
+     * and a call to {@link #doFinal(byte[], int)}.
+     * 
      * @param len the length of the input.
      * @return the space required to accommodate a call to processBytes and doFinal
      * with len bytes of input.