Merge branch 'development'

doxygen/input/doc_hashing.h

@@ -23,13 +23,14 @@
 /**
  * @addtogroup hashing_module Hashing module
  *
- * The Hashing module provides one-way hashing functions. Such functions can be
+ * The Message Digest (MD) or Hashing module provides one-way hashing
- * used for creating a hash message authentication code (HMAC) when sending a
+ * functions. Such functions can be used for creating a hash message
- * message. Such a HMAC can be used in combination with a private key
+ * authentication code (HMAC) when sending a message. Such a HMAC can be used
- * for authentication, which is a message integrity control.
+ * in combination with a private key for authentication, which is a message
+ * integrity control.
  *
  * All hash algorithms can be accessed via the generic MD layer (see
- * \c md_setup())
+ * \c mbedtls_md_setup())
  *
  * The following hashing-algorithms are provided:
  * - MD2, MD4, MD5 128-bit one-way hash functions by Ron Rivest.

include/mbedtls/debug.h

@@ -1,7 +1,7 @@
 /**
  * \file debug.h
  *
- * \brief Debug functions
+ * \brief Functions for controlling and providing debug output from the library.
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
@@ -80,39 +80,141 @@ extern "C" {
 #endif
 
 /**
- * \brief   Set the level threshold to handle globally. Messages that have a
+ * \brief   Set the threshold error level to handle globally all debug output.
- *          level over the threshold value are ignored.
+ *          Debug messages that have a level over the threshold value are
- *          (Default value: 0 (No debug))
+ *          discarded.
+ *          (Default value: 0 = No debug )
  *
- * \param threshold     maximum level of messages to pass on
+ * \param threshold     theshold level of messages to filter on. Messages at a
+ *                      higher level will be discarded.
+ *                          - Debug levels
+ *                              - 0 No debug
+ *                              - 1 Error
+ *                              - 2 State change
+ *                              - 3 Informational
+ *                              - 4 Verbose
  */
 void mbedtls_debug_set_threshold( int threshold );
 
+/**
+* \brief    Print a message to the debug output. This function is always used
+ *          through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl
+ *          context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the message has occurred in
+ * \param line      line number the message has occurred at
+ * \param format    format specifier, in printf format
+ * \param ...       variables used by the format specifier
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level,
                               const char *file, int line,
                               const char *format, ... );
 
+/**
+ * \brief   Print the return value of a function to the debug output. This
+ *          function is always used through the MBEDTLS_SSL_DEBUG_RET() macro,
+ *          which supplies the ssl context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param text      the name of the function that returned the error
+ * \param ret       the return code value
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level,
                       const char *file, int line,
                       const char *text, int ret );
 
+/**
+ * \brief   Output a buffer of size len bytes to the debug output. This function
+ *          is always used through the MBEDTLS_SSL_DEBUG_BUF() macro,
+ *          which supplies the ssl context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param text      a name or label for the buffer being dumped. Normally the
+ *                  variable or buffer name
+ * \param buf       the buffer to be outputted
+ * \param len       length of the buffer
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level,
                       const char *file, int line, const char *text,
                       const unsigned char *buf, size_t len );
 
 #if defined(MBEDTLS_BIGNUM_C)
+/**
+ * \brief   Print a MPI variable to the debug output. This function is always
+ *          used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the
+ *          ssl context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param text      a name or label for the MPI being output. Normally the
+ *                  variable name
+ * \param X         the MPI variable
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level,
                       const char *file, int line,
                       const char *text, const mbedtls_mpi *X );
 #endif
 
 #if defined(MBEDTLS_ECP_C)
+/**
+ * \brief   Print an ECP point to the debug output. This function is always
+ *          used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the
+ *          ssl context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param text      a name or label for the ECP point being output. Normally the
+ *                  variable name
+ * \param X         the ECP point
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level,
                       const char *file, int line,
                       const char *text, const mbedtls_ecp_point *X );
 #endif
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
+/**
+ * \brief   Print a X.509 certificate structure to the debug output. This
+ *          function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro,
+ *          which supplies the ssl context, file and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param text      a name or label for the certificate being output
+ * \param crt       X.509 certificate structure
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
                       const char *file, int line,
                       const char *text, const mbedtls_x509_crt *crt );
@@ -123,3 +225,4 @@ void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
 #endif
 
 #endif /* debug.h */
+

include/mbedtls/ssl.h

@@ -2012,11 +2012,13 @@ void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems
  * \brief          Disable or enable support for RC4
  *                 (Default: MBEDTLS_SSL_ARC4_DISABLED)
  *
- * \warning        Use of RC4 in (D)TLS has been prohibited by RFC ????
+ * \warning        Use of RC4 in DTLS/TLS has been prohibited by RFC-7465
- *                 for security reasons. Use at your own risks.
+ *                 for security reasons. Use at your own risk.
  *
- * \note           This function will likely be removed in future versions as
+ * \note           This function is deprecated and will likely be removed in
- *                 RC4 will then be disabled by default at compile time.
+ *                 a future version of the library.
+ *                 RC4 is disabled by default at compile time and needs to be
+ *                 actively enabled for use with legacy systems.
  *
  * \param conf     SSL configuration
  * \param arc4     MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED

yotta/data/example-authcrypt/main.cpp

@@ -175,10 +175,6 @@ static int example(void)
 #include "minar/minar.h"
 
 static void run() {
-    /* Use 115200 bps for consistency with other examples */
-    Serial pc(USBTX, USBRX);
-    pc.baud(115200);
-
     MBED_HOSTTEST_TIMEOUT(10);
     MBED_HOSTTEST_SELECT(default);
     MBED_HOSTTEST_DESCRIPTION(mbed TLS example authcrypt);
@@ -187,6 +183,8 @@ static void run() {
 }
 
 void app_start(int, char*[]) {
+    /* Use 115200 bps for consistency with other examples */
+    get_stdio_serial().baud(115200);
     minar::Scheduler::postCallback(mbed::util::FunctionPointer0<void>(run).bind());
 }
 

yotta/data/example-benchmark/README.md

@@ -92,3 +92,9 @@ To build and run this example you must have:
     {{success}}
     {{end}}
     ```
+
+Any performance data generated by this example application are indicative only of the performance of the mbed TLS module on the platform it's executed on.
+
+Differences in the integration of mbed TLS into the platform, such as whether all available hardware accelerators have been used or not, can lead to significant differences in performance, and so results from the program are not intended to be used to meaningfully compare platforms.
+
+The figures may also slightly change from execution to execution due to variations in the timing functions.

yotta/data/example-benchmark/main.cpp

@@ -935,10 +935,6 @@ int benchmark( int argc, char *argv[] )
 #include "minar/minar.h"
 
 static void run() {
-    /* Use 115200 bps for consistency with other examples */
-    Serial pc(USBTX, USBRX);
-    pc.baud(115200);
-
     MBED_HOSTTEST_TIMEOUT(150);
     MBED_HOSTTEST_SELECT(default);
     MBED_HOSTTEST_DESCRIPTION(mbed TLS benchmark program);
@@ -947,6 +943,8 @@ static void run() {
 }
 
 void app_start(int, char*[]) {
+    /* Use 115200 bps for consistency with other examples */
+    get_stdio_serial().baud(115200);
     minar::Scheduler::postCallback(mbed::util::FunctionPointer0<void>(run).bind());
 }
 

yotta/data/example-hashing/main.cpp

@@ -155,10 +155,6 @@ int example(void)
 #include "minar/minar.h"
 
 static void run() {
-    /* Use 115200 bps for consistency with other examples */
-    Serial pc(USBTX, USBRX);
-    pc.baud(115200);
-
     MBED_HOSTTEST_TIMEOUT(10);
     MBED_HOSTTEST_SELECT(default);
     MBED_HOSTTEST_DESCRIPTION(mbed TLS example on hashing);
@@ -167,6 +163,8 @@ static void run() {
 }
 
 void app_start(int, char*[]) {
+    /* Use 115200 bps for consistency with other examples */
+    get_stdio_serial().baud(115200);
     minar::Scheduler::postCallback(mbed::util::FunctionPointer0<void>(run).bind());
 }
 

yotta/data/example-selftest/main.cpp

@@ -246,10 +246,6 @@ int selftest( int argc, char *argv[] )
 #include "minar/minar.h"
 
 static void run() {
-    /* Use 115200 bps for consistency with other examples */
-    Serial pc(USBTX, USBRX);
-    pc.baud(115200);
-
     MBED_HOSTTEST_TIMEOUT(40);
     MBED_HOSTTEST_SELECT(default);
     MBED_HOSTTEST_DESCRIPTION(mbed TLS selftest program);
@@ -258,6 +254,8 @@ static void run() {
 }
 
 void app_start(int, char*[]) {
+    /* Use 115200 bps for consistency with other examples */
+    get_stdio_serial().baud(115200);
     minar::Scheduler::postCallback(mbed::util::FunctionPointer0<void>(run).bind());
 }
 

yotta/data/module.json

@@ -1,6 +1,6 @@
 {
     "name": "mbedtls",
-    "version": "2.2.1",
+    "version": "2.2.2",
     "description": "The mbed TLS crypto/SSL/TLS library",
     "licenses": [
         {