OPENSSL_MALLOC(3SSL)

📦

version 4.0.3 · 3 versions

✨ OPENSSL_MALLOC 💖 — Memory allocation functions ✨

okay bestie, sit down, hydrate, because we are about to talk about memory allocation in OpenSSL and honestly? it's giving ✨foundational✨. this is the OPENSSL_MALLOC(3SSL) page, and it's a big one, so we're doing it in parts. part 1 is the header + synopsis, and the juicy lore comes after. no cap. 🫶

🌸 NAME 🌸

bestie, this page is the home base for so many functions. like, an unreasonable amount. here's literally every single one of them, and yes you need to know they all live here:

OPENSSL_malloc_init
OPENSSL_malloc
OPENSSL_aligned_alloc
OPENSSL_zalloc
OPENSSL_realloc
OPENSSL_malloc_array
OPENSSL_aligned_alloc_array
OPENSSL_calloc
OPENSSL_realloc_array
OPENSSL_free
OPENSSL_clear_realloc
OPENSSL_clear_realloc_array
OPENSSL_clear_free
OPENSSL_cleanse
CRYPTO_malloc
CRYPTO_aligned_alloc
CRYPTO_zalloc
CRYPTO_malloc_array
CRYPTO_aligned_alloc_array
CRYPTO_calloc
CRYPTO_realloc
CRYPTO_realloc_array
CRYPTO_free
OPENSSL_strdup
OPENSSL_strndup
OPENSSL_memdup
OPENSSL_strlcpy
OPENSSL_strlcat
OPENSSL_strtoul
CRYPTO_strdup
CRYPTO_strndup
CRYPTO_memdup
OPENSSL_mem_debug_push
OPENSSL_mem_debug_pop
CRYPTO_mem_debug_push
CRYPTO_mem_debug_pop
CRYPTO_clear_realloc
CRYPTO_clear_realloc_array
CRYPTO_clear_free
CRYPTO_malloc_fn
CRYPTO_realloc_fn
CRYPTO_free_fn
CRYPTO_get_mem_functions
CRYPTO_set_mem_functions
CRYPTO_get_alloc_counts
CRYPTO_set_mem_debug
CRYPTO_mem_ctrl
CRYPTO_mem_leaks
CRYPTO_mem_leaks_fp
CRYPTO_mem_leaks_cb
OPENSSL_MALLOC_FAILURES
OPENSSL_MALLOC_FD
OPENSSL_MALLOC_SEED

and the whole vibe of the page? Memory allocation functions. that's the vibe. that's the assignment. 💅

✨ SYNOPSIS ✨

here's the receipts, bestie — every signature, verbatim, because we do not paraphrase prototypes in this house:

#include <openssl/crypto.h>

int OPENSSL_malloc_init(void);

void *OPENSSL_malloc(size_t num);
void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr);
void *OPENSSL_zalloc(size_t num);
void *OPENSSL_realloc(void *addr, size_t num);
void *OPENSSL_malloc_array(size_t num, size_t size);
void *OPENSSL_aligned_alloc_array(size_t num, size_t size, size_t alignment,
                                  void **freeptr);
void *OPENSSL_calloc(size_t num, size_t size);
void *OPENSSL_realloc_array(void *addr, size_t num, size_t size);
void OPENSSL_free(void *addr);
char *OPENSSL_strdup(const char *str);
char *OPENSSL_strndup(const char *str, size_t s);
size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num);
void *OPENSSL_memdup(void *data, size_t s);
void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);
void *OPENSSL_clear_realloc_array(void *p, size_t old_len, size_t num,
                                  size_t size);
void OPENSSL_clear_free(void *str, size_t num);
void OPENSSL_cleanse(void *ptr, size_t len);

void *CRYPTO_malloc(size_t num, const char *file, int line);
void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr,
                           const char *file, int line);
void *CRYPTO_zalloc(size_t num, const char *file, int line);
void *CRYPTO_realloc(void *p, size_t num, const char *file, int line);
void *CRYPTO_malloc_array(size_t num, size_t size, const char *file, int line);
void *CRYPTO_aligned_alloc_array(size_t num, size_t size, size_t align,
                                 void **freeptr, const char *file, int line);
void *CRYPTO_calloc(size_t num, size_t size, const char *file, int line);
void *CRYPTO_realloc_array(void *p, size_t num, size_t size,
                           const char *file, int line);
void CRYPTO_free(void *str, const char *file, int line);
char *CRYPTO_strdup(const char *p, const char *file, int line);
char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line);
void *CRYPTO_memdup(void *data, size_t s, const char *file, int line);
void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,
                           const char *file, int line);
void *CRYPTO_clear_realloc_array(void *p, size_t old_len, size_t num,
                                 size_t size, const char *file, int line);
void CRYPTO_clear_free(void *str, size_t num, const char *file, int line);

typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);
typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,
                                   int line);
typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);
void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,
                              CRYPTO_realloc_fn *realloc_fn,
                              CRYPTO_free_fn *free_fn);
int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,
                             CRYPTO_realloc_fn realloc_fn,
                             CRYPTO_free_fn free_fn);

void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);

env OPENSSL_MALLOC_FAILURES=... <application>
env OPENSSL_MALLOC_FD=... <application>
env OPENSSL_MALLOC_SEED=... <application>

💀 the deprecated girlies 💀

okay so heads up bestie, these ones have been deprecated since OpenSSL 3.0 — they're the vintage collection. you can hide them entirely by defining OPENSSL_API_COMPAT with a suitable version value, and there's more tea on that in openssl_user_macros(7). 👑

like, if you're writing new code, please don't reach for these. they're giving legacy. iykyk. 💅

int CRYPTO_mem_leaks(BIO *b);
int CRYPTO_mem_leaks_fp(FILE *fp);
int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
                        void *u);

int CRYPTO_set_mem_debug(int onoff);
int CRYPTO_mem_ctrl(int mode);
int OPENSSL_mem_debug_push(const char *info);
int OPENSSL_mem_debug_pop(void);
int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
int CRYPTO_mem_debug_pop(void);

🦋 okay that's the header, the full NAME roster, and the whole SYNOPSIS wrapped up, bestie. the actual vibes — descriptions, options, all the lore — is coming up next, so don't go anywhere. 🌈

💖 DESCRIPTION 💖

okay so bestie, here's the tea on how OpenSSL does memory: it's all handled by the OPENSSL_xxx API. These are generally macros — like, they sneak in the standard C __FILE__ and __LINE__ parameters for you and then call a lower-level CRYPTO_xxx API. Some functions don't add those parameters, but they exist anyway for consistency. it's giving ✨thorough✨

OPENSSL_malloc_init() does absolutely nothing and you do not need to call it. It's just there for compatibility with older versions of OpenSSL. a participation trophy, honestly. 💀

OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are literally just like the C malloc(), realloc(), and free() functions. And OPENSSL_zalloc()? It calls memset() to zero the memory before returning. clean girl aesthetic 🎀

OPENSSL_aligned_alloc() operates just as OPENSSL_malloc() does, but it lets you specify an alignment value — for the instances where the default alignment of malloc just isn't enough for what you need. Note this though: the alignment value must be a power of 2 no larger than 65536.

NOTE: the call to OPENSSL_aligned_alloc() accepts a 3rd argument, freeptr, which must point to a void pointer. 💅

On some platforms, there's no available library call to get memory allocations with alignment greater than what malloc provides. In that case, OPENSSL_aligned_alloc() implements its own alignment routine — allocating additional memory and offsetting the returned pointer so it lands on the requested alignment boundary. And here's the crucial part: to safely free allocations made by this method, the caller must return the value in the freeptr variable, rather than the returned pointer. do NOT skip that. 🫶

OPENSSL_clear_realloc() and OPENSSL_clear_free() — use these besties when the buffer at addr holds sensitive information. The old buffer gets filled with zero's by calling OPENSSL_cleanse() before ultimately calling OPENSSL_free(). And if the argument to OPENSSL_clear_free() is NULL, nothing is done. no drama, no work. 😌

OPENSSL_malloc_array(), OPENSSL_calloc(), OPENSSL_aligned_alloc_array(), OPENSSL_realloc_array(), and OPENSSL_clear_realloc_array() are variants of OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_aligned_alloc(), OPENSSL_realloc(), and OPENSSL_clear_realloc(), respectively — except they take an additional parameter, size, which enables memory allocation operations for an array of num members size bytes each. These functions return an error if multiplying num and size leads to an integer overflow, which prevents allocations of an incorrect size. protection era 🛡️

OPENSSL_cleanse() fills ptr of size len with a string of 0's. It's useful when you need to make sure memory (the kind containing sensitive information) actually gets overwritten — for example before it's reclaimed, or when it's stored on the stack — and that this operation does not get optimised out by compiler optimisations such as dead store elimination (because memset(3) totally can 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 zeros will be compressed 😭
if the storage controller uses wear leveling, then the old sensitive data will not be overwritten; rather, a block of 0's will be written at a new physical location 💀

OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the equivalent C functions, except that memory is allocated by calling OPENSSL_malloc() and should be released by calling OPENSSL_free(). team players fr fr.

OPENSSL_strlcpy(), OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C library functions and they're provided for portability. 🌈

OPENSSL_strtoul() is a wrapper around the POSIX function strtoul, with the same behaviors listed in the POSIX documentation, plus this extra behavior: it validates the input str and num parameters for not being NULL, and confirms that at least a single byte of input has been consumed in the translation, returning an error in the event that no bytes were consumed. picky in a responsible way 👑

If no allocations have been done, it's possible to "swap out" the default implementations for OPENSSL_malloc(), OPENSSL_realloc() and OPENSSL_free() and replace them with alternate versions. The CRYPTO_get_mem_functions() function fills in the given arguments with the function pointers for the current implementations. With CRYPTO_set_mem_functions(), you can specify a different set of functions. If any of malloc_fn, realloc_fn, or free_fn are NULL, then the function is not changed. And while it's permitted to swap out only a few and not all the functions with CRYPTO_set_mem_functions(), it's recommended to swap them all out at once. no half-glow-ups, babe.

If the library is built with the "crypto-mdebug" option, then one function, CRYPTO_get_alloc_counts(), and three additional environment variables, OPENSSL_MALLOC_FAILURES, OPENSSL_MALLOC_FD, and OPENSSL_MALLOC_SEED, are available. 🦋

The function CRYPTO_get_alloc_counts() fills in the number of times each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been called, into the values pointed to by mcount, rcount, and fcount, respectively. If a pointer is NULL, then the corresponding count is not stored. simple as. ✨

The variable OPENSSL_MALLOC_FAILURES controls how often allocations should fail. It's a set of fields separated by semicolons, where each field is a count (defaulting to zero) and an optional atsign and percentage (interpreted as a floating point number that is rounded up to two decimal digits of precision, defaulting to 100). If the count is zero, then it lasts forever. For example, "100;@0.258" or "100@0;0@0.258" means the first 100 allocations pass, then all other allocations (until the program exits or crashes) have a 0.26% chance of failing, with random(3) used as a source of randomness. The length of the value of OPENSSL_MALLOC_FAILURES must be 256 or fewer characters. 📏

If the variable OPENSSL_MALLOC_FD is parsed as a positive integer, then it is taken as an open file descriptor. This is used in conjunction with OPENSSL_MALLOC_FAILURES described above. For every allocation it will log details about how many allocations there have been so far, what percentage chance there is for this allocation failing, and whether it has actually failed. The following example in classic shell syntax shows how to use this (will not work on all platforms):

OPENSSL_MALLOC_FAILURES='200;@10'
export OPENSSL_MALLOC_FAILURES
OPENSSL_MALLOC_FD=3
export OPENSSL_MALLOC_FD
...app invocation... 3>/tmp/log$$

If the environment variable OPENSSL_MALLOC_SEED is set, its value is interpreted as an integer using atoi(3) and supplied to the srandom(3) call for the random number generator initialisation. 🎲

🫶 RETURN VALUES 🫶

OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free(), CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() return no value. they simply do not do that.

OPENSSL_malloc(), OPENSSL_aligned_alloc(), OPENSSL_zalloc(), OPENSSL_realloc(), OPENSSL_malloc_array(), OPENSSL_aligned_alloc_array(), OPENSSL_calloc(), OPENSSL_realloc_array(), OPENSSL_clear_realloc(), OPENSSL_clear_realloc_array(), OPENSSL_strdup(), OPENSSL_strndup(), OPENSSL_memdup(), CRYPTO_malloc(), CRYPTO_aligned_alloc(), CRYPTO_zalloc(), CRYPTO_realloc(), CRYPTO_malloc_array(), CRYPTO_aligned_alloc_array(), CRYPTO_calloc(), CRYPTO_realloc_array(), CRYPTO_clear_realloc(), CRYPTO_clear_realloc_array(), CRYPTO_strdup(), CRYPTO_strndup(), and CRYPTO_memdup() return a pointer to allocated memory, or NULL on error. 💖

OPENSSL_aligned_alloc(), OPENSSL_aligned_alloc_array(), CRYPTO_aligned_alloc(), and CRYPTO_aligned_alloc_array() set freeptr to NULL on error. noted. 🫡

CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost always because allocations have already happened). it's giving "you missed your window, bestie".

CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and are no-ops that always return -1. OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop() are deprecated and are no-ops that always return 0. 💀

OPENSSL_strtoul() returns 1 on success and 0 in the event that an error has occurred. Specifically, 0 is returned in the following events:

If the underlying call to strtoul returned a non zero errno value
If the translation did not consume the entire input string, and the passed endptr value was NULL
If no characters were consumed in the translation

Note that a success condition does not imply that the expected translation has been performed. For instance calling

OPENSSL_strtoul("0x12345", &endptr, 10, &num);

will result in a successful translation with num having the value 0, and *endptr = 'x'. So be sure to validate how much data was consumed when calling this function. the audacity of this function honestly 😭

📜 HISTORY 📜

OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), CRYPTO_mem_debug_pop(), CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl() were deprecated in OpenSSL 3.0. The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of clang's memory and leak sanitizer. ✨

OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc(), OPENSSL_strtoul() were added in OpenSSL 3.4. 💅

OPENSSL_malloc_array(), OPENSSL_calloc(), OPENSSL_aligned_alloc_array(), OPENSSL_realloc_array(), OPENSSL_clear_realloc_array(), CRYPTO_malloc_array(), CRYPTO_calloc(), CRYPTO_aligned_alloc_array(), CRYPTO_realloc_array(), CRYPTO_clear_realloc_array() were added in OpenSSL 3.6. 👑

Before OpenSSL 3.6, there was an OPENSSL_aligned_malloc() requirement that the size must be a multiple of the alignment, that was enforced only on platforms that do not provide posix_memalign(3), but do provide aligned_alloc(3).

Before OpenSSL 4.0, the call to OPENSSL_aligned_alloc() may fail for reasons other than memory exhaustion or incorrect arguments, depending on the underlying implementation, and, most notably, OpenSSL library's build configuration: for example, it always returned "NULL" without setting any error if OpenSSL was built with "OPENSSL_SMALL_FOOTPRINT" macro defined. Consequently, the caller may need to fall back to a non-aligned memory allocation (and open-code the alignment routine if the alignment is a requirement). 🙈

Before OpenSSL 4.0, the call to OPENSSL_aligned_alloc() did not have an explicit upper limit on the value of alignment. wild. 😭

⚖️ COPYRIGHT ⚖️

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's a wrap on this iconic page, bestie 🎀 this was the 4.0.3 version, dated 2026-09-29 — so if you're reading a different release, go check your own copy, mkay? stay allocated, stay cleansed, and don't forget your freeptr. 💜🦋✨

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms