sec_mem: add note about the minimum size parameter.

[openssl.git] / doc / man3 / OPENSSL_secure_malloc.pod

diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod
index 0d831296352cb39d3d0f6af75fa41359d25a662d..67a34eb809d095ade4c295d77ebc8f897fd2acb9 100644 (file)
--- a/doc/man3/OPENSSL_secure_malloc.pod
+++ b/doc/man3/OPENSSL_secure_malloc.pod
@@ -5,14 +5,16 @@
 CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized,
 CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc,
 OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free,
-CRYPTO_secure_free, OPENSSL_secure_actual_size, OPENSSL_secure_allocated,
-CYRPTO_secure_used - secure heap storage
+CRYPTO_secure_free, OPENSSL_secure_clear_free,
+CRYPTO_secure_clear_free, OPENSSL_secure_actual_size,
+CRYPTO_secure_allocated,
+CRYPTO_secure_used - secure heap storage
 
 =head1 SYNOPSIS
 
  #include <openssl/crypto.h>
 
- int CRYPTO_secure_malloc_init(size_t size, int minsize);
+ int CRYPTO_secure_malloc_init(size_t size, size_t minsize);
 
  int CRYPTO_secure_malloc_initialized();
 
@@ -27,10 +29,13 @@ CYRPTO_secure_used - secure heap storage
  void OPENSSL_secure_free(void* ptr);
  void CRYPTO_secure_free(void *ptr, const char *, int);
 
+ void OPENSSL_secure_clear_free(void* ptr, size_t num);
+ void CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int);
+
  size_t OPENSSL_secure_actual_size(const void *ptr);
- int OPENSSL_secure_allocated(const void *ptr);
 
- size_t CYRPTO_secure_used();
+ int CRYPTO_secure_allocated(const void *ptr);
+ size_t CRYPTO_secure_used();
 
 =head1 DESCRIPTION
 
@@ -48,8 +53,10 @@ put all intermediate values and computations there.
 
 CRYPTO_secure_malloc_init() creates the secure heap, with the specified
 C<size> in bytes. The C<minsize> parameter is the minimum size to
-allocate from the heap. Both C<size> and C<minsize> must be a power
-of two.
+allocate from the heap or zero to use a reasonable default value.
+Both C<size> and, if specified, C<minsize> must be a power of two and
+C<minsize> should generally be small, for example 16 or 32.
+C<minsize> must be less than a quarter of C<size> in any case.
 
 CRYPTO_secure_malloc_initialized() indicates whether or not the secure
 heap as been initialized and is available.
@@ -77,12 +84,18 @@ It exists for consistency with OPENSSL_secure_malloc() , and
 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_clear_free() is similar to OPENSSL_secure_free() except
+that it has an additional C<num> parameter which is used to clear
+the memory if it was not allocated from the secure heap.
+If CRYPTO_secure_malloc_init() is not called, this is equivalent to
+calling OPENSSL_clear_free().
+
 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.
 
+OPENSSL_secure_allocated() tells if a pointer is allocated in the secure heap.
+
 CRYPTO_secure_used() returns the number of bytes allocated in the
 secure heap.
 
@@ -104,18 +117,25 @@ CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 i
 
 CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not.
 
-OPENSSL_secure_free() returns no values.
+OPENSSL_secure_free() and OPENSSL_secure_clear_free() return no values.
 
 =head1 SEE ALSO
 
 L<OPENSSL_malloc(3)>,
 L<BN_new(3)>
 
+=head1 HISTORY
+
+The OPENSSL_secure_clear_free() function was added in OpenSSL 1.1.0g.
+
+The second argument to CRYPTO_secure_malloc_init() was changed from an B<int> to
+a B<size_t> in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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
 L<https://www.openssl.org/source/license.html>.