From ab588529e1fd2d3a5368ffefd4ed2722f11d665e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 10 Dec 2018 16:04:46 +0100 Subject: [PATCH] Rework documentation. --- include/mbedtls/config.h | 63 +++++++++++++++++++++++++++------ include/mbedtls/platform_util.h | 14 +++++--- 2 files changed, 61 insertions(+), 16 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 25f6c8c28..54be651b9 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -259,19 +259,41 @@ /** * \def MBEDTLS_CHECK_PARAMS * - * This configuration controls whether the library validates parameters passed - * to it. + * This configuration controls whether the library validates more of the + * parameters passed to it. * - * Application code that deals with 3rd party input may wish to enable such - * validation, whilst code on closed systems, such as embedded systems, where - * the input is controlled and predictable, may wish to disable it entirely to - * reduce the code size of the library. + * When this flag is not defined, the library only attempts to validate input + * parameter if: (1) they may come from the outside world (such as the + * network, the filesystem, etc.) or (2) not validating them could result in + * internal memory errors such as overflowing a buffer controlled by the + * library. On the other hand, it doesn't attempt to validate parameters whose + * values are fully controlled by the application (such as pointers). * - * When the symbol is not defined, no parameter validation except that required - * to ensure the integrity or security of the library are performed. + * When this flag is defined, the library additionally attempts to validate + * parameters that are fully controlled by the application, and should always + * be valid if the application code is fully correct and trusted. * - * When the symbol is defined, all parameters will be validated, and an error - * code returned where appropriate. + * For example, when a function accepts a input a pointer to a buffer than may + * contain untrusted data, and its documentation mentions that this pointer + * must not be NULL: + * - the pointer is checked to be non-NULL only if this option is enabled + * - the content of the buffer is always validated + * + * When this flag is defined, if a library function receives a parameter that + * is invalid, it will: + * - invoke the macro MBEDTLS_PARAM_FAILED() which by default expands to a + * call to the function mbedtls_param_failed() + * - immediately return (with a specific error code unless the function + * returns void and can't communicate an error). + * + * When defining this flag, you also need to: + * - either provide a definition of the function mbedtls_param_failed() in + * your application (see platform_util.h for its prototype) as the library + * calls that function, but does not provide a default definition for it, + * - or provide a different definition of the macro MBEDTLS_PARAM_FAILED() + * below if the above mechanism is not enough flexible to suit your needs. + * + * Uncomment to enable validation of application-controlled parameters. */ #define MBEDTLS_CHECK_PARAMS @@ -3015,7 +3037,26 @@ //#define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO mbedtls_platform_std_nv_seed_read /**< Default nv_seed_read function to use, can be undefined */ //#define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */ -//#define MBEDTLS_PARAM_FAILED(x) mbedtls_param_failed( #x, __FILE__, __LINE__ ) /**< Default parameter validation callback to use. Can be undefined */ +/** + * \brief This macro is invoked by the library when an invalid parameter + * is detected that is only checked with MBEDTLS_CHECK_PARAMS + * (see the document of the flag for context). + * + * When you leave this undefined here, a default definition is + * provided the invokes the function mbedtls_param_failed(), + * which is declared in platform_util.h for the benefit of the + * library, but that you need to define in your application. + * + * When you define this here, this replaces the default + * definition in platform_util.h (which no longer declares the + * function mbedtls_param_failed()) and it is your responsability + * to make sure this macro expands to something suitable (in + * particular, that all the necessary declarations are visible + * from within the library). + * + * \param cond The expression that should evaluate to true, but doesn't. + */ +//#define MBEDTLS_PARAM_FAILED( cond ) assert( cond ) /* SSL Cache options */ diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h index a712764a6..ed21ffa91 100644 --- a/include/mbedtls/platform_util.h +++ b/include/mbedtls/platform_util.h @@ -52,7 +52,7 @@ extern "C" { #define MBEDTLS_PARAM_FAILED_ALT #else #define MBEDTLS_PARAM_FAILED( cond ) \ - mbedtls_param_failed( cond, __FILE__, __LINE__ ) + mbedtls_param_failed( #cond, __FILE__, __LINE__ ) /** * \brief User supplied callback function for parameter validation failure. @@ -66,15 +66,19 @@ extern "C" { * application software using Mbed TLS, or catch other runtime * errors which may be due to issues in the application software. * - * This function will be called unless an alternative function is - * defined through the MBEDTLS_PARAM_FAILURE function. + * This function will be called unless an alternative treatement + * is defined through the MBEDTLS_PARAM_FAILURE() macro. * * This function can return, and the operation will be aborted, or * alternatively, through use of setjmp()/longjmp() can resume * execution in the application code. + * + * \param failure_condition The assertion that didn't hold. + * \param file The file where the assertion failed. + * \param line The line in the file where the assertion failed. */ -void mbedtls_param_failed( const char* failure_condition, - const char* file, +void mbedtls_param_failed( const char *failure_condition, + const char *file, int line ); #endif /* MBEDTLS_PARAM_FAILED */ #endif /* MBEDTLS_CHECK_PARAMS */