From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod | 207 +++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod (limited to 'openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod') diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod new file mode 100644 index 0000000..2104f43 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +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_set_mem_debug, CRYPTO_mem_ctrl, +CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions + +=head1 SYNOPSIS + + #include + + int OPENSSL_malloc_init(void) + + 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); + + unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); + char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len); + int OPENSSL_hexchar2int(unsigned char c); + + 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) + + 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)) + + 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); + + void CRYPTO_mem_leaks(BIO *b); + void CRYPTO_mem_leaks_fp(FILE *fp); + +=head1 DESCRIPTION + +OpenSSL memory allocation is handled by the B API. These are +generally macro's that add the standard C B<__FILE__> and B<__LINE__> +parameters and call a lower-level B API. +Some functions do not add those parameters, but exist for consistency. + +OPENSSL_malloc_init() sets the lower-level memory allocation functions +to their default implementation. +It is generally not necessary to call this, except perhaps in certain +shared-library situations. + +OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the +C malloc(), realloc(), and free() functions. +OPENSSL_zalloc() calls memset() to zero the memory before returning. + +OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used +when the buffer at B holds sensitive information. +The old buffer is filled with zero's by calling OPENSSL_cleanse() +before ultimately calling OPENSSL_free(). + +OPENSSL_cleanse() fills B of size B with a string of 0's. +Use OPENSSL_cleanse() 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. + +OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the +equivalent C functions, except that memory is allocated by calling the +OPENSSL_malloc() and should be released by calling OPENSSL_free(). + +OPENSSL_strlcpy(), +OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C +library functions and are provided for portability. + +OPENSSL_hexstr2buf() parses B as a hex string and returns a +pointer to the parsed value. The memory is allocated by calling +OPENSSL_malloc() and should be released by calling OPENSSL_free(). +If B 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. + +OPENSSL_buf2hexstr() takes the specified buffer and length, and returns +a hex string for value, or NULL on error. +B cannot be NULL; if B is 0 an empty string is returned. + +OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent, +or returns -1 on error. + +If no allocations have been done, it is possible to "swap out" the default +implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free() +and replace them with alternate versions (hooks). +CRYPTO_get_mem_functions() function fills in the given arguments with the +function pointers for the current implementations. +With CRYPTO_set_mem_functions(), you can specify a different set of functions. +If any of B, B, or B are NULL, then the function is not changed. + +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. +CRYPTO_set_mem_debug() 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 main() in an application. + +CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking. +To enable tracking call CRYPTO_mem_ctrl() with a B argument of +the B. +To disable tracking call CRYPTO_mem_ctrl() with a B argument of +the B. + +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. +OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push()) +attachs an identifying string to the allocation stack. +This must be a global or other static string; it is not copied. +OPENSSL_mem_debug_pop() removes identifying state from the stack. + +At the end of the program, calling CRYPTO_mem_leaks() or +CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it +to the specified BIO B or FILE B. These functions return 1 if +there are no leaks, 0 if there are leaks and -1 if an error occurred. + +=head1 RETURN VALUES + +OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() +CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() +return no value. + +CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there +are no leaks, 0 if there are leaks and -1 if an error occurred. + +OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), +OPENSSL_clear_realloc(), +CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), +CRYPTO_clear_realloc(), +OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(), +OPENSSL_strdup(), and OPENSSL_strndup() +return a pointer to allocated memory or NULL on error. + +CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug() +return 1 on success or 0 on failure (almost +always because allocations have already happened). + +CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the +previous value of the mode. + +OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop() +return 1 on success or 0 on failure. + +=head1 NOTES + +While it's permitted to swap out only a few and not all the functions +with CRYPTO_set_mem_functions(), it's recommended to swap them all out +at once. I C I + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut -- cgit v1.2.3