From 1e8ea5fa68223351553192a608ac06a6ac8dfbc3 Mon Sep 17 00:00:00 2001
From: Andres Amaya Garcia <Andres.AmayaGarcia@arm.com>
Date: Thu, 8 Mar 2018 20:46:39 +0000
Subject: [PATCH] Improve docs for mbedtls_zeroize() and add refs

---
 include/mbedtls/utils.h |  7 +++++++
 library/utils.c         | 20 +++++++++++++-------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/include/mbedtls/utils.h b/include/mbedtls/utils.h
index 61b1b76c0d..cb03fb0e45 100644
--- a/include/mbedtls/utils.h
+++ b/include/mbedtls/utils.h
@@ -33,6 +33,13 @@
  *
  * \note        This implementation should never be optimized out by the
  *              compiler
+ *
+ * \note        It is extremely difficult to guarantee that calls to
+ *              mbedtls_zeroize() are not removed by aggressive compiler
+ *              optimizations in a portable way. For this reason, Mbed TLS
+ *              provides the configuration option MBEDTLS_UTILS_ZEROIZE_ALT,
+ *              which allows users to configure mbedtls_zeroize() to use a
+ *              suitable implementation for their platform and needs
  */
 void mbedtls_zeroize( void *buf, size_t len );
 
diff --git a/library/utils.c b/library/utils.c
index 62b3244ed2..e7fef6da1b 100644
--- a/library/utils.c
+++ b/library/utils.c
@@ -34,19 +34,25 @@
 /*
  * This implementation should never be optimized out by the compiler
  *
- * This implementation for mbedtls_zeroize() uses a volatile function pointer.
- * We always know that it points to memset(), but because it is volatile the
- * compiler expects it to change at any time and will not optimize out the
- * call that could potentially perform other operations on the input buffer
- * instead of just setting it to 0. Nevertheless, optimizations of the
- * following form are still possible:
+ * This implementation for mbedtls_zeroize() was inspired from Colin Percival's
+ * blog article at:
+ *
+ * http://www.daemonology.net/blog/2014-09-04-how-to-zero-a-buffer.html
+ *
+ * It uses a volatile function pointer to the standard memset(). Because the
+ * pointer is volatile the compiler expects it to change at
+ * any time and will not optimize out the call that could potentially perform
+ * other operations on the input buffer instead of just setting it to 0.
+ * Nevertheless, as pointed out by davidtgoldblatt on Hacker News
+ * (refer to http://www.daemonology.net/blog/2014-09-05-erratum.html for
+ * details), optimizations of the following form are still possible:
  *
  * if( memset_func != memset )
  *     memset_func( buf, 0, len );
  *
  * Note that it is extremely difficult to guarantee that mbedtls_zeroize()
  * will not be optimized out by aggressive compilers in a portable way. For
- * this reason, mbed TLS also provides the configuration option
+ * this reason, Mbed TLS also provides the configuration option
  * MBEDTLS_UTILS_ZEROIZE_ALT, which allows users to configure
  * mbedtls_zeroize() to use a suitable implementation for their platform and
  * needs.