269 lines
13 KiB
HTML
Executable File
269 lines
13 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>OPENSSL_malloc</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>OPENSSL_malloc_init,
|
|
OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
|
|
OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
|
|
CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
|
|
OPENSSL_strdup, OPENSSL_strndup,
|
|
OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
|
|
OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int,
|
|
CRYPTO_strdup, CRYPTO_strndup,
|
|
OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
|
|
CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
|
|
CRYPTO_clear_realloc, CRYPTO_clear_free,
|
|
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
|
|
- Memory allocation functions</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/crypto.h></pre>
|
|
<pre>
|
|
int OPENSSL_malloc_init(void)</pre>
|
|
<pre>
|
|
void *OPENSSL_malloc(size_t num)
|
|
void *OPENSSL_zalloc(size_t num)
|
|
void *OPENSSL_realloc(void *addr, size_t num)
|
|
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);
|
|
void *OPENSSL_memdup(void *data, size_t s)
|
|
void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num)
|
|
void OPENSSL_clear_free(void *str, size_t num)
|
|
void OPENSSL_cleanse(void *ptr, size_t len);</pre>
|
|
<pre>
|
|
unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
|
|
char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len);
|
|
int OPENSSL_hexchar2int(unsigned char c);</pre>
|
|
<pre>
|
|
void *CRYPTO_malloc(size_t num, 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_free(void *str, const char *, int)
|
|
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_clear_realloc(void *p, size_t old_len, size_t num,
|
|
const char *file, int line)
|
|
void CRYPTO_clear_free(void *str, size_t num, const char *, int)</pre>
|
|
<pre>
|
|
void CRYPTO_get_mem_functions(
|
|
void *(**m)(size_t, const char *, int),
|
|
void *(**r)(void *, size_t, const char *, int),
|
|
void (**f)(void *, const char *, int))
|
|
int CRYPTO_set_mem_functions(
|
|
void *(*m)(size_t, const char *, int),
|
|
void *(*r)(void *, size_t, const char *, int),
|
|
void (*f)(void *, const char *, int))</pre>
|
|
<pre>
|
|
void CRYPTO_get_alloc_counts(int *m, int *r, int *f)</pre>
|
|
<pre>
|
|
int CRYPTO_set_mem_debug(int onoff)</pre>
|
|
<pre>
|
|
env OPENSSL_MALLOC_FAILURES=... <application>
|
|
env OPENSSL_MALLOC_FD=... <application></pre>
|
|
<pre>
|
|
int CRYPTO_mem_ctrl(int mode);</pre>
|
|
<pre>
|
|
int OPENSSL_mem_debug_push(const char *info)
|
|
int OPENSSL_mem_debug_pop(void);</pre>
|
|
<pre>
|
|
int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
|
|
int CRYPTO_mem_debug_pop(void);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>OpenSSL memory allocation is handled by the <strong>OPENSSL_xxx</strong> API. These are
|
|
generally macro's that add the standard C <strong>__FILE__</strong> and <strong>__LINE__</strong>
|
|
parameters and call a lower-level <strong>CRYPTO_xxx</strong> API.
|
|
Some functions do not add those parameters, but exist for consistency.</p>
|
|
<p><code>OPENSSL_malloc_init()</code> does nothing and does not need to be called. It is
|
|
included for compatibility with older versions of OpenSSL.</p>
|
|
<p><code>OPENSSL_malloc()</code>, <code>OPENSSL_realloc()</code>, and <code>OPENSSL_free()</code> are like the
|
|
C <code>malloc()</code>, <code>realloc()</code>, and <code>free()</code> functions.
|
|
<code>OPENSSL_zalloc()</code> calls <code>memset()</code> to zero the memory before returning.</p>
|
|
<p><code>OPENSSL_clear_realloc()</code> and <code>OPENSSL_clear_free()</code> should be used
|
|
when the buffer at <strong>addr</strong> holds sensitive information.
|
|
The old buffer is filled with zero's by calling <code>OPENSSL_cleanse()</code>
|
|
before ultimately calling <code>OPENSSL_free()</code>.</p>
|
|
<p><code>OPENSSL_cleanse()</code> fills <strong>ptr</strong> of size <strong>len</strong> with a string of 0's.
|
|
Use <code>OPENSSL_cleanse()</code> with care if the memory is a mapping of a file.
|
|
If the storage controller uses write compression, then its 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.</p>
|
|
<p><code>OPENSSL_strdup()</code>, <code>OPENSSL_strndup()</code> and <code>OPENSSL_memdup()</code> are like the
|
|
equivalent C functions, except that memory is allocated by calling the
|
|
<code>OPENSSL_malloc()</code> and should be released by calling <code>OPENSSL_free()</code>.</p>
|
|
<p><code>OPENSSL_strlcpy()</code>,
|
|
<code>OPENSSL_strlcat()</code> and <code>OPENSSL_strnlen()</code> are equivalents of the common C
|
|
library functions and are provided for portability.</p>
|
|
<p>OPENSSL_hexstr2buf() parses <strong>str</strong> as a hex string and returns a
|
|
pointer to the parsed value. The memory is allocated by calling
|
|
<code>OPENSSL_malloc()</code> and should be released by calling <code>OPENSSL_free()</code>.
|
|
If <strong>len</strong> is not NULL, it is filled in with the output length.
|
|
Colons between two-character hex "bytes" are ignored.
|
|
An odd number of hex digits is an error.</p>
|
|
<p>OPENSSL_buf2hexstr() takes the specified buffer and length, and returns
|
|
a hex string for value, or NULL on error.
|
|
<strong>Buffer</strong> cannot be NULL; if <strong>len</strong> is 0 an empty string is returned.</p>
|
|
<p>OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent,
|
|
or returns -1 on error.</p>
|
|
<p>If no allocations have been done, it is possible to "swap out" the default
|
|
implementations for <code>OPENSSL_malloc()</code>, OPENSSL_realloc and <code>OPENSSL_free()</code>
|
|
and replace them with alternate versions (hooks).
|
|
<code>CRYPTO_get_mem_functions()</code> function fills in the given arguments with the
|
|
function pointers for the current implementations.
|
|
With <code>CRYPTO_set_mem_functions()</code>, you can specify a different set of functions.
|
|
If any of <strong>m</strong>, <strong>r</strong>, or <strong>f</strong> are NULL, then the function is not changed.</p>
|
|
<p>The default implementation can include some debugging capability (if enabled
|
|
at build-time).
|
|
This adds some overhead by keeping a list of all memory allocations, and
|
|
removes items from the list when they are free'd.
|
|
This is most useful for identifying memory leaks.
|
|
<code>CRYPTO_set_mem_debug()</code> turns this tracking on and off. In order to have
|
|
any effect, is must be called before any of the allocation functions
|
|
(e.g., CRYPTO_malloc()) are called, and is therefore normally one of the
|
|
first lines of <code>main()</code> in an application.
|
|
<code>CRYPTO_mem_ctrl()</code> provides fine-grained control of memory leak tracking.
|
|
To enable tracking call <code>CRYPTO_mem_ctrl()</code> with a <strong>mode</strong> argument of
|
|
the <strong>CRYPTO_MEM_CHECK_ON</strong>.
|
|
To disable tracking call <code>CRYPTO_mem_ctrl()</code> with a <strong>mode</strong> argument of
|
|
the <strong>CRYPTO_MEM_CHECK_OFF</strong>.</p>
|
|
<p>While checking memory, it can be useful to store additional context
|
|
about what is being done.
|
|
For example, identifying the field names when parsing a complicated
|
|
data structure.
|
|
<code>OPENSSL_mem_debug_push()</code> (which calls CRYPTO_mem_debug_push())
|
|
attaches an identifying string to the allocation stack.
|
|
This must be a global or other static string; it is not copied.
|
|
<code>OPENSSL_mem_debug_pop()</code> removes identifying state from the stack.</p>
|
|
<p>At the end of the program, calling <code>CRYPTO_mem_leaks()</code> or
|
|
<code>CRYPTO_mem_leaks_fp()</code> will report all "leaked" memory, writing it
|
|
to the specified BIO <strong>b</strong> or FILE <strong>fp</strong>. These functions return 1 if
|
|
there are no leaks, 0 if there are leaks and -1 if an error occurred.</p>
|
|
<p><code>CRYPTO_mem_leaks_cb()</code> does the same as <code>CRYPTO_mem_leaks()</code>, but instead
|
|
of writing to a given BIO, the callback function is called for each
|
|
output string with the string, length, and userdata <strong>u</strong> as the callback
|
|
parameters.</p>
|
|
<p>If the library is built with the <code>crypto-mdebug</code> option, then one
|
|
function, <code>CRYPTO_get_alloc_counts()</code>, and two additional environment
|
|
variables, <strong>OPENSSL_MALLOC_FAILURES</strong> and <strong>OPENSSL_MALLOC_FD</strong>,
|
|
are available.</p>
|
|
<p>The function <code>CRYPTO_get_alloc_counts()</code> fills in the number of times
|
|
each of <code>CRYPTO_malloc()</code>, <code>CRYPTO_realloc()</code>, and <code>CRYPTO_free()</code> have been
|
|
called, into the values pointed to by <strong>mcount</strong>, <strong>rcount</strong>, and <strong>fcount</strong>,
|
|
respectively. If a pointer is NULL, then the corresponding count is not stored.</p>
|
|
<p>The variable
|
|
<strong>OPENSSL_MALLOC_FAILURES</strong> controls how often allocations should fail.
|
|
It is a set of fields separated by semicolons, which each field is a count
|
|
(defaulting to zero) and an optional atsign and percentage (defaulting
|
|
to 100). If the count is zero, then it lasts forever. For example,
|
|
<code>100;@25</code> or <code>100@0;0@25</code> means the first 100 allocations pass, then all
|
|
other allocations (until the program exits or crashes) have a 25% chance of
|
|
failing.</p>
|
|
<p>If the variable <strong>OPENSSL_MALLOC_FD</strong> is parsed as a positive integer, then
|
|
it is taken as an open file descriptor, and a record of all allocations is
|
|
written to that descriptor. If an allocation will fail, and the platform
|
|
supports it, then a backtrace will be written to the descriptor. This can
|
|
be useful because a malloc may fail but not be checked, and problems will
|
|
only occur later. The following example in classic shell syntax shows how
|
|
to use this (will not work on all platforms):</p>
|
|
<pre>
|
|
OPENSSL_MALLOC_FAILURES='200;@10'
|
|
export OPENSSL_MALLOC_FAILURES
|
|
OPENSSL_MALLOC_FD=3
|
|
export OPENSSL_MALLOC_FD
|
|
...app invocation... 3>/tmp/log$$</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>OPENSSL_malloc_init()</code>, <code>OPENSSL_free()</code>, <code>OPENSSL_clear_free()</code>
|
|
<code>CRYPTO_free()</code>, <code>CRYPTO_clear_free()</code> and <code>CRYPTO_get_mem_functions()</code>
|
|
return no value.</p>
|
|
<p><code>CRYPTO_mem_leaks()</code>, <code>CRYPTO_mem_leaks_fp()</code> and <code>CRYPTO_mem_leaks_cb()</code> return 1 if
|
|
there are no leaks, 0 if there are leaks and -1 if an error occurred.</p>
|
|
<p><code>OPENSSL_malloc()</code>, <code>OPENSSL_zalloc()</code>, <code>OPENSSL_realloc()</code>,
|
|
<code>OPENSSL_clear_realloc()</code>,
|
|
<code>CRYPTO_malloc()</code>, <code>CRYPTO_zalloc()</code>, <code>CRYPTO_realloc()</code>,
|
|
<code>CRYPTO_clear_realloc()</code>,
|
|
OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(),
|
|
<code>OPENSSL_strdup()</code>, and <code>OPENSSL_strndup()</code>
|
|
return a pointer to allocated memory or NULL on error.</p>
|
|
<p><code>CRYPTO_set_mem_functions()</code> and <code>CRYPTO_set_mem_debug()</code>
|
|
return 1 on success or 0 on failure (almost
|
|
always because allocations have already happened).</p>
|
|
<p><code>CRYPTO_mem_ctrl()</code> returns -1 if an error occurred, otherwise the
|
|
previous value of the mode.</p>
|
|
<p><code>OPENSSL_mem_debug_push()</code> and <code>OPENSSL_mem_debug_pop()</code>
|
|
return 1 on success or 0 on failure.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>While it's permitted to swap out only a few and not all the functions
|
|
with <code>CRYPTO_set_mem_functions()</code>, it's recommended to swap them all out
|
|
at once. <em>This applies specially if OpenSSL was built with the
|
|
configuration option</em> <code>crypto-mdebug</code> <em>enabled. In case, swapping out
|
|
only, say, the malloc() implementation is outright dangerous.</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the OpenSSL license (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
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|