diff options
author | Rich Salz <rsalz@openssl.org> | 2016-01-27 23:16:47 -0500 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-01-27 23:34:13 -0500 |
commit | 3538c7da3d53dca70be5f507376299843046d2b7 (patch) | |
tree | e2bc925373cc5891b349041b101a021a8a32b084 /doc/crypto/OPENSSL_secure_malloc.pod | |
parent | 109f8b5dec6aa3f46c1df79c8d5f8e8aba10474b (diff) |
Add CRYPTO_secure_zalloc
Also turn B<foo> into foo() in the pod page.
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Diffstat (limited to 'doc/crypto/OPENSSL_secure_malloc.pod')
-rw-r--r-- | doc/crypto/OPENSSL_secure_malloc.pod | 65 |
1 files changed, 38 insertions, 27 deletions
diff --git a/doc/crypto/OPENSSL_secure_malloc.pod b/doc/crypto/OPENSSL_secure_malloc.pod index 5e221e90b4..a055f1dc95 100644 --- a/doc/crypto/OPENSSL_secure_malloc.pod +++ b/doc/crypto/OPENSSL_secure_malloc.pod @@ -2,8 +2,11 @@ =head1 NAME -CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, -OPENSSL_secure_free, OPENSSL_secure_allocated - secure heap storage +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_malloc_used - secure heap storage =head1 SYNOPSIS @@ -18,6 +21,9 @@ OPENSSL_secure_free, OPENSSL_secure_allocated - secure heap storage void *OPENSSL_secure_malloc(int num); void *CRYPTO_secure_malloc(int num, const char *file, int line); + void *OPENSSL_secure_zalloc(int num); + void *CRYPTO_secure_zalloc(int num, const char *file, int line); + void OPENSSL_secure_free(void* ptr); void CRYPTO_secure_free(void *ptr); @@ -40,58 +46,63 @@ If a secure heap is used, then private key B<BIGNUM> values are stored there. This protects long-term storage of private keys, but will not necessarily put all intermediate values and computations there. -B<CRYPTO_secure_malloc_init> creates the secure heap, with the specified +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. It is an error to call this after any B<OPENSSL_secure_malloc> +of two. It is an error to call this after any OPENSSL_secure_malloc() calls have been made. -B<CRYPTO_secure_malloc_initialized> indicates whether or not the secure +CRYPTO_secure_malloc_initialized() indicates whether or not the secure heap as been initialized and is available. -B<CRYPTO_secure_malloc_done> releases the heap and makes the memory unavailable +CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable 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>. +OPENSSL_secure_malloc() allocates C<num> bytes from the heap. +If CRYPTO_secure_malloc_init() is not called, this is equivalent to +calling OPENSSL_malloc(). It is a macro that expands to -B<CRYPTO_secure_malloc> and adds the B<__FILE__> and B<__LINE__> parameters. +CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters. + +OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like +OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively, +except that they call memset() to zero the memory before returning. -B<OPENSSL_secure_free> releases the memory at C<ptr> back to the heap. +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>. +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 +is a macro that expands to CRYPTO_secure_free(). -B<OPENSSL_secure_allocated> tells whether or not a pointer is within +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 +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 +CRYPTO_secure_malloc_used() returns the number of bytes allocated in the secure heap. =head1 RETURN VALUES -B<CRYPTO_secure_malloc_init> returns 0 on failure, 1 if successful, +CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful, and 2 if successful but the heap could not be protected by memory mapping. -B<CRYPTO_secure_malloc_initialized> returns 1 if the secure heap is -available (that is, if B<CRYPTO_secure_malloc_init> has been called, -but B<CRYPTO_secure_malloc_done> has not) or 0 if not. +CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is +available (that is, if CRYPTO_secure_malloc_init() has been called, +but CRYPTO_secure_malloc_done() has not) or 0 if not. -B<OPENSSL_secure_malloc> returns a pointer into the secure heap of -the requested size, or C<NULL> if memory could not be allocated. +OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into +the secure heap of the requested size, or C<NULL> if memory could not be +allocated. -B<CRYPTO_secure_allocated> returns 1 if the pointer is in the +CRYPTO_secure_allocated() returns 1 if the pointer is in the the secure heap, or 0 if not. -B<CRYPTO_secure_malloc_done> and B<OPENSSL_secure_free> +CRYPTO_secure_malloc_done() and OPENSSL_secure_free() return no values. =head1 BUGS |