doc/man3/OPENSSL_malloc.pod: mention rationale for OPENSSL_cleanse()

It was not entirely clear from the sole description, what is  the reason
for preferring OPENSSL_cleanse() over memset().  Add a note about situations
in which OPENSSL_cleanse() should be chosen.

Signed-off-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/29174)

diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod
index 5ddc6e4a6c09596a2e1e74ee29e853aad7b68c6f..30ceeb6ec0389830b2182ffb3526e4ae29ec2e64 100644 (file)
--- a/doc/man3/OPENSSL_malloc.pod
+++ b/doc/man3/OPENSSL_malloc.pod
@@ -151,6 +151,10 @@ these functions return an error if multiplication of B<num> and B<size>
 leads to an integer overflow, thus preventing allocations of an incorrect size.
 
 OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
+It is useful in cases when it is needed to ensure that memory (that contains
+sensitive information) is overwritten (for example, before it is reclaimed,
+or when it is stored on stack), and such operation is not optimised out
+by compiler optimisations such as dead store elimination (as memset(3) may be).
 Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
 If the storage controller uses write compression, then it's possible
 that sensitive tail bytes will survive zeroization because the block of