secure.hh File Reference

Secure memory handling: zeroization, locked allocations and sensitive value containers. More...

#include <array>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <iosfwd>
#include <string>
#include <vector>
#include "libkeepass/export.hh"

Go to the source code of this file.

Classes
class	keepass::SecureBuffer< N >
	Fixed-size byte buffer that is zeroized on destruction. More...
class	keepass::SecureBytes
	Dynamic byte buffer that is zeroized in best-effort locked memory. More...
class	keepass::secure_string
	String that is stored in wiped and best-effort locked memory. More...

Functions
LIBKEEPASS_API void	keepass::secure_zero (void *data, std::size_t size) noexcept
	Securely erases a memory region by overwriting it with zero bytes.
LIBKEEPASS_API void *	keepass::secure_alloc (std::size_t size) noexcept
	Allocates a memory region that is best-effort locked in RAM.
LIBKEEPASS_API void	keepass::secure_free (void *data, std::size_t size) noexcept
	Erases and releases memory obtained from secure_alloc().
LIBKEEPASS_API bool	keepass::operator== (const secure_string &lhs, const secure_string &rhs)
	Returns whether two secure strings hold the same bytes.
LIBKEEPASS_API bool	keepass::operator!= (const secure_string &lhs, const secure_string &rhs)
	Returns whether two secure strings hold different bytes.
LIBKEEPASS_API bool	keepass::operator== (const secure_string &lhs, const std::string &rhs)
	Returns whether a secure string matches a std::string.
LIBKEEPASS_API bool	keepass::operator== (const std::string &lhs, const secure_string &rhs)
	Returns whether a std::string matches a secure string.
LIBKEEPASS_API bool	keepass::operator!= (const secure_string &lhs, const std::string &rhs)
	Returns whether a secure string differs from a std::string.
LIBKEEPASS_API bool	keepass::operator!= (const std::string &lhs, const secure_string &rhs)
	Returns whether a std::string differs from a secure string.
LIBKEEPASS_API bool	keepass::operator== (const secure_string &lhs, const char *rhs)
	Returns whether a secure string matches a NUL-terminated C string.
LIBKEEPASS_API bool	keepass::operator== (const char *lhs, const secure_string &rhs)
	Returns whether a NUL-terminated C string matches a secure string.
LIBKEEPASS_API bool	keepass::operator!= (const secure_string &lhs, const char *rhs)
	Returns whether a secure string differs from a NUL-terminated C string.
LIBKEEPASS_API bool	keepass::operator!= (const char *lhs, const secure_string &rhs)
	Returns whether a NUL-terminated C string differs from a secure string.
LIBKEEPASS_API std::ostream &	keepass::operator<< (std::ostream &os, const secure_string &str)
	Writes the string content to a stream.

Detailed Description

Secure memory handling: zeroization, locked allocations and sensitive value containers.

Function Documentation

secure_alloc()

LIBKEEPASS_API void * keepass::secure_alloc ( std::size_t  size )

noexcept

Allocates a memory region that is best-effort locked in RAM.

Locking the pages prevents them from being swapped out to disk. Locking is best-effort: it may fail (for example when the process runs out of the mlock allowance) and the call still succeeds with an unlocked allocation. Regardless of locking, always wipe the memory with secure_zero() before calling secure_free().

Parameters

size	Number of bytes to allocate (at least one byte is allocated).

Returns

Pointer to the allocated memory or nullptr on allocation failure.

secure_free()

LIBKEEPASS_API void keepass::secure_free ( void *  data, std::size_t  size  )

noexcept

Erases and releases memory obtained from secure_alloc().

Parameters

data	Pointer returned by secure_alloc(), or nullptr.
size	Size that was passed to secure_alloc().

secure_zero()

LIBKEEPASS_API void keepass::secure_zero ( void *  data, std::size_t  size  )

noexcept

Securely erases a memory region by overwriting it with zero bytes.

The write is performed through a volatile pointer so that optimizing compilers cannot elide the operation.

Parameters

data	Pointer to the region to erase.
size	Number of bytes to erase.