RT4351: Update doc for OPENSSL_cleanse

[openssl.git] / doc / crypto / OPENSSL_malloc.pod

diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
index 04fa0b718c76ba674e25f8c79e180a6896cdb52d..e0271ca97780fbf947761fc45872190f3d964202 100644 (file)
--- a/doc/crypto/OPENSSL_malloc.pod
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -4,7 +4,7 @@
 
 OPENSSL_malloc_init,
 OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
-OPENSSL_clear_realloc, OPENSSL_clear_free,
+OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse
 CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
 OPENSSL_strdup, OPENSSL_strndup,
 OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
@@ -84,9 +84,17 @@ OPENSSL_zalloc() calls memset() to zero the memory before returning.
 
 OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
 when the buffer at B<addr> holds sensitive information.
-The old buffer is filled with arbitrary data by calling OPENSSL_cleanse()
+The old buffer is filled with zero's by calling OPENSSL_cleanse()
 before ultimately calling OPENSSL_free().
 
+OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
+Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
+If the storage controller uses write compression, then its possible 
+that sensitive tail bytes will survive zeroization because the block of 
+zeros will be compressed. If the storage controller uses wear leveling, 
+then the old sensitive data will not be overwritten; rather, a block of 
+0's will be written at a new physical location.
+
 OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
 equivalent C functions, except that memory is allocated by calling the
 OPENSSL_malloc() and should be releaed by calling OPENSSL_free().