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