diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/secmem.txt | 96 |
1 files changed, 23 insertions, 73 deletions
diff --git a/doc/secmem.txt b/doc/secmem.txt index eba3462de..76751bb40 100644 --- a/doc/secmem.txt +++ b/doc/secmem.txt @@ -1,81 +1,31 @@ -Secure Memory Containers +Memory container ======================================== A major concern with mixing modern multiuser OSes and cryptographic code is that at any time the code (including secret keys) could be -swapped to disk, where it can later be read by an attacker. Botan -stores almost everything (and especially anything sensitive) in memory -buffers that a) clear out their contents when their destructors are -called, and b) have easy plugins for various memory locking functions, -such as the ``mlock`` call on many Unix systems. - -Two of the allocation method used ("malloc" and "mmap") don't -require any extra privileges on Unix, but locking memory does. At -startup, each allocator type will attempt to allocate a few blocks -(typically totaling 128k), so if you want, you can run your -application ``setuid`` ``root``, and then drop privileges -immediately after creating your ``LibraryInitializer``. If you end -up using more than what's been allocated, some of your sensitive data -might end up being swappable, but that beats running as ``root`` -all the time. - -These classes should also be used within your own code for storing -sensitive data. They are only meant for primitive data types (int, -long, etc): if you want a container of higher level Botan objects, you -can just use a ``std::vector``, since these objects know how to clear -themselves when they are destroyed. You cannot, however, have a -``std::vector`` (or any other container) of ``Pipe`` objects or +swapped to disk, where it can later be read by an attacker, or left +floating around in memory for later retreval. + +For this reason the library uses a ``std::vector`` with a custom +allocator that will zero memory before deallocation, named via typedef +as ``secure_vector``. Because it is simply a STL vector with a custom +allocator, it has an identical API to the ``std::vector`` you know and +love. + +Some operating systems offer the ability to lock memory into RAM, +preventing swapping from occuring. Typically this operation is +restricted to privledged users (root or admin), however some OSes +including Linux and FreeBSD allow normal users to lock a small amount +of memory. On these systems, allocations first attempt to allocate out +of this small locked pool, and then if that fails will fall back to +normal heap allocations. + +The ``secure_vector`` template is only meant for primitive data types +(bytes or ints): if you want a container of higher level Botan +objects, you can just use a ``std::vector``, since these objects know +how to clear themselves when they are destroyed. You cannot, however, +have a ``std::vector`` (or any other container) of ``Pipe`` objects or filters, because these types have pointers to other filters, and implementing copy constructors for these types would be both hard and quite expensive (vectors of pointers to such objects is fine, though). - -These types are not described in any great detail: for more information, -consult the definitive sources~--~the header files ``secmem.h`` and -``allocate.h``. - -``SecureBuffer`` is a simple array type, whose size is specified at -compile time. It will automatically convert to a pointer of the -appropriate type, and has a number of useful functions, including -``clear()``, and ``size_t`` ``size()``, which returns the length of -the array. It is a template that takes as parameters a type, and a -constant integer which is how long the array is (for example: -``SecureBuffer<byte, 8> key;``). - -``SecureVector`` is a variable length array. Its size can be increased -or decreased as need be, and it has a wide variety of functions useful -for copying data into its buffer. Like ``SecureBuffer``, it implements -``clear`` and ``size``. - -Allocators -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The containers described above get their memory from allocators. As a -user of the library, you can add new allocator methods at run time for -containers, including the ones used internally by the library, to -use. The interface to this is in ``allocate.h``. Code needing to -allocate or deallocate memory calls ``get_allocator``, which returns a -pointer to an allocator object. This pointer should not be freed: the -caller does not own the allocator (it is shared among multiple -allocatore users, and uses a mutex to serialize access internally if -necessary). It is possible to call ``get_allocator`` with a specific -name to request a particular type of allocator, otherwise, a default -allocator type is returned. - -At start time, the only allocator known is a ``Default_Allocator``, -which just allocates memory using ``malloc``, and zeroizes it when the -memory is released. It is known by the name "malloc". If you ask for -another type of allocator ("locking" and "mmap" are currently used), -and it is not available, some other allocator will be returned. - -You can add in a new allocator type using ``add_allocator_type``. This -function takes a string and a pointer to an allocator. The string gives this -allocator type a name to which it can be referred when one is requesting it -with ``get_allocator``. If an error occurs (such as the name being -already registered), this function returns false. It will return true if the -allocator was successfully registered. If you ask it to, -``LibraryInitializer`` will do this for you. - -Finally, you can set the default allocator type that will be returned -using the policy setting "default_alloc" to the name of any previously -registered allocator. |