From 704ee1348c46a4980c6918f6a7db32a322f565ab Mon Sep 17 00:00:00 2001 From: Eugene Syromiatnikov Date: Thu, 31 Jul 2025 13:42:41 +0200 Subject: [PATCH] doc/man3/OPENSSL_malloc.pod: document OPENSSL_aligned_alloc peculiarity MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit OPENSSL_aligned_alloc can return NULL in cases other than memory exhaustion or incorrect arguments, document that. Signed-off-by: Eugene Syromiatnikov Reviewed-by: Saša Nedvědický Reviewed-by: Matt Caswell Reviewed-by: Paul Dale Reviewed-by: Neil Horman (Merged from https://github.com/openssl/openssl/pull/28059) --- doc/man3/OPENSSL_malloc.pod | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 6e8d350dd30..9dd3bc17666 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -127,7 +127,13 @@ allows for the caller to specify an alignment value, for instances in which the default alignment of malloc is insufficient for the caller's needs. Note, the alignment value must be a power of 2, and the size specified must be a multiple of the alignment. -NOTE: The call to OPENSSL_aligned_alloc() accepts a 3rd argument, I +NOTES: + +=over 4 + +=item * + +The call to OPENSSL_aligned_alloc() accepts a 3rd argument, I which must point to a void pointer. On some platforms, there is no available library call to obtain memory allocations with alignment greater than what malloc provides. In this case, OPENSSL_aligned_alloc() implements its own @@ -136,6 +142,18 @@ pointer to be on the requested alignment boundary. In order to safely free allocations made by this method, the caller must return the value in the I variable, rather than the returned pointer. +=item * + +The call to OPENSSL_aligned_alloc() may fail for reasons other than memory +exhaustion, depending on the underlying implementation, and, most notably, +OpenSSL library's build configuration: for example, it always returns C +without setting any error if OpenSSL is built with C +macro defined. Consequently, caller may need to fall back to a non-aligned +memory allocation (and open-code the alignment routine if the alignment +is a requirement). + +=back + OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when the buffer at B holds sensitive information. The old buffer is filled with zero's by calling OPENSSL_cleanse() -- 2.47.3