]>
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, | |
14f051a0 | 11 | OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int, |
c952780c RS |
12 | CRYPTO_strdup, CRYPTO_strndup, |
13 | OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, | |
14 | CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, | |
bbd86bf5 RS |
15 | CRYPTO_clear_realloc, CRYPTO_clear_free, |
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 | ||
28 | int OPENSSL_malloc_init(void) | |
29 | ||
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); | |
38 | void *OPENSSL_memdup(void *data, size_t s) | |
bbd86bf5 RS |
39 | void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num) |
40 | void OPENSSL_clear_free(void *str, size_t num) | |
41 | void OPENSSL_cleanse(void *ptr, size_t len); | |
42 | ||
14f051a0 RS |
43 | unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); |
44 | char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len); | |
45 | int OPENSSL_hexchar2int(unsigned char c); | |
46 | ||
bbd86bf5 RS |
47 | void *CRYPTO_malloc(size_t num, const char *file, int line) |
48 | void *CRYPTO_zalloc(size_t num, const char *file, int line) | |
49 | void *CRYPTO_realloc(void *p, size_t num, const char *file, int line) | |
fa9bb620 | 50 | void CRYPTO_free(void *str, const char *, int) |
bbd86bf5 RS |
51 | char *CRYPTO_strdup(const char *p, const char *file, int line) |
52 | char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line) | |
e9b77246 BB |
53 | void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, |
54 | const char *file, int line) | |
fa9bb620 | 55 | void CRYPTO_clear_free(void *str, size_t num, const char *, int) |
bbd86bf5 RS |
56 | |
57 | void CRYPTO_get_mem_functions( | |
58 | void *(**m)(size_t, const char *, int), | |
59 | void *(**r)(void *, size_t, const char *, int), | |
fa9bb620 | 60 | void (**f)(void *, const char *, int)) |
bbd86bf5 RS |
61 | int CRYPTO_set_mem_functions( |
62 | void *(*m)(size_t, const char *, int), | |
63 | void *(*r)(void *, size_t, const char *, int), | |
fa9bb620 | 64 | void (*f)(void *, const char *, int)) |
bbd86bf5 | 65 | |
0e598a3d RS |
66 | void CRYPTO_get_alloc_counts(int *m, int *r, int *f) |
67 | ||
bbd86bf5 RS |
68 | int CRYPTO_set_mem_debug(int onoff) |
69 | ||
a68d8c7b RS |
70 | env OPENSSL_MALLOC_FAILURES=... <application> |
71 | env OPENSSL_MALLOC_FD=... <application> | |
72 | ||
c2e27310 | 73 | int CRYPTO_mem_ctrl(int mode); |
bbd86bf5 RS |
74 | |
75 | int OPENSSL_mem_debug_push(const char *info) | |
c952780c | 76 | int OPENSSL_mem_debug_pop(void); |
bbd86bf5 RS |
77 | |
78 | int CRYPTO_mem_debug_push(const char *info, const char *file, int line); | |
c952780c | 79 | int CRYPTO_mem_debug_pop(void); |
bbd86bf5 RS |
80 | |
81 | void CRYPTO_mem_leaks(BIO *b); | |
c952780c | 82 | void CRYPTO_mem_leaks_fp(FILE *fp); |
20626cfd RL |
83 | void CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), |
84 | void *u); | |
bbd86bf5 RS |
85 | |
86 | =head1 DESCRIPTION | |
87 | ||
88 | OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are | |
89 | generally macro's that add the standard C B<__FILE__> and B<__LINE__> | |
90 | parameters and call a lower-level B<CRYPTO_xxx> API. | |
91 | Some functions do not add those parameters, but exist for consistency. | |
92 | ||
93 | OPENSSL_malloc_init() sets the lower-level memory allocation functions | |
94 | to their default implementation. | |
95 | It is generally not necessary to call this, except perhaps in certain | |
96 | shared-library situations. | |
97 | ||
98 | OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the | |
99 | C malloc(), realloc(), and free() functions. | |
100 | OPENSSL_zalloc() calls memset() to zero the memory before returning. | |
101 | ||
102 | OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used | |
103 | when the buffer at B<addr> holds sensitive information. | |
91a61513 | 104 | The old buffer is filled with zero's by calling OPENSSL_cleanse() |
bbd86bf5 RS |
105 | before ultimately calling OPENSSL_free(). |
106 | ||
91a61513 JW |
107 | OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. |
108 | Use OPENSSL_cleanse() with care if the memory is a mapping of a file. | |
1bc74519 RS |
109 | If the storage controller uses write compression, then its possible |
110 | that sensitive tail bytes will survive zeroization because the block of | |
6b4a77f5 | 111 | zeros will be compressed. If the storage controller uses wear leveling, |
1bc74519 | 112 | then the old sensitive data will not be overwritten; rather, a block of |
91a61513 JW |
113 | 0's will be written at a new physical location. |
114 | ||
bbd86bf5 RS |
115 | OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the |
116 | equivalent C functions, except that memory is allocated by calling the | |
9d22666e | 117 | OPENSSL_malloc() and should be released by calling OPENSSL_free(). |
bbd86bf5 RS |
118 | |
119 | OPENSSL_strlcpy(), | |
120 | OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C | |
121 | library functions and are provided for portability. | |
122 | ||
14f051a0 RS |
123 | OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a |
124 | pointer to the parsed value. The memory is allocated by calling | |
125 | OPENSSL_malloc() and should be released by calling OPENSSL_free(). | |
126 | If B<len> is not NULL, it is filled in with the output length. | |
127 | Colons between two-character hex "bytes" are ignored. | |
128 | An odd number of hex digits is an error. | |
129 | ||
130 | OPENSSL_buf2hexstr() takes the specified buffer and length, and returns | |
131 | a hex string for value, or NULL on error. | |
01238aec | 132 | B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned. |
14f051a0 RS |
133 | |
134 | OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent, | |
135 | or returns -1 on error. | |
136 | ||
bbd86bf5 | 137 | If no allocations have been done, it is possible to "swap out" the default |
fa9bb620 RL |
138 | implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free() |
139 | and replace them with alternate versions (hooks). | |
140 | CRYPTO_get_mem_functions() function fills in the given arguments with the | |
141 | function pointers for the current implementations. | |
142 | With CRYPTO_set_mem_functions(), you can specify a different set of functions. | |
bbd86bf5 RS |
143 | If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed. |
144 | ||
145 | The default implementation can include some debugging capability (if enabled | |
146 | at build-time). | |
147 | This adds some overhead by keeping a list of all memory allocations, and | |
148 | removes items from the list when they are free'd. | |
149 | This is most useful for identifying memory leaks. | |
00bb5504 RS |
150 | CRYPTO_set_mem_debug() turns this tracking on and off. In order to have |
151 | any effect, is must be called before any of the allocation functions | |
152 | (e.g., CRYPTO_malloc()) are called, and is therefore normally one of the | |
153 | first lines of main() in an application. | |
c2e27310 VD |
154 | CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking. |
155 | To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of | |
156 | the B<CRYPTO_MEM_CHECK_ON>. | |
157 | To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of | |
158 | the B<CRYPTO_MEM_CHECK_OFF>. | |
bbd86bf5 RS |
159 | |
160 | While checking memory, it can be useful to store additional context | |
161 | about what is being done. | |
162 | For example, identifying the field names when parsing a complicated | |
163 | data structure. | |
164 | OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push()) | |
165 | attachs an identifying string to the allocation stack. | |
166 | This must be a global or other static string; it is not copied. | |
167 | OPENSSL_mem_debug_pop() removes identifying state from the stack. | |
168 | ||
169 | At the end of the program, calling CRYPTO_mem_leaks() or | |
c2e27310 | 170 | CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it |
4e482ae6 DSH |
171 | to the specified BIO B<b> or FILE B<fp>. These functions return 1 if |
172 | there are no leaks, 0 if there are leaks and -1 if an error occurred. | |
bbd86bf5 | 173 | |
20626cfd RL |
174 | CRYPTO_mem_leaks_cb() does the same as CRYPTO_mem_leaks(), but instead |
175 | of writing to a given BIO, the callback function is called for each | |
176 | output string with the string, length, and userdata B<u> as the callback | |
177 | parameters. | |
178 | ||
0e598a3d RS |
179 | If the library is built with the C<crypto-mdebug> option, then one |
180 | function, CRYPTO_get_alloc_counts(), and two additional environment | |
181 | variables, B<OPENSSL_MALLOC_FAILURES> and B<OPENSSL_MALLOC_FD>, | |
182 | are available. | |
183 | ||
184 | The function CRYPTO_get_alloc_counts() fills in the number of times | |
185 | each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been | |
186 | called, into the values pointed to by B<mcount>, B<rcount>, and B<fcount>, | |
187 | respectively. If a pointer is NULL, then the corresponding count is not stored. | |
188 | ||
189 | The variable | |
190 | B<OPENSSL_MALLOC_FAILURES> controls how often allocations should fail. | |
191 | It is a set of fields separated by semicolons, which each field is a count | |
192 | (defaulting to zero) and an optional atsign and percentage (defaulting | |
193 | to 100). If the count is zero, then it lasts forever. For example, | |
194 | C<100;@25> or C<100@0;0@25> means the first 100 allocations pass, then all | |
195 | other allocations (until the program exits or crashes) have a 25% chance of | |
196 | failing. | |
197 | ||
198 | If the variable B<OPENSSL_MALLOC_FD> is parsed as a positive integer, then | |
199 | it is taken as an open file descriptor, and a record of all allocations is | |
200 | written to that descriptor. If an allocation will fail, and the platform | |
201 | supports it, then a backtrace will be written to the descriptor. This can | |
202 | be useful because a malloc may fail but not be checked, and problems will | |
203 | only occur later. The following example in classic shell syntax shows how | |
204 | to use this (will not work on all platforms): | |
205 | ||
206 | OPENSSL_MALLOC_FAILURES='200;@10' | |
207 | export OPENSSL_MALLOC_FAILURES | |
208 | OPENSSL_MALLOC_FD=3 | |
209 | export OPENSSL_MALLOC_FD | |
210 | ...app invocation... 3>/tmp/log$$ | |
211 | ||
212 | ||
bbd86bf5 RS |
213 | =head1 RETURN VALUES |
214 | ||
215 | OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() | |
4e482ae6 | 216 | CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() |
bbd86bf5 RS |
217 | return no value. |
218 | ||
4e482ae6 DSH |
219 | CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there |
220 | are no leaks, 0 if there are leaks and -1 if an error occurred. | |
221 | ||
bbd86bf5 RS |
222 | OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), |
223 | OPENSSL_clear_realloc(), | |
224 | CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), | |
225 | CRYPTO_clear_realloc(), | |
14f051a0 | 226 | OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(), |
bbd86bf5 RS |
227 | OPENSSL_strdup(), and OPENSSL_strndup() |
228 | return a pointer to allocated memory or NULL on error. | |
229 | ||
230 | CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug() | |
231 | return 1 on success or 0 on failure (almost | |
232 | always because allocations have already happened). | |
233 | ||
60250017 | 234 | CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the |
0a522854 | 235 | previous value of the mode. |
bbd86bf5 RS |
236 | |
237 | OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop() | |
238 | return 1 on success or 0 on failure. | |
239 | ||
fa9bb620 RL |
240 | =head1 NOTES |
241 | ||
242 | While it's permitted to swap out only a few and not all the functions | |
243 | with CRYPTO_set_mem_functions(), it's recommended to swap them all out | |
244 | at once. I<This applies specially if OpenSSL was built with the | |
245 | configuration option> C<crypto-mdebug> I<enabled. In case, swapping out | |
246 | only, say, the malloc() implementation is outright dangerous.> | |
247 | ||
e2f92610 RS |
248 | =head1 COPYRIGHT |
249 | ||
250 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
251 | ||
252 | Licensed under the OpenSSL license (the "License"). You may not use | |
253 | this file except in compliance with the License. You can obtain a copy | |
254 | in the file LICENSE in the source distribution or at | |
255 | L<https://www.openssl.org/source/license.html>. | |
256 | ||
257 | =cut |