]>
Commit | Line | Data |
---|---|---|
bbd86bf5 RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OPENSSL_malloc_init, | |
6 | OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free, | |
eae02924 | 7 | OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, |
bbd86bf5 RS |
8 | CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, |
9 | OPENSSL_strdup, OPENSSL_strndup, | |
10 | OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, | |
c952780c RS |
11 | CRYPTO_strdup, CRYPTO_strndup, |
12 | OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, | |
13 | CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, | |
bbd86bf5 | 14 | CRYPTO_clear_realloc, CRYPTO_clear_free, |
f4dcc09b | 15 | CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn, |
bbd86bf5 | 16 | CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, |
0e598a3d | 17 | CRYPTO_get_alloc_counts, |
bbd86bf5 | 18 | CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, |
20626cfd | 19 | CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, |
a68d8c7b RS |
20 | OPENSSL_MALLOC_FAILURES, |
21 | OPENSSL_MALLOC_FD | |
22 | - Memory allocation functions | |
bbd86bf5 RS |
23 | |
24 | =head1 SYNOPSIS | |
25 | ||
26 | #include <openssl/crypto.h> | |
27 | ||
f4dcc09b | 28 | int OPENSSL_malloc_init(void); |
bbd86bf5 | 29 | |
f4dcc09b DG |
30 | void *OPENSSL_malloc(size_t num); |
31 | void *OPENSSL_zalloc(size_t num); | |
32 | void *OPENSSL_realloc(void *addr, size_t num); | |
33 | void OPENSSL_free(void *addr); | |
34 | char *OPENSSL_strdup(const char *str); | |
35 | char *OPENSSL_strndup(const char *str, size_t s); | |
c952780c RS |
36 | size_t OPENSSL_strlcat(char *dst, const char *src, size_t size); |
37 | size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size); | |
f4dcc09b DG |
38 | void *OPENSSL_memdup(void *data, size_t s); |
39 | void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num); | |
40 | void OPENSSL_clear_free(void *str, size_t num); | |
bbd86bf5 RS |
41 | void OPENSSL_cleanse(void *ptr, size_t len); |
42 | ||
f4dcc09b DG |
43 | void *CRYPTO_malloc(size_t num, const char *file, int line); |
44 | void *CRYPTO_zalloc(size_t num, const char *file, int line); | |
45 | void *CRYPTO_realloc(void *p, size_t num, const char *file, int line); | |
46 | void CRYPTO_free(void *str, const char *, int); | |
47 | char *CRYPTO_strdup(const char *p, const char *file, int line); | |
48 | char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line); | |
e9b77246 | 49 | void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, |
f4dcc09b | 50 | const char *file, int line); |
fa9bb620 | 51 | void CRYPTO_clear_free(void *str, size_t num, const char *, int) |
bbd86bf5 | 52 | |
f4dcc09b DG |
53 | typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line); |
54 | typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file, | |
55 | int line); | |
56 | typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line); | |
57 | void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn, | |
58 | CRYPTO_realloc_fn *realloc_fn, | |
59 | CRYPTO_free_fn *free_fn); | |
60 | int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn, | |
61 | CRYPTO_realloc_fn realloc_fn, | |
62 | CRYPTO_free_fn free_fn); | |
bbd86bf5 | 63 | |
f4dcc09b | 64 | void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount); |
0e598a3d | 65 | |
a68d8c7b RS |
66 | env OPENSSL_MALLOC_FAILURES=... <application> |
67 | env OPENSSL_MALLOC_FD=... <application> | |
68 | ||
742ccab3 | 69 | Deprecated: |
bbd86bf5 | 70 | |
29f484d0 MC |
71 | int CRYPTO_mem_leaks(BIO *b); |
72 | int CRYPTO_mem_leaks_fp(FILE *fp); | |
73 | int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), | |
74 | void *u); | |
bbd86bf5 | 75 | |
742ccab3 RS |
76 | int CRYPTO_set_mem_debug(int onoff) |
77 | int CRYPTO_mem_ctrl(int mode); | |
e7aa7c11 RS |
78 | int OPENSSL_mem_debug_push(const char *info) |
79 | int OPENSSL_mem_debug_pop(void); | |
80 | int CRYPTO_mem_debug_push(const char *info, const char *file, int line); | |
81 | int CRYPTO_mem_debug_pop(void); | |
82 | ||
bbd86bf5 RS |
83 | =head1 DESCRIPTION |
84 | ||
85 | OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are | |
86 | generally macro's that add the standard C B<__FILE__> and B<__LINE__> | |
87 | parameters and call a lower-level B<CRYPTO_xxx> API. | |
88 | Some functions do not add those parameters, but exist for consistency. | |
89 | ||
ef45aa14 MC |
90 | OPENSSL_malloc_init() does nothing and does not need to be called. It is |
91 | included for compatibility with older versions of OpenSSL. | |
bbd86bf5 RS |
92 | |
93 | OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the | |
94 | C malloc(), realloc(), and free() functions. | |
95 | OPENSSL_zalloc() calls memset() to zero the memory before returning. | |
96 | ||
97 | OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used | |
98 | when the buffer at B<addr> holds sensitive information. | |
91a61513 | 99 | The old buffer is filled with zero's by calling OPENSSL_cleanse() |
bbd86bf5 RS |
100 | before ultimately calling OPENSSL_free(). |
101 | ||
91a61513 JW |
102 | OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. |
103 | Use OPENSSL_cleanse() with care if the memory is a mapping of a file. | |
1bc74519 RS |
104 | If the storage controller uses write compression, then its possible |
105 | that sensitive tail bytes will survive zeroization because the block of | |
6b4a77f5 | 106 | zeros will be compressed. If the storage controller uses wear leveling, |
1bc74519 | 107 | then the old sensitive data will not be overwritten; rather, a block of |
91a61513 JW |
108 | 0's will be written at a new physical location. |
109 | ||
bbd86bf5 RS |
110 | OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the |
111 | equivalent C functions, except that memory is allocated by calling the | |
9d22666e | 112 | OPENSSL_malloc() and should be released by calling OPENSSL_free(). |
bbd86bf5 RS |
113 | |
114 | OPENSSL_strlcpy(), | |
115 | OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C | |
116 | library functions and are provided for portability. | |
117 | ||
118 | If no allocations have been done, it is possible to "swap out" the default | |
742ccab3 RS |
119 | implementations for OPENSSL_malloc(), OPENSSL_realloc() and OPENSSL_free() |
120 | and replace them with alternate versions. | |
fa9bb620 RL |
121 | CRYPTO_get_mem_functions() function fills in the given arguments with the |
122 | function pointers for the current implementations. | |
123 | With CRYPTO_set_mem_functions(), you can specify a different set of functions. | |
f4dcc09b DG |
124 | If any of B<malloc_fn>, B<realloc_fn>, or B<free_fn> are NULL, then |
125 | the function is not changed. | |
742ccab3 RS |
126 | While it's permitted to swap out only a few and not all the functions |
127 | with CRYPTO_set_mem_functions(), it's recommended to swap them all out | |
128 | at once. | |
20626cfd | 129 | |
0e598a3d RS |
130 | If the library is built with the C<crypto-mdebug> option, then one |
131 | function, CRYPTO_get_alloc_counts(), and two additional environment | |
132 | variables, B<OPENSSL_MALLOC_FAILURES> and B<OPENSSL_MALLOC_FD>, | |
133 | are available. | |
134 | ||
135 | The function CRYPTO_get_alloc_counts() fills in the number of times | |
136 | each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been | |
137 | called, into the values pointed to by B<mcount>, B<rcount>, and B<fcount>, | |
138 | respectively. If a pointer is NULL, then the corresponding count is not stored. | |
139 | ||
140 | The variable | |
141 | B<OPENSSL_MALLOC_FAILURES> controls how often allocations should fail. | |
142 | It is a set of fields separated by semicolons, which each field is a count | |
143 | (defaulting to zero) and an optional atsign and percentage (defaulting | |
144 | to 100). If the count is zero, then it lasts forever. For example, | |
145 | C<100;@25> or C<100@0;0@25> means the first 100 allocations pass, then all | |
146 | other allocations (until the program exits or crashes) have a 25% chance of | |
147 | failing. | |
148 | ||
149 | If the variable B<OPENSSL_MALLOC_FD> is parsed as a positive integer, then | |
150 | it is taken as an open file descriptor, and a record of all allocations is | |
151 | written to that descriptor. If an allocation will fail, and the platform | |
152 | supports it, then a backtrace will be written to the descriptor. This can | |
153 | be useful because a malloc may fail but not be checked, and problems will | |
154 | only occur later. The following example in classic shell syntax shows how | |
155 | to use this (will not work on all platforms): | |
156 | ||
157 | OPENSSL_MALLOC_FAILURES='200;@10' | |
158 | export OPENSSL_MALLOC_FAILURES | |
159 | OPENSSL_MALLOC_FD=3 | |
160 | export OPENSSL_MALLOC_FD | |
161 | ...app invocation... 3>/tmp/log$$ | |
162 | ||
bbd86bf5 RS |
163 | =head1 RETURN VALUES |
164 | ||
165 | OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() | |
4e482ae6 | 166 | CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() |
bbd86bf5 RS |
167 | return no value. |
168 | ||
169 | OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), | |
170 | OPENSSL_clear_realloc(), | |
171 | CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), | |
172 | CRYPTO_clear_realloc(), | |
173 | OPENSSL_strdup(), and OPENSSL_strndup() | |
174 | return a pointer to allocated memory or NULL on error. | |
175 | ||
742ccab3 | 176 | CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost |
bbd86bf5 RS |
177 | always because allocations have already happened). |
178 | ||
742ccab3 RS |
179 | CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), |
180 | CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and return -1. | |
181 | OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), | |
182 | CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop() | |
183 | are deprecated and return 0. | |
e7aa7c11 RS |
184 | |
185 | =head1 HISTORY | |
186 | ||
187 | OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), | |
742ccab3 RS |
188 | CRYPTO_mem_debug_push(), CRYPTO_mem_debug_pop(), |
189 | CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), | |
190 | CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl() | |
e7aa7c11 | 191 | were deprecated in OpenSSL 3.0. |
742ccab3 RS |
192 | The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of |
193 | clang's memory and leak sanitizer. | |
e7aa7c11 | 194 | |
fa9bb620 | 195 | |
e2f92610 RS |
196 | =head1 COPYRIGHT |
197 | ||
28428130 | 198 | Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 199 | |
4746f25a | 200 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
201 | this file except in compliance with the License. You can obtain a copy |
202 | in the file LICENSE in the source distribution or at | |
203 | L<https://www.openssl.org/source/license.html>. | |
204 | ||
205 | =cut |