diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod index 04fa0b718c76ba674e25f8c79e180a6896cdb52d..e0271ca97780fbf947761fc45872190f3d964202 100644 --- 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 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 of size B 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().