1=pod
2
3=head1 NAME
4
5OPENSSL_malloc_init,
6OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc,
7OPENSSL_malloc_array, OPENSSL_aligned_alloc_array, OPENSSL_calloc,
8OPENSSL_realloc_array, OPENSSL_free,
9OPENSSL_clear_realloc, OPENSSL_clear_realloc_array,
10OPENSSL_clear_free, OPENSSL_cleanse,
11CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc,
12CRYPTO_malloc_array, CRYPTO_aligned_alloc_array, CRYPTO_calloc,
13CRYPTO_realloc, CRYPTO_realloc_array, CRYPTO_free,
14OPENSSL_strdup, OPENSSL_strndup,
15OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul,
16CRYPTO_strdup, CRYPTO_strndup,
17OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
18CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
19CRYPTO_clear_realloc, CRYPTO_clear_realloc_array, CRYPTO_clear_free,
20CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn,
21CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
22CRYPTO_get_alloc_counts,
23CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
24CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb,
25OPENSSL_MALLOC_FAILURES,
26OPENSSL_MALLOC_FD,
27OPENSSL_MALLOC_SEED
28- Memory allocation functions
29
30=head1 SYNOPSIS
31
32 #include <openssl/crypto.h>
33
34 int OPENSSL_malloc_init(void);
35
36 void *OPENSSL_malloc(size_t num);
37 void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr);
38 void *OPENSSL_zalloc(size_t num);
39 void *OPENSSL_realloc(void *addr, size_t num);
40 void *OPENSSL_malloc_array(size_t num, size_t size);
41 void *OPENSSL_aligned_alloc_array(size_t num, size_t size, size_t alignment,
42                                   void **freeptr);
43 void *OPENSSL_calloc(size_t num, size_t size);
44 void *OPENSSL_realloc_array(void *addr, size_t num, size_t size);
45 void OPENSSL_free(void *addr);
46 char *OPENSSL_strdup(const char *str);
47 char *OPENSSL_strndup(const char *str, size_t s);
48 size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
49 size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
50 int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num);
51 void *OPENSSL_memdup(void *data, size_t s);
52 void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);
53 void *OPENSSL_clear_realloc_array(void *p, size_t old_len, size_t num,
54                                   size_t size);
55 void OPENSSL_clear_free(void *str, size_t num);
56 void OPENSSL_cleanse(void *ptr, size_t len);
57
58 void *CRYPTO_malloc(size_t num, const char *file, int line);
59 void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr,
60                            const char *file, int line);
61 void *CRYPTO_zalloc(size_t num, const char *file, int line);
62 void *CRYPTO_realloc(void *p, size_t num, const char *file, int line);
63 void *CRYPTO_malloc_array(size_t num, size_t size, const char *file, int line);
64 void *CRYPTO_aligned_alloc_array(size_t num, size_t size, size_t align,
65                                  void **freeptr, const char *file, int line);
66 void *CRYPTO_calloc(size_t num, size_t size, const char *file, int line);
67 void *CRYPTO_realloc_array(void *p, size_t num, size_t size,
68                            const char *file, int line);
69 void CRYPTO_free(void *str, const char *file, int line);
70 char *CRYPTO_strdup(const char *p, const char *file, int line);
71 char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line);
72 void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,
73                            const char *file, int line);
74 void *CRYPTO_clear_realloc_array(void *p, size_t old_len, size_t num,
75                                  size_t size, const char *file, int line);
76 void CRYPTO_clear_free(void *str, size_t num, const char *file, int line);
77
78 typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);
79 typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,
80                                    int line);
81 typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);
82 void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,
83                               CRYPTO_realloc_fn *realloc_fn,
84                               CRYPTO_free_fn *free_fn);
85 int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,
86                              CRYPTO_realloc_fn realloc_fn,
87                              CRYPTO_free_fn free_fn);
88
89 void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);
90
91 env OPENSSL_MALLOC_FAILURES=... <application>
92 env OPENSSL_MALLOC_FD=... <application>
93 env OPENSSL_MALLOC_SEED=... <application>
94
95The following functions have been deprecated since OpenSSL 3.0, and can be
96hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
97see L<openssl_user_macros(7)>:
98
99 int CRYPTO_mem_leaks(BIO *b);
100 int CRYPTO_mem_leaks_fp(FILE *fp);
101 int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
102                         void *u);
103
104 int CRYPTO_set_mem_debug(int onoff);
105 int CRYPTO_mem_ctrl(int mode);
106 int OPENSSL_mem_debug_push(const char *info);
107 int OPENSSL_mem_debug_pop(void);
108 int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
109 int CRYPTO_mem_debug_pop(void);
110
111=head1 DESCRIPTION
112
113OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are
114generally macro's that add the standard C B<__FILE__> and B<__LINE__>
115parameters and call a lower-level B<CRYPTO_xxx> API.
116Some functions do not add those parameters, but exist for consistency.
117
118OPENSSL_malloc_init() does nothing and does not need to be called. It is
119included for compatibility with older versions of OpenSSL.
120
121OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the
122C malloc(), realloc(), and free() functions.
123OPENSSL_zalloc() calls memset() to zero the memory before returning.
124
125OPENSSL_aligned_alloc() operates just as OPENSSL_malloc() does, but it
126allows for the caller to specify an alignment value, for instances in
127which the default alignment of malloc is insufficient for the caller's
128needs.  Note, the alignment value must be a power of 2, and the size
129specified must be a multiple of the alignment.
130NOTES:
131
132=over 4
133
134=item *
135
136The call to OPENSSL_aligned_alloc() accepts a 3rd argument, I<freeptr>
137which must point to a void pointer.  On some platforms, there is no available
138library call to obtain memory allocations with alignment greater than what
139malloc provides.  In this case, OPENSSL_aligned_alloc() implements its own
140alignment routine, allocating additional memory and offsetting the returned
141pointer to be on the requested alignment boundary.  In order to safely free
142allocations made by this method, the caller must return the value
143in the I<freeptr> variable, rather than the returned pointer.
144
145=item *
146
147The call to OPENSSL_aligned_alloc() may fail for reasons other than memory
148exhaustion, depending on the underlying implementation, and, most notably,
149OpenSSL library's build configuration:  for example, it always returns C<NULL>
150without setting any error if OpenSSL is built with C<OPENSSL_SMALL_FOOTPRINT>
151macro defined.  Consequently, caller may need to fall back to a non-aligned
152memory allocation (and open-code the alignment routine if the alignment
153is a requirement).
154
155=back
156
157OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
158when the buffer at B<addr> holds sensitive information.
159The old buffer is filled with zero's by calling OPENSSL_cleanse()
160before ultimately calling OPENSSL_free(). If the argument to OPENSSL_free() is
161NULL, nothing is done.
162
163OPENSSL_malloc_array(), OPENSSL_calloc(), OPENSSL_aligned_alloc_array(),
164OPENSSL_realloc_array(), and OPENSSL_clear_realloc_array() are variants
165of OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_aligned_alloc(),
166OPENSSL_realloc(), and OPENSSL_clear_realloc(), respectively, that accept
167an additional parameter, B<size>, which enables memory allocation
168operations for an array of B<num> members B<size> bytes each;
169these functions return an error if multiplication of B<num> and B<size>
170leads to an integer overflow, thus preventing allocations of an incorrect size.
171
172OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
173Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
174If the storage controller uses write compression, then it's possible
175that sensitive tail bytes will survive zeroization because the block of
176zeros will be compressed. If the storage controller uses wear leveling,
177then the old sensitive data will not be overwritten; rather, a block of
1780's will be written at a new physical location.
179
180OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
181equivalent C functions, except that memory is allocated by calling the
182OPENSSL_malloc() and should be released by calling OPENSSL_free().
183
184OPENSSL_strlcpy(),
185OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
186library functions and are provided for portability.
187
188OPENSSL_strtoul() is a wrapper around the POSIX function strtoul, with the same
189behaviors listed in the POSIX documentation, with the additional behavior that
190it validates the input I<str> and I<num> parameters for not being NULL, and confirms
191that at least a single byte of input has been consumed in the translation,
192returning an error in the event that no bytes were consumed.
193
194If no allocations have been done, it is possible to "swap out" the default
195implementations for OPENSSL_malloc(), OPENSSL_realloc() and OPENSSL_free()
196and replace them with alternate versions.
197CRYPTO_get_mem_functions() function fills in the given arguments with the
198function pointers for the current implementations.
199With CRYPTO_set_mem_functions(), you can specify a different set of functions.
200If any of B<malloc_fn>, B<realloc_fn>, or B<free_fn> are NULL, then
201the function is not changed.
202While it's permitted to swap out only a few and not all the functions
203with CRYPTO_set_mem_functions(), it's recommended to swap them all out
204at once.
205
206If the library is built with the C<crypto-mdebug> option, then one
207function, CRYPTO_get_alloc_counts(), and three additional environment
208variables, B<OPENSSL_MALLOC_FAILURES>, B<OPENSSL_MALLOC_FD>,
209and B<OPENSSL_MALLOC_SEED>, are available.
210
211The function CRYPTO_get_alloc_counts() fills in the number of times
212each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been
213called, into the values pointed to by B<mcount>, B<rcount>, and B<fcount>,
214respectively.  If a pointer is NULL, then the corresponding count is not stored.
215
216The variable
217B<OPENSSL_MALLOC_FAILURES> controls how often allocations should fail.
218It is a set of fields separated by semicolons, which each field is a count
219(defaulting to zero) and an optional atsign and percentage (interpreted
220as a floating point number that is rounded up to two decimal digits
221of precision, defaulting to 100).  If the count is zero, then it lasts forever.
222For example, C<100;@0.258> or C<100@0;0@0.258> means the first 100 allocations
223pass, then all other allocations (until the program exits or crashes) have
224a 0.26% chance of failing, with random(3) used as a source of randomness.
225The length of the value of B<OPENSSL_MALLOC_FAILURES> must be 256 or fewer
226characters.
227
228If the variable B<OPENSSL_MALLOC_FD> is parsed as a positive integer, then
229it is taken as an open file descriptor. This is used in conjunction with
230B<OPENSSL_MALLOC_FAILURES> described above. For every allocation it will log
231details about how many allocations there have been so far, what percentage
232chance there is for this allocation failing, and whether it has actually failed.
233The following example in classic shell syntax shows how to use this (will not
234work on all platforms):
235
236  OPENSSL_MALLOC_FAILURES='200;@10'
237  export OPENSSL_MALLOC_FAILURES
238  OPENSSL_MALLOC_FD=3
239  export OPENSSL_MALLOC_FD
240  ...app invocation... 3>/tmp/log$$
241
242If the environment variable B<OPENSSL_MALLOC_SEED> is set, its value
243is interpreted as an integer using atoi(3) and supplied to the srandom(3)
244call for the random number generator initialisation.
245
246=head1 RETURN VALUES
247
248OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
249CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
250return no value.
251
252OPENSSL_malloc(), OPENSSL_aligned_alloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
253OPENSSL_malloc_array(), OPENSSL_aligned_alloc_array(), OPENSSL_calloc(),
254OPENSSL_realloc_array(),
255OPENSSL_clear_realloc(), OPENSSL_clear_realloc_array(),
256CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
257CRYPTO_malloc_array(), CRYPTO_calloc(), CRYPTO_realloc_array(),
258CRYPTO_clear_realloc(), CRYPTO_clear_realloc_array(),
259OPENSSL_strdup(), and OPENSSL_strndup()
260return a pointer to allocated memory or NULL on error.
261
262OPENSSL_aligned_alloc() and OPENSSL_aligned_alloc_array() set B<freeptr>
263to NULL on error.
264
265CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost
266always because allocations have already happened).
267
268CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(),
269CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and are no-ops that
270always return -1.
271OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
272CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop()
273are deprecated and are no-ops that always return 0.
274
275OPENSSL_strtoul() returns 1 on success and 0 in the event that an error has
276occurred. Specifically, 0 is returned in the following events:
277
278=over 4
279
280=item *
281
282If the underlying call to strtoul returned a non zero errno value
283
284=item *
285
286If the translation did not consume the entire input string, and the passed
287endptr value was NULL
288
289=item *
290
291If no characters were consumed in the translation
292
293=back
294
295Note that a success condition does not imply that the expected
296translation has been performed.  For instance calling
297
298    OPENSSL_strtoul("0x12345", &endptr, 10, &num);
299
300will result in a successful translation with num having the value 0, and
301*endptr = 'x'.  Be sure to validate how much data was consumed when calling this
302function.
303
304=head1 HISTORY
305
306OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
307CRYPTO_mem_debug_push(), CRYPTO_mem_debug_pop(),
308CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(),
309CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl()
310were deprecated in OpenSSL 3.0.
311The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of
312clang's memory and leak sanitizer.
313OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc(), OPENSSL_strtoul() were
314added in OpenSSL 3.4.
315OPENSSL_malloc_array(), OPENSSL_calloc(), OPENSSL_aligned_alloc_array(),
316OPENSSL_realloc_array(), OPENSSL_clear_realloc_array(), CRYPTO_malloc_array(),
317CRYPTO_calloc(), CRYPTO_aligned_alloc_array(), CRYPTO_realloc_array(),
318CRYPTO_clear_realloc_array() were added in OpenSSL 3.6.
319
320=head1 COPYRIGHT
321
322Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
323
324Licensed under the Apache License 2.0 (the "License").  You may not use
325this file except in compliance with the License.  You can obtain a copy
326in the file LICENSE in the source distribution or at
327L<https://www.openssl.org/source/license.html>.
328
329=cut
330