diff --git a/doxygen/input/doc_hashing.h b/doxygen/input/doc_hashing.h index de8205074..49f15ea88 100644 --- a/doxygen/input/doc_hashing.h +++ b/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 - * used for creating a hash message authentication code (HMAC) when sending a - * message. Such a HMAC can be used in combination with a private key - * for authentication, which is a message integrity control. + * The Message Digest (MD) or Hashing module provides one-way hashing + * functions. Such functions can be used for creating a hash message + * authentication code (HMAC) when sending a message. Such a HMAC can be used + * 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. diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h index d859dd5f6..7d944f3f6 100644 --- a/include/mbedtls/debug.h +++ b/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 - * level over the threshold value are ignored. - * (Default value: 0 (No debug)) + * \brief Set the threshold error level to handle globally all debug output. + * Debug messages that have a level over the threshold value are + * 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 */ + diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 307275130..3e05f3f3d 100644 --- a/include/mbedtls/ssl.h +++ b/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 ???? - * for security reasons. Use at your own risks. + * \warning Use of RC4 in DTLS/TLS has been prohibited by RFC-7465 + * for security reasons. Use at your own risk. * - * \note This function will likely be removed in future versions as - * RC4 will then be disabled by default at compile time. + * \note This function is deprecated and will likely be removed in + * 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 diff --git a/yotta/data/example-authcrypt/main.cpp b/yotta/data/example-authcrypt/main.cpp index 83d5566c5..23fad2792 100644 --- a/yotta/data/example-authcrypt/main.cpp +++ b/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(run).bind()); } diff --git a/yotta/data/example-benchmark/README.md b/yotta/data/example-benchmark/README.md index 1a534a2f3..8589e7bd6 100644 --- a/yotta/data/example-benchmark/README.md +++ b/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. diff --git a/yotta/data/example-benchmark/main.cpp b/yotta/data/example-benchmark/main.cpp index 77c70052b..ef38c442b 100644 --- a/yotta/data/example-benchmark/main.cpp +++ b/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(run).bind()); } diff --git a/yotta/data/example-hashing/main.cpp b/yotta/data/example-hashing/main.cpp index 27c469ba5..574152ab8 100644 --- a/yotta/data/example-hashing/main.cpp +++ b/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(run).bind()); } diff --git a/yotta/data/example-selftest/main.cpp b/yotta/data/example-selftest/main.cpp index b1b15f13b..0ff5b048e 100644 --- a/yotta/data/example-selftest/main.cpp +++ b/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(run).bind()); } diff --git a/yotta/data/module.json b/yotta/data/module.json index 0569e6246..164a083d8 100644 --- a/yotta/data/module.json +++ b/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": [ {