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