More secure storage of key material.

Add secure heap for storage of private keys (when possible).
Add BIO_s_secmem(), CBIGNUM, etc.
Add BIO_CTX_secure_new so all BIGNUM's in the context are secure.
Contributed by Akamai Technologies under the Corporate CLA.

Reviewed-by: Richard Levitte <levitte@openssl.org>

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