memset()
and hand-written code can be silently stripped out by an optimizing compiler or the linker.sodium_memzero()
function tries to effectively zero len
bytes starting at pnt
, even if optimizations are being applied to the code.sodium_mlock()
function locks at least len
bytes of memory starting at addr
. This can help avoid swapping sensitive data to disk.ulimit
or programmatically using setrlimit(RLIMIT_CORE, &(struct rlimit) {0, 0})
. On operating systems where this feature is implemented, kernel crash dumps should also be disabled.sodium_mlock()
wraps mlock()
and VirtualLock()
. Note: Many systems place limits on the amount of memory that may be locked by a process. Care should be taken to raise those limits (e.g. Unix ulimits) where necessary. sodium_mlock()
will return -1
when any limit is reached.sodium_munlock()
function should be called after locked memory is not being used anymore. It will zero len
bytes starting at addr
before flagging the pages as swappable again. Calling sodium_memzero()
prior to sodium_munlock()
is thus not required.sodium_mlock()
also wraps madvise()
and advises the kernel not to include the locked memory in core dumps. sodium_munlock()
also undoes this additional protection.malloc()
and friends and require 3 or 4 extra pages of virtual memory.sodium_init()
must be called before using any of the guarded heap allocation functions.sodium_malloc()
function returns a pointer from which exactly size
contiguous bytes of memory can be accessed. Like normal malloc
, NULL
may be returned and errno
set if it is not possible to allocate enough memory.sodium_free()
and cause the application to immediately terminate.0xdb
bytes to help catch bugs due to uninitialized data.sodium_mlock()
is called on the region to help avoid it being swapped to disk. On operating systems supporting MAP_NOCORE
or MADV_DONTDUMP
, memory allocated this way will also not be part of core dumps.sodium_malloc()
should not be used with packed or variable-length structures unless the size given to sodium_malloc()
is rounded up to ensure proper alignment.sodium_malloc()
.0
bytes is a valid operation. It returns a pointer that can be successfully passed to sodium_free()
.sodium_allocarray()
function returns a pointer from which count
objects that are size
bytes of memory each can be accessed.sodium_malloc()
but also protects against arithmetic overflows when count * size
exceeds SIZE_MAX
.sodium_free()
function unlocks and deallocates memory allocated using sodium_malloc()
or sodium_allocarray()
.sodium_free()
also fills the memory region with zeros before the deallocation.sodium_mprotect_readonly()
; the protection will automatically be changed as needed.ptr
can be NULL
, in which case no operation is performed.sodium_mprotect_noaccess()
function makes a region allocated using sodium_malloc()
or sodium_allocarray()
inaccessible. It cannot be read or written, but the data are preserved.sodium_mprotect_readonly()
function marks a region allocated using sodium_malloc()
or sodium_allocarray()
as read-only.sodium_mprotect_readwrite()
function marks a region allocated using sodium_malloc()
or sodium_allocarray()
as readable and writable after having been protected using sodium_mprotect_readonly()
or sodium_mprotect_noaccess()
.