From: Eugene Syromiatnikov <esyr@openssl.org>
Date: Thu, 31 Jul 2025 13:21:01 +0000 (+0200)
Subject: OPENSSL_secure_malloc.pod: articulate possibly non-secure pointer being returned
X-Git-Tag: openssl-3.6.0-alpha1~206
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=78b10493a91934558bc135e1b7b2ac227340d875;p=thirdparty%2Fopenssl.git

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 f887da4c114..e9586be0ebf 100644
--- 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.