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