2 files changed, 187 insertions, 3 deletions
diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
new file mode 100644
index 0000000000..bf7c3ab9ed
--- /dev/null
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -0,0 +1,162 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_malloc_init,
+OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
+OPENSSL_clear_realloc, OPENSSL_clear_free,
+CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
+OPENSSL_strdup, OPENSSL_strndup,
+OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
+CRYPTO_clear_realloc, CRYPTO_clear_free,
+CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
+CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
+OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
+CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
+CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ 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)
+ 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_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)
+ 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)
+
+ void CRYPTO_get_mem_functions(
+         void *(**m)(size_t, const char *, int),
+         void *(**r)(void *, size_t, const char *, int),
+         void (**f)(void *))
+ int CRYPTO_set_mem_functions(
+         void *(*m)(size_t, const char *, int),
+         void *(*r)(void *, size_t, const char *, int),
+         void (*f)(void *))
+
+ int CRYPTO_set_mem_debug(int onoff)
+
+ #define CRYPTO_MEM_CHECK_OFF
+ #define CRYPTO_MEM_CHECK_ON
+ #define CRYPTO_MEM_CHECK_DISABLE
+ #define CRYPTO_MEM_CHECK_ENABLE
+
+ int CRYPTO_mem_ctrl(int flags);
+
+ int OPENSSL_mem_debug_push(const char *info)
+ int OPENSLS_mem_debug_pop)(void)
+
+ int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
+
+ void CRYPTO_mem_leaks(BIO *b);
+ void CRYPTO_mem_leaks(FILE *fp);
+
+=head1 DESCRIPTION
+
+OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are
+generally macro's that add the standard C B<__FILE__> and B<__LINE__>
+parameters and call a lower-level B<CRYPTO_xxx> 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<addr> holds sensitive information.
+The old buffer is filled with arbitrary data by calling OPENSSL_cleanse()
+before ultimately calling OPENSSL_free().
+
+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 releaed by calling OPENSSL_free().
+
+OPENSSL_strlcpy(),
+OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
+library functions and are provided for portability.
+
+If no allocations have been done, it is possible to "swap out" the default
+implementations and replace them with alternate versions, or wrappers that
+do some additional housekeeping and then defer to the OpenSSL implementation.
+The CRYPTO_get_mem_functions() function fills in the function pointers for
+with the current functions (normally, and by default,
+CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free()).
+The CRYPTO_set_mem_functions() specifies a different set of functions.
+If any of B<m>, B<r>, or B<f> 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.  It is normally
+called at startup, but can be called at any time.
+
+Finer-grain control of the tracking can be done with CRYPTO_mem_ctrl().
+The most common case is to enable tracking, which is done by using
+the B<CRYPTO_MEM_CHECK_ON> constant; it can be turned off by using
+the B<CRYPTO_MEM_CHECK_OFF> value.  The disable and enable values are
+most commonly used within OpenSSL to termporarily suspend and restore
+tracking of library internals.
+
+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<b>
+or FILE B<fp>.
+Depending on how OpenSSL is built, it may then abort if there
+are any unfree'd allocations, for debugging.
+
+=head1 RETURN VALUES
+
+OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
+CRYPTO_free(), CRYPTO_clear_free(),
+CRYPTO_get_mem_functions(), and
+CRYPTO_mem_leaks()
+return no value.
+
+OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
+OPENSSL_clear_realloc(),
+CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
+CRYPTO_clear_realloc(),
+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() return the previous value of the flag.
+
+OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
+return 1 on success or 0 on failure.
+
+=cut
diff --git a/doc/crypto/OPENSSL_secure_malloc.pod b/doc/crypto/OPENSSL_secure_malloc.pod
index 588c4b15f9..5e221e90b4 100644
--- a/doc/crypto/OPENSSL_secure_malloc.pod
+++ b/doc/crypto/OPENSSL_secure_malloc.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, OPENSSL_secure_free, OPENSSL_secure_allocated - use secure heap storage
+CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc,
+OPENSSL_secure_free, OPENSSL_secure_allocated - secure heap storage
 
 =head1 SYNOPSIS
 
@@ -15,10 +16,15 @@ CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, OPE
  void CRYPTO_secure_malloc_done();
 
  void *OPENSSL_secure_malloc(int num);
+ void *CRYPTO_secure_malloc(int num, const char *file, int line);
 
  void OPENSSL_secure_free(void* ptr);
+ void CRYPTO_secure_free(void *ptr);
 
- int OPENSSL_secure_allocated(const void* ptr);
+ size_t OPENSSL_secure_actual_size(const void *ptr);
+ int OPENSSL_secure_allocated(const void *ptr);
+
+ size_t CYRPTO_secure_malloc_used();
 
 =head1 DESCRIPTION
 
@@ -49,15 +55,25 @@ to the process. It can take noticeably long to complete.
 B<OPENSSL_secure_malloc> allocates C<num> bytes from the heap.
 If B<CRYPTO_secure_malloc_init> is not called, this is equivalent to
 calling B<OPENSSL_malloc>.
+It is a macro that expands to
+B<CRYPTO_secure_malloc> and adds the B<__FILE__> and B<__LINE__> parameters.
 
 B<OPENSSL_secure_free> releases the memory at C<ptr> back to the heap.
 It must be called with a value previously obtained from
 B<OPENSSL_secure_malloc>.
 If B<CRYPTO_secure_malloc_init> is not called, this is equivalent to
 calling B<OPENSSL_free>.
+It exists for consistency with B<OPENSSL_secure_malloc> , and
+is a macro that expands to B<CRYPTO_secure_free>.
 
 B<OPENSSL_secure_allocated> tells whether or not a pointer is within
 the secure heap.
+B<OPENSSL_secure_actual_size> tells the actual size allocated to the
+pointer; implementations may allocate more space than initially
+requested, in order to "round up" and reduce secure heap fragmentation.
+
+B<CRYPTO_secure_malloc_used> returns the number of bytes allocated in the
+secure heap.
 
 =head1 RETURN VALUES
 
@@ -78,9 +94,15 @@ the secure heap, or 0 if not.
 B<CRYPTO_secure_malloc_done> and B<OPENSSL_secure_free>
 return no values.
 
+=head1 BUGS
+
+The size parameters should be B<size_t> not B<int> and will be changed
+in a future release.
+
 =head1 SEE ALSO
 
+L<OPENSSL_malloc(3)>,
 L<BN_new(3)>,
-L<bn_internal(3)>
+L<bn_internal(3)>.
 
 =cut