From dc11cd166897118db1f7b5f96339bef3ea6a8eaf Mon Sep 17 00:00:00 2001 From: Andrzej Kurek Date: Fri, 14 Jul 2023 09:47:05 -0400 Subject: [PATCH] Extend mbedtls_calloc and mbedtls_free documentation Co-authored-by: Gilles Peskine Signed-off-by: Andrzej Kurek --- include/mbedtls/config.h | 23 +++++++++++++++++++---- include/mbedtls/platform.h | 3 ++- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index be6ad83cb..aaa150833 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3798,8 +3798,23 @@ /* Platform options */ //#define MBEDTLS_PLATFORM_STD_MEM_HDR /**< Header to include if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS is defined. Don't define if no header is needed. */ -//#define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< Default allocator to use, can be undefined. Please note that it should zeroize the allocated buffer. */ -//#define MBEDTLS_PLATFORM_STD_FREE free /**< Default free to use, can be undefined */ +/** \def MBEDTLS_PLATFORM_STD_CALLOC + * + * Default allocator to use, can be undefined. + * It should initialize the allocated buffer memory to zeroes. + * The size of the buffer is the product of the two parameters. + * The behavior is undefined if the product of the two parameters overflows size_t. + * If the product is 0, the function may either return NULL or a valid pointer to an array of size 0 which is a valid input to the deallocation function. + * The corresponding deallocation function is MBEDTLS_PLATFORM_STD_FREE. + */ +//#define MBEDTLS_PLATFORM_STD_CALLOC calloc +/** \def MBEDTLS_PLATFORM_STD_FREE + * + * Default free to use, can be undefined. + * NULL is a valid parameter, and the function must do nothing. + * A non-null parameter will always be a pointer previously returned by MBEDTLS_PLATFORM_STD_CALLOC and not yet freed. + */ +//#define MBEDTLS_PLATFORM_STD_FREE free //#define MBEDTLS_PLATFORM_STD_EXIT exit /**< Default exit to use, can be undefined */ //#define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */ //#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use, can be undefined */ @@ -3814,8 +3829,8 @@ /* To Use Function Macros MBEDTLS_PLATFORM_C must be enabled */ /* MBEDTLS_PLATFORM_XXX_MACRO and MBEDTLS_PLATFORM_XXX_ALT cannot both be defined */ -//#define MBEDTLS_PLATFORM_CALLOC_MACRO calloc /**< Default allocator macro to use, can be undefined */ -//#define MBEDTLS_PLATFORM_FREE_MACRO free /**< Default free macro to use, can be undefined */ +//#define MBEDTLS_PLATFORM_CALLOC_MACRO calloc /**< Default allocator macro to use, can be undefined. See MBEDTLS_PLATFORM_STD_CALLOC for requirements. */ +//#define MBEDTLS_PLATFORM_FREE_MACRO free /**< Default free macro to use, can be undefined. See MBEDTLS_PLATFORM_STD_FREE for requirements. */ //#define MBEDTLS_PLATFORM_EXIT_MACRO exit /**< Default exit macro to use, can be undefined */ //#define MBEDTLS_PLATFORM_TIME_MACRO time /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */ //#define MBEDTLS_PLATFORM_TIME_TYPE_MACRO time_t /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */ diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index 121ba3ad7..08c0172e0 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -140,7 +140,8 @@ extern "C" { /* * The function pointers for calloc and free. - * mbedtls_calloc will allocate and zeroize the buffer. + * please see MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE + * in mbedtls_config.h for more information about behaviour and requirements. */ #if defined(MBEDTLS_PLATFORM_MEMORY) #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \