Commit 3538c7da authored by Rich Salz's avatar Rich Salz
Browse files

Add CRYPTO_secure_zalloc 



Also turn B<foo> into foo() in the pod page.

Reviewed-by: default avatarViktor Dukhovni <viktor@openssl.org>
parent 109f8b5d

crypto/mem_sec.c

+9 −0
Original line number Diff line number Diff line
@@ -110,6 +110,15 @@ void *CRYPTO_secure_malloc(size_t num, const char *file, int line) 
#endif /* IMPLEMENTED */

}



void *CRYPTO_secure_zalloc(size_t num, const char *file, int line)

{

    void *ret = CRYPTO_secure_malloc(num, file, line);



    if (ret != NULL)

        memset(ret, 0, num);

    return ret;

}



void CRYPTO_secure_free(void *ptr)

{

#ifdef IMPLEMENTED

doc/crypto/OPENSSL_secure_malloc.pod

+38 −27
Original line number Diff line number Diff line
@@ -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

include/openssl/crypto.h

+5 −0
Original line number Diff line number Diff line
@@ -312,6 +312,8 @@ int CRYPTO_mem_ctrl(int mode); 
        CRYPTO_strndup(str, n, __FILE__, __LINE__)

#  define OPENSSL_secure_malloc(num) \

        CRYPTO_secure_malloc(num, __FILE__, __LINE__)

#  define OPENSSL_secure_zalloc(num) \

        CRYPTO_secure_zalloc(num, __FILE__, __LINE__)

#  define OPENSSL_secure_free(addr) \

        CRYPTO_secure_free(addr)

#  define OPENSSL_secure_actual_size(ptr) \
@@ -337,6 +339,8 @@ int CRYPTO_mem_ctrl(int mode); 
        CRYPTO_strndup(str, s, NULL, 0)

#  define OPENSSL_secure_malloc(num) \

        CRYPTO_secure_malloc(num, NULL, 0)

#  define OPENSSL_secure_zalloc(num) \

        CRYPTO_secure_zalloc(num, NULL, 0)

#  define OPENSSL_secure_free(addr) \

        CRYPTO_secure_free(addr)

#  define OPENSSL_secure_actual_size(ptr) \
@@ -478,6 +482,7 @@ void *CRYPTO_clear_realloc(void *addr, size_t old_num, size_t num, 
int CRYPTO_secure_malloc_init(size_t sz, int minsize);

void CRYPTO_secure_malloc_done(void);

void *CRYPTO_secure_malloc(size_t num, const char *file, int line);

void *CRYPTO_secure_zalloc(size_t num, const char *file, int line);

void CRYPTO_secure_free(void *ptr);

int CRYPTO_secure_allocated(const void *ptr);

int CRYPTO_secure_malloc_initialized(void);

util/libeay.num

+1 −0
Original line number Diff line number Diff line
@@ -4764,3 +4764,4 @@ TS_STATUS_INFO_get0_status 5158 1_1_0 EXIST::FUNCTION: 
OCSP_resp_get0_produced_at              5159	1_1_0	EXIST::FUNCTION:

TS_STATUS_INFO_get0_failure_info        5160	1_1_0	EXIST::FUNCTION:

TS_STATUS_INFO_get0_text                5161	1_1_0	EXIST::FUNCTION:

CRYPTO_secure_zalloc                    5162	1_1_0	EXIST::FUNCTION: