OPENSSL_secure_malloc.pod: articulate possibly non-secure pointer being returned

The semantics of OPENSSL_secure_[mz]alloc is somewhat unorthodox,
as it silently return a pointer to non-secure memory if the arena
is not initialised, which, while mentioned in the DESCRIPTION, is not
clear from reading the pertaining part of the RETURNING VALUE section alone;
explicitly state that the memory may be allocated by OPENSSL_calloc instead
if the secure heap is not initialised.

Signed-off-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/28059)

diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod
index f887da4c114c5001886ae8e28ec48e90133456aa..e9586be0ebfb45be793458757209352f4f71e813 100644 (file)
--- a/doc/man3/OPENSSL_secure_malloc.pod
+++ b/doc/man3/OPENSSL_secure_malloc.pod
@@ -137,8 +137,9 @@ but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not.
 OPENSSL_secure_malloc(), CRYPTO_secure_malloc(), OPENSSL_secure_zalloc(),
 CRYPTO_secure_zalloc(), OPENSSL_secure_malloc_array(),
 CRYPTO_secure_malloc_array(), OPENSSL_secure_calloc(), and CRYPTO_secure_calloc()
-return a pointer into the secure heap of the requested size,
-or C<NULL> if memory could not be allocated.
+return a pointer into the secure heap of the requested size, if it is
+initialised, a pointer returned by the underlying OPENSSL_malloc() call,
+if it is not, or C<NULL> on error.
 
 CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not.