227 lines
11 KiB
HTML
Executable File
227 lines
11 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="#history">HISTORY</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,
|
|
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_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn,
|
|
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>
|
|
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>
|
|
typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);
|
|
typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,
|
|
int line);
|
|
typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);
|
|
void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,
|
|
CRYPTO_realloc_fn *realloc_fn,
|
|
CRYPTO_free_fn *free_fn);
|
|
int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,
|
|
CRYPTO_realloc_fn realloc_fn,
|
|
CRYPTO_free_fn free_fn);</pre>
|
|
<pre>
|
|
void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);</pre>
|
|
<pre>
|
|
env OPENSSL_MALLOC_FAILURES=... <application>
|
|
env OPENSSL_MALLOC_FD=... <application></pre>
|
|
<p>Deprecated:</p>
|
|
<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>
|
|
<pre>
|
|
int CRYPTO_set_mem_debug(int onoff)
|
|
int CRYPTO_mem_ctrl(int mode);
|
|
int OPENSSL_mem_debug_push(const char *info)
|
|
int OPENSSL_mem_debug_pop(void);
|
|
int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
|
|
int CRYPTO_mem_debug_pop(void);</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>If no allocations have been done, it is possible to "swap out" the default
|
|
implementations for <code>OPENSSL_malloc()</code>, <code>OPENSSL_realloc()</code> and <code>OPENSSL_free()</code>
|
|
and replace them with alternate versions.
|
|
<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>malloc_fn</strong>, <strong>realloc_fn</strong>, or <strong>free_fn</strong> are NULL, then
|
|
the function is not changed.
|
|
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.</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>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>,
|
|
<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> returns 1 on success or 0 on failure (almost
|
|
always because allocations have already happened).</p>
|
|
<p><code>CRYPTO_mem_leaks()</code>, <code>CRYPTO_mem_leaks_fp()</code>, <code>CRYPTO_mem_leaks_cb()</code>,
|
|
<code>CRYPTO_set_mem_debug()</code>, and <code>CRYPTO_mem_ctrl()</code> are deprecated and return -1.
|
|
<code>OPENSSL_mem_debug_push()</code>, <code>OPENSSL_mem_debug_pop()</code>,
|
|
<code>CRYPTO_mem_debug_push()</code>, and <code>CRYPTO_mem_debug_pop()</code>
|
|
are deprecated and return 0.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p><code>OPENSSL_mem_debug_push()</code>, <code>OPENSSL_mem_debug_pop()</code>,
|
|
<code>CRYPTO_mem_debug_push()</code>, <code>CRYPTO_mem_debug_pop()</code>,
|
|
<code>CRYPTO_mem_leaks()</code>, <code>CRYPTO_mem_leaks_fp()</code>,
|
|
<code>CRYPTO_mem_leaks_cb()</code>, <code>CRYPTO_set_mem_debug()</code>, <code>CRYPTO_mem_ctrl()</code>
|
|
were deprecated in OpenSSL 3.0.
|
|
The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of
|
|
clang's memory and leak sanitizer.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (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>
|