From: Eugene Syromiatnikov Date: Thu, 31 Jul 2025 11:42:41 +0000 (+0200) Subject: doc/man3/OPENSSL_malloc.pod: document OPENSSL_aligned_alloc peculiarity X-Git-Tag: openssl-3.6.0-alpha1~208 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=704ee1348c46a4980c6918f6a7db32a322f565ab;p=thirdparty%2Fopenssl.git doc/man3/OPENSSL_malloc.pod: document OPENSSL_aligned_alloc peculiarity 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) --- 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()