Update the documentation on heap allocators / deallocators

Reviewed-by: Rich Salz <rsalz@openssl.org>

diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
index 9dfeb390bfca1bbb23d1b9995283c2f149c517c5..04fa0b718c76ba674e25f8c79e180a6896cdb52d 100644 (file)
--- a/doc/crypto/OPENSSL_malloc.pod
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -34,20 +34,20 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
  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_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)
+ 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)
  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_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 CRYPTO_get_mem_functions(
          void *(**m)(size_t, const char *, int),
          void *(**r)(void *, size_t, const char *, int),

-         void (**f)(void *))
+         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),
  int CRYPTO_set_mem_functions(
          void *(*m)(size_t, const char *, int),
          void *(*r)(void *, size_t, const char *, int),

-         void (*f)(void *))
+         void (*f)(void *, const char *, int))

 
  int CRYPTO_set_mem_debug(int onoff)
 
 
  int CRYPTO_set_mem_debug(int onoff)
 


@@ -96,12 +96,11 @@ 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
 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.
+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<m>, B<r>, or B<f> are NULL, then the function is not changed.
 
 The default implementation can include some debugging capability (if enabled
 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


@@ -160,4 +159,12 @@ CRYPTO_mem_ctrl() returns the previous value of the mode.
 OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
 return 1 on success or 0 on failure.
 
 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<This applies specially if OpenSSL was built with the
+configuration option> C<crypto-mdebug> I<enabled.  In case, swapping out
+only, say, the malloc() implementation is outright dangerous.>
+

 =cut
 =cut

diff --git a/doc/crypto/OPENSSL_secure_malloc.pod b/doc/crypto/OPENSSL_secure_malloc.pod
index a055f1dc952d29dd5c4b13d506e2b57e25b49123..3423eb0413080f8ad82cd459828b28a883cb6319 100644 (file)
--- a/doc/crypto/OPENSSL_secure_malloc.pod
+++ b/doc/crypto/OPENSSL_secure_malloc.pod
@@ -25,7 +25,7 @@ CYRPTO_secure_malloc_used - secure heap storage
  void *CRYPTO_secure_zalloc(int num, const char *file, int line);
 
  void OPENSSL_secure_free(void* ptr);
  void *CRYPTO_secure_zalloc(int num, const char *file, int line);
 
  void OPENSSL_secure_free(void* ptr);

- void CRYPTO_secure_free(void *ptr);
+ void CRYPTO_secure_free(void *ptr, const char *, int);

 
  size_t OPENSSL_secure_actual_size(const 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);


@@ -74,7 +74,8 @@ OPENSSL_secure_malloc().
 If CRYPTO_secure_malloc_init() is not called, this is equivalent to
 calling OPENSSL_free().
 It exists for consistency with OPENSSL_secure_malloc() , and
 If CRYPTO_secure_malloc_init() is not called, this is equivalent to
 calling OPENSSL_free().
 It exists for consistency with OPENSSL_secure_malloc() , and

-is a macro that expands to CRYPTO_secure_free().
+is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__>
+and C<__LINE__> parameters..

 
 OPENSSL_secure_allocated() tells whether or not a pointer is within
 the secure heap.
 
 OPENSSL_secure_allocated() tells whether or not a pointer is within
 the secure heap.