doc/man3/OPENSSL_malloc.pod

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