From 56e06db1023255d19578cc4108ecf3b78053ccd7 Mon Sep 17 00:00:00 2001 From: Andres Amaya Garcia Date: Tue, 24 Apr 2018 08:37:52 -0500 Subject: [PATCH] Improve mbedtls_platform_zeroize() docs --- include/mbedtls/platform_util.h | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h index bda97102c..84f0732ee 100644 --- a/include/mbedtls/platform_util.h +++ b/include/mbedtls/platform_util.h @@ -34,19 +34,24 @@ extern "C" { /** * \brief Securely zeroize a buffer * - * \param buf Buffer to be zeroized - * \param len Length of the buffer in bytes + * The function is meant to wipe the data contained in a buffer so + * that it can no longer be recovered even if the program memory + * is later compromised. Call this function on sensitive data + * stored on the stack before returning from a function, and on + * sensitive data stored on the heap before freeing the heap + * object. * - * \note This implementation should never be optimized out by the - * compiler - * - * \note It is extremely difficult to guarantee that calls to + * It is extremely difficult to guarantee that calls to * mbedtls_platform_zeroize() are not removed by aggressive * compiler optimizations in a portable way. For this reason, Mbed * TLS provides the configuration option * MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure * mbedtls_platform_zeroize() to use a suitable implementation for * their platform and needs + * + * \param buf Buffer to be zeroized + * \param len Length of the buffer in bytes + * */ void mbedtls_platform_zeroize( void *buf, size_t len );