diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BIO_s_mem.pod | 7 | ||||
-rw-r--r-- | doc/crypto/BN_CTX_new.pod | 15 | ||||
-rw-r--r-- | doc/crypto/CRYPTO_secure_malloc.pod | 91 | ||||
-rw-r--r-- | doc/crypto/bio.pod | 1 | ||||
-rw-r--r-- | doc/crypto/bn.pod | 1 | ||||
-rw-r--r-- | doc/crypto/buffer.pod | 14 |
6 files changed, 123 insertions, 6 deletions
diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod index 8f85e0dcee..1aa7e6ebf9 100644 --- a/doc/crypto/BIO_s_mem.pod +++ b/doc/crypto/BIO_s_mem.pod @@ -10,6 +10,7 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO #include <openssl/bio.h> BIO_METHOD * BIO_s_mem(void); + BIO_METHOD * BIO_s_secmem(void); BIO_set_mem_eof_return(BIO *b,int v) long BIO_get_mem_data(BIO *b, char **pp) @@ -26,6 +27,9 @@ A memory BIO is a source/sink BIO which uses memory for its I/O. Data written to a memory BIO is stored in a BUF_MEM structure which is extended as appropriate to accommodate the stored data. +BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used +for buffer storage. + Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read only any data read from it is deleted from the BIO. @@ -79,6 +83,9 @@ read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO to the chain will speed up the process. +Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will +give undefined results, including perhaps a program crash. + =head1 BUGS There should be an option to set the maximum size of a memory BIO. diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod index 5da8433637..958e551467 100644 --- a/doc/crypto/BN_CTX_new.pod +++ b/doc/crypto/BN_CTX_new.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures +BN_CTX_new, BN_CTX_secure_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures =head1 SYNOPSIS @@ -10,6 +10,8 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures BN_CTX *BN_CTX_new(void); + BN_CTX *BN_CTX_secure_new(void); + void BN_CTX_free(BN_CTX *c); =head1 DESCRIPTION @@ -19,8 +21,10 @@ library functions. Since dynamic memory allocation to create B<BIGNUM>s is rather expensive when used in conjunction with repeated subroutine calls, the B<BN_CTX> structure is used. -BN_CTX_new() allocates and initializes a B<BN_CTX> -structure. +BN_CTX_new() allocates and initializes a B<BN_CTX> structure. +BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure +but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the +B<BIGNUM>s. BN_CTX_free() frees the components of the B<BN_CTX>, and if it was created by BN_CTX_new(), also the structure itself. @@ -31,8 +35,9 @@ If B<c> is NULL, nothing is done. =head1 RETURN VALUES -BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained by +BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>. +If the allocation fails, +they return B<NULL> and sets an error code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. BN_CTX_free() has no return values. diff --git a/doc/crypto/CRYPTO_secure_malloc.pod b/doc/crypto/CRYPTO_secure_malloc.pod new file mode 100644 index 0000000000..a3b416ed08 --- /dev/null +++ b/doc/crypto/CRYPTO_secure_malloc.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, OPENSSL_secure_free, OPENSSL_secure_allocated - use secure heap storage + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int CRYPTO_secure_malloc_init(size_t size, int minsize); + + int CRYPTO_secure_malloc_initialized(); + + void CRYPTO_secure_malloc_done(); + + void *OPENSSL_secure_malloc(int num); + + void OPENSSL_secure_free(void* ptr); + + int OPENSSL_secure_allocated(const void* ptr); + +=head1 DESCRIPTION + +In order to help protect applications (particularly long-running servers) +from pointer overruns or underruns that could return arbitrary data from +the program's dynamic memory area, where keys and other sensitive +information might be stored, OpenSSL supports the concept of a "secure heap." +The level and type of security guarantees depend on the operating system. +It is a good idea to review the code and see if it addresses your +threat model and concerns. + +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 +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> +calls have been made. + +B<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 +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>. + +B<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>. + +B<OPENSSL_secure_allocated> tells whether or not a pointer is within +the secure heap. + +=head1 RETURN VALUES + +B<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. + +B<OPENSSL_secure_malloc> returns 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 +the secure heap, or 0 if not. + +B<CRYPTO_secure_malloc_done> and B<OPENSSL_secure_free> +return no values. + +=head1 SEE ALSO + +L<BN_new(3)|BN_new(3)>, +L<bn_internal(3)|bn_internal(3)> + +=head1 HISTORY + +These functions were contributed to the OpenSSL project by +Akamai Technologies in April, 2014. + +=cut diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod index f9239226ff..9debe4f1b6 100644 --- a/doc/crypto/bio.pod +++ b/doc/crypto/bio.pod @@ -49,6 +49,7 @@ L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, +L<BIO_s_secmem(3)|BIO_s_mem(3)>, L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, L<BIO_set_callback(3)|BIO_set_callback(3)>, L<BIO_should_retry(3)|BIO_should_retry(3)> diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod index b52916bada..ab809f95e4 100644 --- a/doc/crypto/bn.pod +++ b/doc/crypto/bn.pod @@ -14,6 +14,7 @@ bn - multiprecision integer arithmetics void BN_clear_free(BIGNUM *a); BN_CTX *BN_CTX_new(void); + BN_CTX *BN_CTX_secure_new(void); void BN_CTX_free(BN_CTX *c); BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod index 781f5b11ee..3804c5649b 100644 --- a/doc/crypto/buffer.pod +++ b/doc/crypto/buffer.pod @@ -11,6 +11,10 @@ character arrays structure BUF_MEM *BUF_MEM_new(void); + #define BUF_MEM_FLAG_SECURE + + BUF_MEM * BUF_MEM_new_ex(unsigned long flags); + void BUF_MEM_free(BUF_MEM *a); int BUF_MEM_grow(BUF_MEM *str, int len); @@ -37,6 +41,10 @@ and one "miscellaneous" function. BUF_MEM_new() allocates a new buffer of zero size. +BUF_MEM_new_ex() allocates a buffer with the specified flags. +The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer +should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>. + BUF_MEM_free() frees up an already existing buffer. The data is zeroed before freeing up in case the buffer contains sensitive data. @@ -63,11 +71,15 @@ BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). =head1 SEE ALSO -L<bio(3)|bio(3)> +L<bio(3)|bio(3)>, +L<CRYPTO_secure_malloc(3)>. =head1 HISTORY BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. +BUF_MEM_new_ex() was contributed to OpenSSL by Akamai Technologies +in May, 2014. + =cut |