From c4315e6d5e73320dffadeccfa4837ca83dd778a2 Mon Sep 17 00:00:00 2001
From: Jarno Lamsa <jarno.lamsa@arm.com>
Date: Fri, 4 Oct 2019 15:42:39 +0300
Subject: [PATCH] Address review comments for documentation

---
 include/mbedtls/platform_util.h | 35 +++++++++++++++------------------
 1 file changed, 16 insertions(+), 19 deletions(-)

diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
index 35e39768c..586f0d9ee 100644
--- a/include/mbedtls/platform_util.h
+++ b/include/mbedtls/platform_util.h
@@ -167,12 +167,11 @@ void mbedtls_platform_zeroize( void *buf, size_t len );
 /**
  * \brief       Secure memset
  *
- *              This function is meant to provide a more secure way to do
- *              memset. It starts by initialising the given memory area
- *              from random tail location with random data. After tail is
- *              initialised, the remaining head of the buffer is initialised
- *              with random data. After initialisation, the original memset
- *              is performed
+ *              This is a constant-time version of memset(). If
+ *              MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the buffer is
+ *              initialised with random data and the order is also
+ *              randomised using the hardware RNG in order to further harden
+ *              against side-channel attacks.
  *
  * \param ptr   Buffer to be set.
  * \param value Value to be used when setting the buffer.
@@ -185,12 +184,11 @@ void *mbedtls_platform_memset( void *ptr, int value, size_t num );
 /**
  * \brief       Secure memcpy
  *
- *              This function is meant to provide a more secure way to do
- *              memcpy. It starts by initialising the given memory area
- *              with random data. After initialisation, the original memcpy
- *              is performed by starting first copying from random tail
- *              location of the buffer. After tail has been copied, the
- *              remaining head is copied as well.
+ *              This is a constant-time version of memcpy(). If
+ *              MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the buffer is
+ *              initialised with random data and the order is also
+ *              randomised using the hardware RNG in order to further harden
+ *              against side-channel attacks.
  *
  * \param dst   Destination buffer where the data is being copied to.
  * \param src   Source buffer where the data is being copied from.
@@ -203,18 +201,17 @@ void *mbedtls_platform_memcpy( void *dst, const void *src, size_t num );
 /**
  * \brief       Secure memcmp
  *
- *              This function is meant to provide a more secure way to do
- *              memcmp. It starts comparing from a random offset and goes
- *              through the tail part of buffers first byte by byte. After
- *              that it starts going through the head part of buffer. In the
- *              end, the number of equal bytes is compared to the length of the
- *              buffers, thus making the function a fixed time memcmp.
+ *              This is a constant-time version of memcmp(). If
+ *              MBEDTLS_ENTROPY_HARDWARE_ALT is defined, the order is also
+ *              randomised using the hardware RNG in order to further harden
+ *              against side-channel attacks.
  *
  * \param buf1  First buffer to compare.
  * \param buf2  Second buffer to compare against.
  * \param num   The length of the buffers in bytes.
  *
- * \return      0 if the buffers were equal.
+ * \return      0 if the buffers were equal or an unspecified non-zero value
+ *              otherwise.
  */
 int mbedtls_platform_memcmp( const void *buf1, const void *buf2, size_t num );