Debian Codegraph @

upstream/debian-trixie/man3/OPENSSL_malloc.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL_MALLOC 3SSL"
58 .TH OPENSSL_MALLOC 3SSL 2026-04-07 3.5.6 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OPENSSL_malloc_init,
65 OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc,
66 OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
67 CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
68 OPENSSL_strdup, OPENSSL_strndup,
69 OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul,
70 CRYPTO_strdup, CRYPTO_strndup,
71 OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
72 CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
73 CRYPTO_clear_realloc, CRYPTO_clear_free,
74 CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn,
75 CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
76 CRYPTO_get_alloc_counts,
77 CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
78 CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb,
79 OPENSSL_MALLOC_FAILURES,
80 OPENSSL_MALLOC_FD
81 \&\- Memory allocation functions
82 .SH SYNOPSIS
83 .IX Header "SYNOPSIS"
84 .Vb 1
85 \& #include <openssl/crypto.h>
86 \&
87 \& int OPENSSL_malloc_init(void);
88 \&
89 \& void *OPENSSL_malloc(size_t num);
90 \& void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr);
91 \& void *OPENSSL_zalloc(size_t num);
92 \& void *OPENSSL_realloc(void *addr, size_t num);
93 \& void OPENSSL_free(void *addr);
94 \& char *OPENSSL_strdup(const char *str);
95 \& char *OPENSSL_strndup(const char *str, size_t s);
96 \& size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
97 \& size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
98 \& int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num);
99 \& void *OPENSSL_memdup(void *data, size_t s);
100 \& void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);
101 \& void OPENSSL_clear_free(void *str, size_t num);
102 \& void OPENSSL_cleanse(void *ptr, size_t len);
103 \&
104 \& void *CRYPTO_malloc(size_t num, const char *file, int line);
105 \& void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr,
106 \& const char *file, int line);
107 \& void *CRYPTO_zalloc(size_t num, const char *file, int line);
108 \& void *CRYPTO_realloc(void *p, size_t num, const char *file, int line);
109 \& void CRYPTO_free(void *str, const char *, int);
110 \& char *CRYPTO_strdup(const char *p, const char *file, int line);
111 \& char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line);
112 \& void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,
113 \& const char *file, int line);
114 \& void CRYPTO_clear_free(void *str, size_t num, const char *, int);
115 \&
116 \& typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);
117 \& typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,
118 \& int line);
119 \& typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);
120 \& void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,
121 \& CRYPTO_realloc_fn *realloc_fn,
122 \& CRYPTO_free_fn *free_fn);
123 \& int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,
124 \& CRYPTO_realloc_fn realloc_fn,
125 \& CRYPTO_free_fn free_fn);
126 \&
127 \& void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);
128 \&
129 \& env OPENSSL_MALLOC_FAILURES=... <application>
130 \& env OPENSSL_MALLOC_FD=... <application>
131 .Ve
132 .PP
133 The following functions have been deprecated since OpenSSL 3.0, and can be
134 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
135 see \fBopenssl_user_macros\fR\|(7):
136 .PP
137 .Vb 4
138 \& int CRYPTO_mem_leaks(BIO *b);
139 \& int CRYPTO_mem_leaks_fp(FILE *fp);
140 \& int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
141 \& void *u);
142 \&
143 \& int CRYPTO_set_mem_debug(int onoff);
144 \& int CRYPTO_mem_ctrl(int mode);
145 \& int OPENSSL_mem_debug_push(const char *info);
146 \& int OPENSSL_mem_debug_pop(void);
147 \& int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
148 \& int CRYPTO_mem_debug_pop(void);
149 .Ve
150 .SH DESCRIPTION
151 .IX Header "DESCRIPTION"
152 OpenSSL memory allocation is handled by the \fBOPENSSL_xxx\fR API. These are
153 generally macro's that add the standard C \fB_\|_FILE_\|_\fR and \fB_\|_LINE_\|_\fR
154 parameters and call a lower-level \fBCRYPTO_xxx\fR API.
155 Some functions do not add those parameters, but exist for consistency.
156 .PP
157 \&\fBOPENSSL_malloc_init()\fR does nothing and does not need to be called. It is
158 included for compatibility with older versions of OpenSSL.
159 .PP
160 \&\fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR, and \fBOPENSSL_free()\fR are like the
161 C \fBmalloc()\fR, \fBrealloc()\fR, and \fBfree()\fR functions.
162 \&\fBOPENSSL_zalloc()\fR calls \fBmemset()\fR to zero the memory before returning.
163 .PP
164 \&\fBOPENSSL_aligned_alloc()\fR operates just as OPENSSL_malloc does, but it
165 allows for the caller to specify an alignment value, for instances in
166 which the default alignment of malloc is insufficient for the callers
167 needs. Note, the alignment value must be a power of 2, and the size
168 specified must be a multiple of the alignment.
169 NOTE: The call to \fBOPENSSL_aligned_alloc()\fR accepts a 3rd argument, \fIfreeptr\fR
170 which must point to a void pointer. On some platforms, there is no available
171 library call to obtain memory allocations greater than what malloc provides. In
172 this case, OPENSSL_aligned_alloc implements its own alignment routine,
173 allocating additional memory and offsetting the returned pointer to be on the
174 requested alignment boundary. In order to safely free allocations made by this
175 method, the caller must return the value in the \fIfreeptr\fR variable, rather than
176 the returned pointer.
177 .PP
178 \&\fBOPENSSL_clear_realloc()\fR and \fBOPENSSL_clear_free()\fR should be used
179 when the buffer at \fBaddr\fR holds sensitive information.
180 The old buffer is filled with zero's by calling \fBOPENSSL_cleanse()\fR
181 before ultimately calling \fBOPENSSL_free()\fR. If the argument to
182 \&\fBOPENSSL_clear_free()\fR is NULL, nothing is done.
183 .PP
184 \&\fBOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0's.
185 It is useful in cases when it is needed to ensure that memory (that contains
186 sensitive information) is overwritten (for example, before it is reclaimed,
187 or when it is stored on stack), and such operation is not optimised out
188 by compiler optimisations such as dead store elimination (as \fBmemset\fR\|(3) may be).
189 Use \fBOPENSSL_cleanse()\fR with care if the memory is a mapping of a file.
190 If the storage controller uses write compression, then it's possible
191 that sensitive tail bytes will survive zeroization because the block of
192 zeros will be compressed. If the storage controller uses wear leveling,
193 then the old sensitive data will not be overwritten; rather, a block of
194 0's will be written at a new physical location.
195 .PP
196 \&\fBOPENSSL_strdup()\fR, \fBOPENSSL_strndup()\fR and \fBOPENSSL_memdup()\fR are like the
197 equivalent C functions, except that memory is allocated by calling the
198 \&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR.
199 .PP
200 \&\fBOPENSSL_strlcpy()\fR,
201 \&\fBOPENSSL_strlcat()\fR and \fBOPENSSL_strnlen()\fR are equivalents of the common C
202 library functions and are provided for portability.
203 .PP
204 \&\fBOPENSSL_strtoul()\fR is a wrapper around the POSIX function strtoul, with the same
205 behaviors listed in the POSIX documentation, with the additional behavior that
206 it validates the input \fIstr\fR and \fInum\fR parameters for not being NULL, and confirms
207 that at least a single byte of input has been consumed in the translation,
208 returning an error in the event that no bytes were consumed.
209 .PP
210 If no allocations have been done, it is possible to "swap out" the default
211 implementations for \fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR and \fBOPENSSL_free()\fR
212 and replace them with alternate versions.
213 \&\fBCRYPTO_get_mem_functions()\fR function fills in the given arguments with the
214 function pointers for the current implementations.
215 With \fBCRYPTO_set_mem_functions()\fR, you can specify a different set of functions.
216 If any of \fBmalloc_fn\fR, \fBrealloc_fn\fR, or \fBfree_fn\fR are NULL, then
217 the function is not changed.
218 While it's permitted to swap out only a few and not all the functions
219 with \fBCRYPTO_set_mem_functions()\fR, it's recommended to swap them all out
220 at once.
221 .PP
222 If the library is built with the \f(CW\*(C`crypto\-mdebug\*(C'\fR option, then one
223 function, \fBCRYPTO_get_alloc_counts()\fR, and two additional environment
224 variables, \fBOPENSSL_MALLOC_FAILURES\fR and \fBOPENSSL_MALLOC_FD\fR,
225 are available.
226 .PP
227 The function \fBCRYPTO_get_alloc_counts()\fR fills in the number of times
228 each of \fBCRYPTO_malloc()\fR, \fBCRYPTO_realloc()\fR, and \fBCRYPTO_free()\fR have been
229 called, into the values pointed to by \fBmcount\fR, \fBrcount\fR, and \fBfcount\fR,
230 respectively. If a pointer is NULL, then the corresponding count is not stored.
231 .PP
232 The variable
233 \&\fBOPENSSL_MALLOC_FAILURES\fR controls how often allocations should fail.
234 It is a set of fields separated by semicolons, which each field is a count
235 (defaulting to zero) and an optional atsign and percentage (defaulting
236 to 100). If the count is zero, then it lasts forever. For example,
237 \&\f(CW\*(C`100;@25\*(C'\fR or \f(CW\*(C`100@0;0@25\*(C'\fR means the first 100 allocations pass, then all
238 other allocations (until the program exits or crashes) have a 25% chance of
239 failing. The length of the value of \fBOPENSSL_MALLOC_FAILURES\fR must be 256 or
240 fewer characters.
241 .PP
242 If the variable \fBOPENSSL_MALLOC_FD\fR is parsed as a positive integer, then
243 it is taken as an open file descriptor. This is used in conjunction with
244 \&\fBOPENSSL_MALLOC_FAILURES\fR described above. For every allocation it will log
245 details about how many allocations there have been so far, what percentage
246 chance there is for this allocation failing, and whether it has actually failed.
247 The following example in classic shell syntax shows how to use this (will not
248 work on all platforms):
249 .PP
250 .Vb 5
251 \& OPENSSL_MALLOC_FAILURES=\*(Aq200;@10\*(Aq
252 \& export OPENSSL_MALLOC_FAILURES
253 \& OPENSSL_MALLOC_FD=3
254 \& export OPENSSL_MALLOC_FD
255 \& ...app invocation... 3>/tmp/log$$
256 .Ve
257 .SH "RETURN VALUES"
258 .IX Header "RETURN VALUES"
259 \&\fBOPENSSL_malloc_init()\fR, \fBOPENSSL_free()\fR, \fBOPENSSL_clear_free()\fR
260 \&\fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR and \fBCRYPTO_get_mem_functions()\fR
261 return no value.
262 .PP
263 \&\fBOPENSSL_malloc()\fR, \fBOPENSSL_aligned_alloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_realloc()\fR,
264 \&\fBOPENSSL_clear_realloc()\fR,
265 \&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_realloc()\fR,
266 \&\fBCRYPTO_clear_realloc()\fR,
267 \&\fBOPENSSL_strdup()\fR, and \fBOPENSSL_strndup()\fR
268 return a pointer to allocated memory or NULL on error.
269 .PP
270 \&\fBCRYPTO_set_mem_functions()\fR returns 1 on success or 0 on failure (almost
271 always because allocations have already happened).
272 .PP
273 \&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, \fBCRYPTO_mem_leaks_cb()\fR,
274 \&\fBCRYPTO_set_mem_debug()\fR, and \fBCRYPTO_mem_ctrl()\fR are deprecated and are no-ops that
275 always return \-1.
276 \&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR,
277 \&\fBCRYPTO_mem_debug_push()\fR, and \fBCRYPTO_mem_debug_pop()\fR
278 are deprecated and are no-ops that always return 0.
279 .PP
280 \&\fBOPENSSL_strtoul()\fR returns 1 on success and 0 in the event that an error has
281 occurred. Specifically, 0 is returned in the following events:
282 .IP \(bu 4
283 If the underlying call to strtoul returned a non zero errno value
284 .IP \(bu 4
285 If the translation did not consume the entire input string, and the passed
286 endptr value was NULL
287 .IP \(bu 4
288 If no characters were consumed in the translation
289 .PP
290 Note that a success condition does not imply that the expected
291 translation has been performed. For instance calling
292 .PP
293 .Vb 1
294 \& OPENSSL_strtoul("0x12345", &endptr, 10, &num);
295 .Ve
296 .PP
297 will result in a successful translation with num having the value 0, and
298 *endptr = 'x'. Be sure to validate how much data was consumed when calling this
299 function.
300 .SH HISTORY
301 .IX Header "HISTORY"
302 \&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR,
303 \&\fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_pop()\fR,
304 \&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR,
305 \&\fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_set_mem_debug()\fR, \fBCRYPTO_mem_ctrl()\fR
306 were deprecated in OpenSSL 3.0.
307 The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of
308 clang's memory and leak sanitizer.
309 \&\fBOPENSSL_aligned_alloc()\fR, \fBCRYPTO_aligned_alloc()\fR, \fBOPENSSL_strtoul()\fR were
310 added in OpenSSL 3.4.
311 .SH COPYRIGHT
312 .IX Header "COPYRIGHT"
313 Copyright 2016\-2026 The OpenSSL Project Authors. All Rights Reserved.
314 .PP
315 Licensed under the Apache License 2.0 (the "License"). You may not use
316 this file except in compliance with the License. You can obtain a copy
317 in the file LICENSE in the source distribution or at
318 <https://www.openssl.org/source/license.html>.