Merge remote-tracking branch 'public/pr/1006' into development

ChangeLog

@@ -14,6 +14,8 @@ Bugfix
      Found and fixed by Hirotaka Niisato in #1783.
    * Fix "no symbols" warning issued by ranlib when building on Mac OS X. Fix
      contributed by tabascoeye in pull request #1600.
+   * Clarify documentation for mbedtls_ssl_write() to include 0 as a valid
+     return value. Found by @davidwu2000. #839
 
 Changes
    * Change the shebang line in Perl scripts to look up perl in the PATH.

include/mbedtls/ssl.h

@@ -2907,17 +2907,19 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
  *                 or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ,
  *                 or another negative error code.
  *
- * \note           If this function returns something other than a positive value
+ * \note           If this function returns something other than 0, a positive
- *                 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop
- *                 the SSL context for reading or writing, and either free it or
+ *                 using the SSL context for reading or writing, and either
- *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 free it or call \c mbedtls_ssl_session_reset() on it before
- *                 for a new connection; the current connection must be closed.
+ *                 re-using it for a new connection; the current connection
+ *                 must be closed.
  *
  * \note           When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
  *                 it must be called later with the *same* arguments,
- *                 until it returns a positive value. When the function returns
+ *                 until it returns a value greater that or equal to 0. When
- *                 MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial
+ *                 the function returns MBEDTLS_ERR_SSL_WANT_WRITE there may be
- *                 data in the output buffer, however this is not yet sent.
+ *                 some partial data in the output buffer, however this is not
+ *                 yet sent.
  *
  * \note           If the requested length is greater than the maximum
  *                 fragment length (either the built-in limit or the one set
@@ -2926,6 +2928,9 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
  *                 - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
  *                 \c mbedtls_ssl_get_max_frag_len() may be used to query the
  *                 active maximum fragment length.
+ *
+ * \note           Attempting to write 0 bytes will result in an empty TLS
+ *                 application record being sent.
  */
 int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );
 

library/ssl_tls.c

@@ -7231,8 +7231,16 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
 }
 
 /*
- * Send application data to be encrypted by the SSL layer,
+ * Send application data to be encrypted by the SSL layer, taking care of max
- * taking care of max fragment length and buffer size
+ * fragment length and buffer size.
+ *
+ * According to RFC 5246 Section 6.2.1:
+ *
+ *      Zero-length fragments of Application data MAY be sent as they are
+ *      potentially useful as a traffic analysis countermeasure.
+ *
+ * Therefore, it is possible that the input message length is 0 and the
+ * corresponding return code is 0 on success.
  */
 static int ssl_write_real( mbedtls_ssl_context *ssl,
                            const unsigned char *buf, size_t len )
@@ -7260,6 +7268,12 @@ static int ssl_write_real( mbedtls_ssl_context *ssl,
 
     if( ssl->out_left != 0 )
     {
+        /*
+         * The user has previously tried to send the data and
+         * MBEDTLS_ERR_SSL_WANT_WRITE or the message was only partially
+         * written. In this case, we expect the high-level write function
+         * (e.g. mbedtls_ssl_write()) to be called with the same parameters
+         */
         if( ( ret = mbedtls_ssl_flush_output( ssl ) ) != 0 )
         {
             MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_ssl_flush_output", ret );
@@ -7268,6 +7282,11 @@ static int ssl_write_real( mbedtls_ssl_context *ssl,
     }
     else
     {
+        /*
+         * The user is trying to send a message the first time, so we need to
+         * copy the data into the internal buffers and setup the data structure
+         * to keep track of partial writes
+         */
         ssl->out_msglen  = len;
         ssl->out_msgtype = MBEDTLS_SSL_MSG_APPLICATION_DATA;
         memcpy( ssl->out_msg, buf, len );