1=pod 2 3=head1 NAME 4 5CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized, 6CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc, 7OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free, 8CRYPTO_secure_free, OPENSSL_secure_clear_free, 9CRYPTO_secure_clear_free, OPENSSL_secure_actual_size, 10CRYPTO_secure_allocated, 11CRYPTO_secure_used - secure heap storage 12 13=head1 SYNOPSIS 14 15 #include <openssl/crypto.h> 16 17 int CRYPTO_secure_malloc_init(size_t size, size_t minsize); 18 19 int CRYPTO_secure_malloc_initialized(); 20 21 int CRYPTO_secure_malloc_done(); 22 23 void *OPENSSL_secure_malloc(size_t num); 24 void *CRYPTO_secure_malloc(size_t num, const char *file, int line); 25 26 void *OPENSSL_secure_zalloc(size_t num); 27 void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); 28 29 void OPENSSL_secure_free(void* ptr); 30 void CRYPTO_secure_free(void *ptr, const char *, int); 31 32 void OPENSSL_secure_clear_free(void* ptr, size_t num); 33 void CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int); 34 35 size_t OPENSSL_secure_actual_size(const void *ptr); 36 37 int CRYPTO_secure_allocated(const void *ptr); 38 size_t CRYPTO_secure_used(); 39 40=head1 DESCRIPTION 41 42In order to help protect applications (particularly long-running servers) 43from pointer overruns or underruns that could return arbitrary data from 44the program's dynamic memory area, where keys and other sensitive 45information might be stored, OpenSSL supports the concept of a "secure heap." 46The level and type of security guarantees depend on the operating system. 47It is a good idea to review the code and see if it addresses your 48threat model and concerns. It should be noted that the secure heap 49uses a single read/write lock, and therefore any operations 50that involve allocation or freeing of secure heap memory are serialised, 51blocking other threads. With that in mind, highly concurrent applications 52should enable the secure heap with caution and be aware of the performance 53implications for multi-threaded code. 54 55If a secure heap is used, then private key B<BIGNUM> values are stored there. 56This protects long-term storage of private keys, but will not necessarily 57put all intermediate values and computations there. 58 59CRYPTO_secure_malloc_init() creates the secure heap, with the specified 60C<size> in bytes. The C<minsize> parameter is the minimum size to 61allocate from the heap or zero to use a reasonable default value. 62Both C<size> and, if specified, C<minsize> must be a power of two and 63C<minsize> should generally be small, for example 16 or 32. 64C<minsize> must be less than a quarter of C<size> in any case. 65 66CRYPTO_secure_malloc_initialized() indicates whether or not the secure 67heap as been initialized and is available. 68 69CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable 70to the process if all secure memory has been freed. 71It can take noticeably long to complete. 72 73OPENSSL_secure_malloc() allocates C<num> bytes from the heap. 74If CRYPTO_secure_malloc_init() is not called, this is equivalent to 75calling OPENSSL_malloc(). 76It is a macro that expands to 77CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters. 78 79OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like 80OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively, 81except that they call memset() to zero the memory before returning. 82 83OPENSSL_secure_free() releases the memory at C<ptr> back to the heap. 84It must be called with a value previously obtained from 85OPENSSL_secure_malloc(). 86If CRYPTO_secure_malloc_init() is not called, this is equivalent to 87calling OPENSSL_free(). 88It exists for consistency with OPENSSL_secure_malloc() , and 89is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__> 90and C<__LINE__> parameters.. If the argument to OPENSSL_secure_free() 91is NULL, nothing is done. 92 93OPENSSL_secure_clear_free() is similar to OPENSSL_secure_free() except 94that it has an additional C<num> parameter which is used to clear 95the memory if it was not allocated from the secure heap. 96If CRYPTO_secure_malloc_init() is not called, this is equivalent to 97calling OPENSSL_clear_free(). If the argument to OPENSSL_secure_clear_free() 98is NULL, nothing is done. 99 100OPENSSL_secure_actual_size() tells the actual size allocated to the 101pointer; implementations may allocate more space than initially 102requested, in order to "round up" and reduce secure heap fragmentation. 103 104OPENSSL_secure_allocated() tells if a pointer is allocated in the secure heap. 105 106CRYPTO_secure_used() returns the number of bytes allocated in the 107secure heap. 108 109=head1 RETURN VALUES 110 111CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful, 112and 2 if successful but the heap could not be protected by memory 113mapping. 114 115CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is 116available (that is, if CRYPTO_secure_malloc_init() has been called, 117but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not. 118 119OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into 120the secure heap of the requested size, or C<NULL> if memory could not be 121allocated. 122 123CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not. 124 125CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not. 126 127OPENSSL_secure_free() and OPENSSL_secure_clear_free() return no values. 128 129=head1 SEE ALSO 130 131L<OPENSSL_malloc(3)>, 132L<BN_new(3)> 133 134=head1 HISTORY 135 136The OPENSSL_secure_clear_free() function was added in OpenSSL 1.1.0g. 137 138The second argument to CRYPTO_secure_malloc_init() was changed from an B<int> to 139a B<size_t> in OpenSSL 3.0. 140 141=head1 COPYRIGHT 142 143Copyright 2015-2025 The OpenSSL Project Authors. All Rights Reserved. 144 145Licensed under the Apache License 2.0 (the "License"). You may not use 146this file except in compliance with the License. You can obtain a copy 147in the file LICENSE in the source distribution or at 148L<https://www.openssl.org/source/license.html>. 149 150=cut 151