Rename zero_mem to secure_scrub_memory

1 files changed, 34 insertions, 9 deletions

diff --git a/src/lib/utils/mem_ops.h b/src/lib/utils/mem_ops.h
index 0d2d0dab0..b4cf7f76c 100644
--- a/src/lib/utils/mem_ops.h
+++ b/src/lib/utils/mem_ops.h
@@ -15,26 +15,51 @@
 namespace Botan {
 
 /**
-* Zeroize memory
-* @param ptr a pointer to memory to zero out
+* Scrub memory contents in a way that a compiler should not elide,
+* using some system specific technique. Note that this function might
+* not zero the memory (for example, in some hypothetical
+* implementation it might combine the memory contents with the output
+* of a system PRNG), but if you can detect any difference in behavior
+* at runtime then the clearing is side-effecting and you can just
+* use `clear_mem`.
+*
+* Use this function to scrub memory just before deallocating it, or on
+* a stack buffer before returning from the function.
+*
+* @param ptr a pointer to memory to scrub
 * @param n the number of bytes pointed to by ptr
 */
-BOTAN_DLL void zero_mem(void* ptr, size_t n);
+BOTAN_DLL void secure_scrub_memory(void* ptr, size_t n);
 
 /**
-* Zeroize memory
-* @param ptr a pointer to an array
-* @param n the number of Ts pointed to by ptr
+* Zero out some bytes
+* @param ptr a pointer to memory to zero
+* @param bytes the number of bytes to zero in ptr
 */
-template<typename T> inline void clear_mem(T* ptr, size_t n)
+inline void clear_bytes(void* ptr, size_t bytes)
    {
-   if(n > 0)
+   if(bytes > 0)
       {
-      std::memset(ptr, 0, sizeof(T)*n);
+      std::memset(ptr, 0, bytes);
       }
    }
 
 /**
+* Zero memory before use. This simply calls memset and should not be
+* used in cases where the compiler cannot see the call as a
+* side-effecting operation (for example, if calling clear_mem before
+* deallocating memory, the compiler would be allowed to omit the call
+* to memset entirely under the as-if rule.)
+*
+* @param ptr a pointer to an array of Ts to zero
+* @param n the number of Ts pointed to by ptr
+*/
+template<typename T> inline void clear_mem(T* ptr, size_t n)
+   {
+   clear_bytes(ptr, sizeof(T)*n);
+   }
+
+/**
 * Copy memory
 * @param out the destination array
 * @param in the source array