Document message length checks

Author: jchambers

src/main/java/com/eatthepath/noise/NoiseHandshake.java

@@ -639,6 +639,8 @@ static int getPayloadLength(final HandshakePattern handshakePattern,
    *
    * @return a new byte array containing the resulting handshake message
    *
+   * @throws IllegalArgumentException if the message produced for the given payload would be larger than the maximum
+   * allowed Noise handshake message size
    * @throws IllegalStateException if this handshake is not currently expecting to send a handshake message to its peer
    *
    * @see #isExpectingWrite()
@@ -679,6 +681,8 @@ public byte[] writeMessage(@Nullable final byte[] payload) {
    *
    * @return the number of bytes written to {@code message}
    *
+   * @throws IllegalArgumentException if the message produced for the given payload would be larger than the maximum
+   * allowed Noise handshake message size
    * @throws IllegalStateException if this handshake is not currently expecting to send a handshake message to its peer
    * @throws ShortBufferException if {@code message} is not large enough (after its offset) to hold the handshake
    * message
@@ -771,6 +775,8 @@ public int writeMessage(@Nullable final byte[] payload,
    *
    * @return a new byte buffer containing the resulting handshake message
    *
+   * @throws IllegalArgumentException if the message produced for the given payload would be larger than the maximum
+   * allowed Noise handshake message size
    * @throws IllegalStateException if this handshake is not currently expecting to send a handshake message to its peer
    *
    * @see #isExpectingWrite()
@@ -811,6 +817,8 @@ public ByteBuffer writeMessage(@Nullable final ByteBuffer payload) {
    *
    * @return the number of bytes written to {@code message}
    *
+   * @throws IllegalArgumentException if the message produced for the given payload would be larger than the maximum
+   * allowed Noise handshake message size
    * @throws IllegalStateException if this handshake is not currently expecting to send a handshake message to its peer
    * @throws ShortBufferException if {@code message} does not have enough remaining capacity to hold the handshake
    * message
@@ -899,7 +907,8 @@ private void checkOutboundMessageSize(final int payloadLength) {
    *
    * @throws AEADBadTagException if the AEAD tag for any encrypted component of the given handshake message does not
    * match the calculated value
-   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message
+   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message or if
+   * the given message is larger than the maximum allowed Noise handshake message size
    */
   public byte[] readMessage(final byte[] message) throws AEADBadTagException {
     checkInboundMessageSize(message.length);
@@ -934,8 +943,9 @@ public byte[] readMessage(final byte[] message) throws AEADBadTagException {
    * match the calculated value
    * @throws ShortBufferException if {@code payload} is too short (after its offset) to hold the plaintext of the
    * payload included in the given handshake message
-   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message
-   * 
+   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message or if
+   * the given message is larger than the maximum allowed Noise handshake message size
+   *
    * @see #getPayloadLength(int)
    */
   public int readMessage(final byte[] message,
@@ -1013,7 +1023,8 @@ public int readMessage(final byte[] message,
    *
    * @throws AEADBadTagException if the AEAD tag for any encrypted component of the given handshake message does not
    * match the calculated value
-   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message
+   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message or if
+   * the given message is larger than the maximum allowed Noise handshake message size
    */
   public ByteBuffer readMessage(final ByteBuffer message) throws AEADBadTagException {
     checkInboundMessageSize(message.remaining());
@@ -1049,7 +1060,8 @@ public ByteBuffer readMessage(final ByteBuffer message) throws AEADBadTagExcepti
    * match the calculated value
    * @throws ShortBufferException if {@code payload} does not have enough remaining capacity to hold the plaintext of
    * the payload included in the given handshake message
-   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message
+   * @throws IllegalArgumentException if the given message is too short to contain the expected handshake message or if
+   * the given message is larger than the maximum allowed Noise handshake message size
    *
    * @see #getPayloadLength(int)
    */

src/main/java/com/eatthepath/noise/NoiseTransportReader.java

@@ -38,7 +38,8 @@ public interface NoiseTransportReader {
    * @return a {@code ByteBuffer} containing the resulting plaintext
    *
    * @throws AEADBadTagException if the AEAD tag in the given ciphertext does not match the calculated value
-   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag
+   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag or if it is
+   * larger than the maximum allowed Noise transport message size
    *
    * @see #getPlaintextLength(int)
    */
@@ -60,7 +61,8 @@ public interface NoiseTransportReader {
    * @return the number of bytes written into the {@code plaintext} buffer
    *
    * @throws AEADBadTagException if the AEAD tag in the given ciphertext does not match the calculated value
-   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag
+   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag or if it is
+   * larger than the maximum allowed Noise transport message size
    * @throws ShortBufferException if the given plaintext buffer does not have enough remaining capacity to hold the
    * resulting plaintext
    *
@@ -76,7 +78,8 @@ public interface NoiseTransportReader {
    * @return a new byte array containing the resulting plaintext
    *
    * @throws AEADBadTagException if the AEAD tag in the given ciphertext does not match the calculated AEAD tag
-   * @throws IllegalArgumentException if the given ciphertext is too small to contain a valid AEAD tag
+   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag or if it is
+   * larger than the maximum allowed Noise transport message size
    */
   byte[] readMessage(final byte[] ciphertext) throws AEADBadTagException;
 
@@ -96,7 +99,8 @@ public interface NoiseTransportReader {
    * @throws AEADBadTagException if the AEAD tag in the given ciphertext does not match the calculated value
    * @throws ShortBufferException if {@code plaintext} is not long enough (after its offset) to contain the resulting
    * plaintext
-   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag
+   * @throws IllegalArgumentException if the given ciphertext is too short to contain a valid AEAD tag or if it is
+   * larger than the maximum allowed Noise transport message size
    */
   int readMessage(final byte[] ciphertext,
                   final int ciphertextOffset,

src/main/java/com/eatthepath/noise/NoiseTransportWriter.java

@@ -33,6 +33,9 @@ public interface NoiseTransportWriter {
    *
    * @return a new byte buffer containing the resulting ciphertext and AEAD tag
    *
+   * @throws IllegalArgumentException if the ciphertext for the given plaintext would be larger than the maximum allowed
+   * Noise transport message size
+   *
    * @see #getCiphertextLength(int)
    */
   ByteBuffer writeMessage(final ByteBuffer plaintext);
@@ -54,6 +57,8 @@ public interface NoiseTransportWriter {
    *
    * @return the number of bytes written into the ciphertext buffer
    *
+   * @throws IllegalArgumentException if the ciphertext for the given plaintext would be larger than the maximum allowed
+   * Noise transport message size
    * @throws ShortBufferException if the given ciphertext buffer does not have enough remaining capacity to hold the
    * resulting ciphertext and AEAD tag
    *
@@ -67,6 +72,9 @@ public interface NoiseTransportWriter {
    * @param plaintext the plaintext to encrypt
    *
    * @return a new byte array containing the resulting ciphertext
+   *
+   * @throws IllegalArgumentException if the ciphertext for the given plaintext would be larger than the maximum allowed
+   * Noise transport message size
    */
   byte[] writeMessage(final byte[] plaintext);
 
@@ -89,6 +97,8 @@ public interface NoiseTransportWriter {
    * ciphertext and AEAD tag
    * @throws IndexOutOfBoundsException if the given plaintext length exceeds the length of the plaintext array after its
    * offset
+   * @throws IllegalArgumentException if the ciphertext for the given plaintext would be larger than the maximum allowed
+   * Noise transport message size
    *
    * @see #getCiphertextLength(int)
    */