diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OPENSSL_malloc.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OPENSSL_malloc.3 | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/OPENSSL_malloc.3 b/secure/lib/libcrypto/man/man3/OPENSSL_malloc.3 new file mode 100644 index 000000000000..b7961955bad4 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/OPENSSL_malloc.3 @@ -0,0 +1,314 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OPENSSL_MALLOC 3ossl" +.TH OPENSSL_MALLOC 3ossl 2025-09-16 3.5.3 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_malloc_init, +OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc, +OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, +CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, +OPENSSL_strdup, OPENSSL_strndup, +OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul, +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 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/crypto.h> +\& +\& int OPENSSL_malloc_init(void); +\& +\& void *OPENSSL_malloc(size_t num); +\& void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr); +\& 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); +\& int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num); +\& 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); +\& +\& void *CRYPTO_malloc(size_t num, const char *file, int line); +\& void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr, +\& 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); +\& +\& 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); +\& +\& void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount); +\& +\& env OPENSSL_MALLOC_FAILURES=... <application> +\& env OPENSSL_MALLOC_FD=... <application> +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 4 +\& 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); +\& +\& 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); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL memory allocation is handled by the \fBOPENSSL_xxx\fR API. These are +generally macro's that add the standard C \fB_\|_FILE_\|_\fR and \fB_\|_LINE_\|_\fR +parameters and call a lower-level \fBCRYPTO_xxx\fR API. +Some functions do not add those parameters, but exist for consistency. +.PP +\&\fBOPENSSL_malloc_init()\fR does nothing and does not need to be called. It is +included for compatibility with older versions of OpenSSL. +.PP +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR, and \fBOPENSSL_free()\fR are like the +C \fBmalloc()\fR, \fBrealloc()\fR, and \fBfree()\fR functions. +\&\fBOPENSSL_zalloc()\fR calls \fBmemset()\fR to zero the memory before returning. +.PP +\&\fBOPENSSL_aligned_alloc()\fR operates just as OPENSSL_malloc does, but it +allows for the caller to specify an alignment value, for instances in +which the default alignment of malloc is insufficient for the callers +needs. Note, the alignment value must be a power of 2, and the size +specified must be a multiple of the alignment. +NOTE: The call to \fBOPENSSL_aligned_alloc()\fR accepts a 3rd argument, \fIfreeptr\fR +which must point to a void pointer. On some platforms, there is no available +library call to obtain memory allocations greater than what malloc provides. In +this case, OPENSSL_aligned_alloc implements its own alignment routine, +allocating additional memory and offsetting the returned pointer to be on the +requested alignment boundary. In order to safely free allocations made by this +method, the caller must return the value in the \fIfreeptr\fR variable, rather than +the returned pointer. +.PP +\&\fBOPENSSL_clear_realloc()\fR and \fBOPENSSL_clear_free()\fR should be used +when the buffer at \fBaddr\fR holds sensitive information. +The old buffer is filled with zero's by calling \fBOPENSSL_cleanse()\fR +before ultimately calling \fBOPENSSL_free()\fR. If the argument to \fBOPENSSL_free()\fR is +NULL, nothing is done. +.PP +\&\fBOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0's. +Use \fBOPENSSL_cleanse()\fR with care if the memory is a mapping of a file. +If the storage controller uses write compression, then it's 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. +.PP +\&\fBOPENSSL_strdup()\fR, \fBOPENSSL_strndup()\fR and \fBOPENSSL_memdup()\fR are like the +equivalent C functions, except that memory is allocated by calling the +\&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR. +.PP +\&\fBOPENSSL_strlcpy()\fR, +\&\fBOPENSSL_strlcat()\fR and \fBOPENSSL_strnlen()\fR are equivalents of the common C +library functions and are provided for portability. +.PP +\&\fBOPENSSL_strtoul()\fR is a wrapper around the POSIX function strtoul, with the same +behaviors listed in the POSIX documentation, with the additional behavior that +it validates the input \fIstr\fR and \fInum\fR parameters for not being NULL, and confirms +that at least a single byte of input has been consumed in the translation, +returning an error in the event that no bytes were consumed. +.PP +If no allocations have been done, it is possible to "swap out" the default +implementations for \fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR and \fBOPENSSL_free()\fR +and replace them with alternate versions. +\&\fBCRYPTO_get_mem_functions()\fR function fills in the given arguments with the +function pointers for the current implementations. +With \fBCRYPTO_set_mem_functions()\fR, you can specify a different set of functions. +If any of \fBmalloc_fn\fR, \fBrealloc_fn\fR, or \fBfree_fn\fR are NULL, then +the function is not changed. +While it's permitted to swap out only a few and not all the functions +with \fBCRYPTO_set_mem_functions()\fR, it's recommended to swap them all out +at once. +.PP +If the library is built with the \f(CW\*(C`crypto\-mdebug\*(C'\fR option, then one +function, \fBCRYPTO_get_alloc_counts()\fR, and two additional environment +variables, \fBOPENSSL_MALLOC_FAILURES\fR and \fBOPENSSL_MALLOC_FD\fR, +are available. +.PP +The function \fBCRYPTO_get_alloc_counts()\fR fills in the number of times +each of \fBCRYPTO_malloc()\fR, \fBCRYPTO_realloc()\fR, and \fBCRYPTO_free()\fR have been +called, into the values pointed to by \fBmcount\fR, \fBrcount\fR, and \fBfcount\fR, +respectively. If a pointer is NULL, then the corresponding count is not stored. +.PP +The variable +\&\fBOPENSSL_MALLOC_FAILURES\fR 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, +\&\f(CW\*(C`100;@25\*(C'\fR or \f(CW\*(C`100@0;0@25\*(C'\fR means the first 100 allocations pass, then all +other allocations (until the program exits or crashes) have a 25% chance of +failing. The length of the value of \fBOPENSSL_MALLOC_FAILURES\fR must be 256 or +fewer characters. +.PP +If the variable \fBOPENSSL_MALLOC_FD\fR is parsed as a positive integer, then +it is taken as an open file descriptor. This is used in conjunction with +\&\fBOPENSSL_MALLOC_FAILURES\fR described above. For every allocation it will log +details about how many allocations there have been so far, what percentage +chance there is for this allocation failing, and whether it has actually failed. +The following example in classic shell syntax shows how to use this (will not +work on all platforms): +.PP +.Vb 5 +\& OPENSSL_MALLOC_FAILURES=\*(Aq200;@10\*(Aq +\& export OPENSSL_MALLOC_FAILURES +\& OPENSSL_MALLOC_FD=3 +\& export OPENSSL_MALLOC_FD +\& ...app invocation... 3>/tmp/log$$ +.Ve +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBOPENSSL_malloc_init()\fR, \fBOPENSSL_free()\fR, \fBOPENSSL_clear_free()\fR +\&\fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR and \fBCRYPTO_get_mem_functions()\fR +return no value. +.PP +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_aligned_alloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_realloc()\fR, +\&\fBOPENSSL_clear_realloc()\fR, +\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_realloc()\fR, +\&\fBCRYPTO_clear_realloc()\fR, +\&\fBOPENSSL_strdup()\fR, and \fBOPENSSL_strndup()\fR +return a pointer to allocated memory or NULL on error. +.PP +\&\fBCRYPTO_set_mem_functions()\fR returns 1 on success or 0 on failure (almost +always because allocations have already happened). +.PP +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, \fBCRYPTO_mem_leaks_cb()\fR, +\&\fBCRYPTO_set_mem_debug()\fR, and \fBCRYPTO_mem_ctrl()\fR are deprecated and are no-ops that +always return \-1. +\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_debug_push()\fR, and \fBCRYPTO_mem_debug_pop()\fR +are deprecated and are no-ops that always return 0. +.PP +\&\fBOPENSSL_strtoul()\fR returns 1 on success and 0 in the event that an error has +occurred. Specifically, 0 is returned in the following events: +.IP \(bu 4 +If the underlying call to strtoul returned a non zero errno value +.IP \(bu 4 +If the translation did not consume the entire input string, and the passed +endptr value was NULL +.IP \(bu 4 +If no characters were consumed in the translation +.PP +Note that a success condition does not imply that the expected +translation has been performed. For instance calling +.PP +.Vb 1 +\& OPENSSL_strtoul("0x12345", &endptr, 10, &num); +.Ve +.PP +will result in a successful translation with num having the value 0, and +*endptr = 'x'. Be sure to validate how much data was consumed when calling this +function. +.SH HISTORY +.IX Header "HISTORY" +\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_pop()\fR, +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, +\&\fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_set_mem_debug()\fR, \fBCRYPTO_mem_ctrl()\fR +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. +\&\fBOPENSSL_aligned_alloc()\fR, \fBCRYPTO_aligned_alloc()\fR, \fBOPENSSL_strtoul()\fR were +added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |