StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::SecureBinary Class Referencefinal

Binary for secrets: every byte it drops or releases is zeroed first. More...

#include <StormByte/safe/secure_binary.hxx>

Inheritance diagram for StormByte::Safe::SecureBinary:
Collaboration diagram for StormByte::Safe::SecureBinary:

Public Member Functions

 SecureBinary () noexcept
 Construct an empty sequence.
 SecureBinary (const ByteSize &count, std::byte value)
 Construct count bytes filled with value.
 SecureBinary (const ByteSize &count)
 Construct count zeroed bytes.
 SecureBinary (std::span< const std::byte > bytes)
 Copy bytes from a contiguous span.
 SecureBinary (const std::byte *bytes, const ByteSize &count)
 Copy count bytes starting at bytes.
 SecureBinary (std::initializer_list< std::byte > list)
 Copy from an initializer list.
 SecureBinary (std::string_view text)
 Copy character bytes from a string view.
 SecureBinary (const char *text)
 Copy character bytes from a C string.
STORMBYTE_FORCE_INLINE SecureBinary (const std::vector< std::byte > &bytes)
 Copy bytes from a caller-owned vector.
STORMBYTE_FORCE_INLINE SecureBinary (std::vector< std::byte > &&bytes)
 Copy bytes from a caller-owned vector, then zero and release it.
template<Type::ByteInputRange R>
 SecureBinary (const R &range)
 Copy from an input range of byte-convertible values.
template<Type::ByteInputRange R>
 SecureBinary (R &&range)
 Consume an rvalue range.
 SecureBinary (const SecureBinary &other)
 Copy construct.
 SecureBinary (SecureBinary &&other) noexcept
 Move construct.
 ~SecureBinary () noexcept override
 Zero the whole block, then release it.
SecureBinary & operator= (const SecureBinary &other)
 Copy assign.
SecureBinary & operator= (SecureBinary &&other) noexcept
 Move assign.
SecureBinary & operator= (std::initializer_list< std::byte > list)
 Replace contents with an initializer list.
 operator std::vector< std::byte > () const &=delete
 Not available: the vector would hold the secret in memory that is never wiped.
 operator std::vector< std::byte > () &&=delete
 Not available: the vector would hold the secret in memory that is never wiped.
String HexDump () const =delete
 Not available: the dump would hold the secret in memory that is never wiped.
String HexDump (Size columns) const =delete
 Not available: the dump would hold the secret in memory that is never wiped.
Public Member Functions inherited from StormByte::Safe::Binary
 Binary () noexcept
 Construct an empty sequence.
 Binary (const ByteSize &count, std::byte value)
 Construct count bytes filled with value.
 Binary (const ByteSize &count)
 Construct count zeroed bytes.
 Binary (std::span< const std::byte > bytes)
 Copy bytes from a contiguous span.
 Binary (const std::byte *bytes, const ByteSize &count)
 Copy count bytes starting at bytes.
 Binary (std::initializer_list< std::byte > list)
 Copy from an initializer list.
 Binary (std::string_view text)
 Copy character bytes from a string view.
 Binary (const char *text)
 Copy character bytes from a C string.
STORMBYTE_FORCE_INLINE Binary (const std::vector< std::byte > &bytes)
 Copy bytes from a caller-owned vector.
STORMBYTE_FORCE_INLINE Binary (std::vector< std::byte > &&bytes)
 Copy bytes from a caller-owned vector, then empty it.
template<Type::ByteInputRange R>
 Binary (const R &range)
 Copy from an input range of byte-convertible values.
template<Type::ByteInputRange R>
 Binary (R &&range)
 Consume an rvalue range.
 Binary (const Binary &other)
 Copy construct.
 Binary (Binary &&other) noexcept
 Move construct.
virtual ~Binary () noexcept
 Destroy the sequence on Base's heap.
Binary & operator= (const Binary &other)
 Copy assign.
Binary & operator= (Binary &&other) noexcept
 Move assign.
Binary & operator= (std::initializer_list< std::byte > list)
 Replace contents with an initializer list.
bool operator== (const Binary &other) const noexcept
 Equality of byte contents.
bool operator!= (const Binary &other) const noexcept
 Inequality of byte contents.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const Binary &other) const noexcept
 Three-way lexicographical comparison.
bool operator== (std::span< const std::byte > bytes) const noexcept
 Equality with a byte span.
bool operator!= (std::span< const std::byte > bytes) const noexcept
 Inequality with a byte span.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (std::span< const std::byte > bytes) const noexcept
 Three-way comparison with a byte span.
iterator begin () noexcept
 Mutable iterator to the first byte.
const_iterator begin () const noexcept
 Read-only iterator to the first byte.
iterator end () noexcept
 Mutable iterator one past the last byte.
const_iterator end () const noexcept
 Read-only iterator one past the last byte.
const_iterator cbegin () const noexcept
 Read-only iterator to the first byte.
const_iterator cend () const noexcept
 Read-only iterator one past the last byte.
reverse_iterator rbegin () noexcept
 Mutable reverse iterator to the last byte.
reverse_iterator rend () noexcept
 Mutable reverse iterator before the first byte.
const_reverse_iterator rbegin () const noexcept
 Read-only reverse iterator to the last byte.
const_reverse_iterator rend () const noexcept
 Read-only reverse iterator before the first byte.
const_reverse_iterator crbegin () const noexcept
 Read-only reverse iterator to the last byte.
const_reverse_iterator crend () const noexcept
 Read-only reverse iterator before the first byte.
ByteSize size () const noexcept
 Occupied length in bytes.
ByteSize max_size () const noexcept
 Implementation maximum size in bytes.
ByteSize capacity () const noexcept
 Allocated capacity in bytes.
bool empty () const noexcept
 Whether the sequence holds no bytes.
void reserve (const ByteSize &new_cap)
 Request capacity of at least new_cap bytes.
void resize (const ByteSize &new_size)
 Resize to new_size bytes.
void resize (const ByteSize &new_size, std::byte value)
 Resize to new_size bytes.
void shrink_to_fit ()
 Release unused capacity when the implementation allows it.
void clear () noexcept
 Drop every byte.
std::byte & operator[] (const ByteSize &index) noexcept
 Unchecked mutable subscript.
const std::byte & operator[] (const ByteSize &index) const noexcept
 Unchecked read-only subscript.
std::byte & at (const ByteSize &index)
 Checked mutable subscript.
const std::byte & at (const ByteSize &index) const
 Checked read-only subscript.
std::byte & front ()
 First byte.
const std::byte & front () const
 First byte.
std::byte & back ()
 Last byte.
const std::byte & back () const
 Last byte.
std::byte * data () noexcept
 Mutable pointer to the first byte, or null when empty.
const std::byte * data () const noexcept
 Read-only pointer to the first byte, or null when empty.
STORMBYTE_FORCE_INLINE std::span< std::byte > span () noexcept
 Mutable view of the occupied bytes.
STORMBYTE_FORCE_INLINE std::span< const std::byte > span () const noexcept
 Read-only view of the occupied bytes.
STORMBYTE_FORCE_INLINE operator std::span< std::byte > () noexcept
 Implicit mutable span conversion.
STORMBYTE_FORCE_INLINE operator std::span< const std::byte > () const noexcept
 Implicit read-only span conversion.
STORMBYTE_FORCE_INLINE operator std::vector< std::byte > () const &
 Copy bytes onto the caller CRT as a vector.
STORMBYTE_FORCE_INLINE operator std::vector< std::byte > () &&
 Copy bytes onto the caller CRT, then release this object's storage.
void assign (const ByteSize &count, std::byte value)
 Replace contents with count copies of value.
void assign (std::span< const std::byte > bytes)
 Replace contents with a copy of bytes.
void assign (std::initializer_list< std::byte > list)
 Replace contents with an initializer list.
template<typename InputIt>
void assign (InputIt first, InputIt last)
 Replace contents with the range [first, last).
void append (std::span< const std::byte > bytes)
 Append a copy of bytes.
void append (const std::byte *bytes, const ByteSize &count)
 Append count bytes starting at bytes.
void append (const Binary &other)
 Append a copy of other.
void append (Binary &&other)
 Append other, then empty it.
Binary & operator+= (std::span< const std::byte > bytes)
 Append a copy of bytes.
Binary & operator+= (const Binary &other)
 Append a copy of other.
Binary & operator+= (Binary &&other)
 Append other, then empty it.
void push_back (std::byte value)
 Append one byte.
template<typename T>
reference emplace_back (T &&value)
 Append a byte constructed in place.
void pop_back ()
 Remove the last byte.
iterator insert (const_iterator pos, std::byte value)
 Insert one byte before pos.
iterator insert (const_iterator pos, const ByteSize &count, std::byte value)
 Insert count copies of value before pos.
iterator insert (const_iterator pos, std::initializer_list< std::byte > list)
 Insert an initializer list before pos.
iterator insert (const_iterator pos, std::span< const std::byte > bytes)
 Insert a span before pos.
template<typename InputIt>
iterator insert (const_iterator pos, InputIt first, InputIt last)
 Insert the range [first, last) before pos.
iterator erase (const_iterator pos)
 Erase the byte at pos.
iterator erase (const_iterator first, const_iterator last)
 Erase [first, last).
void swap (Binary &other) noexcept
 Exchange storage with other.
String HexDump () const
 Hexadecimal dump, sixteen bytes per row.
String HexDump (Size columns) const
 Hexadecimal dump of the occupied bytes.

Protected Member Functions

void Discard (std::span< std::byte > bytes) noexcept override
 Zero bytes.
bool ConstantTimeCompare () const noexcept override
 Equality with this object never stops at the first difference.
void Acquire (std::span< std::byte > block) noexcept override
 Best effort: lock the pages of block in memory so they are not written to swap.
void Release (std::span< std::byte > block) noexcept override
 Unlock the pages of block once no other block on the same pages is locked.
Protected Member Functions inherited from StormByte::Safe::Binary
std::span< std::byte > Storage () noexcept
 The whole allocated block, including unused capacity.

Additional Inherited Members

Public Types inherited from StormByte::Safe::Binary
using value_type = std::byte
 Element type.
using size_type = Size
 Count typedef. size() returns ByteSize.
using difference_type = std::ptrdiff_t
 Iterator difference.
using reference = std::byte&
 Mutable element reference.
using const_reference = const std::byte&
 Read-only element reference.
using pointer = std::byte*
 Mutable pointer.
using const_pointer = const std::byte*
 Read-only pointer.
using iterator = std::byte*
 Contiguous mutable iterator.
using const_iterator = const std::byte*
 Contiguous read-only iterator.
using reverse_iterator = std::reverse_iterator<iterator>
 Reverse iterator.
using const_reverse_iterator = std::reverse_iterator<const_iterator>
 Read-only reverse iterator.
Static Protected Member Functions inherited from StormByte::Safe::Binary
static void Wipe (std::span< std::byte > bytes) noexcept
 Zero bytes.

Detailed Description

Binary for secrets: every byte it drops or releases is zeroed first.

Same API as Binary. Erased, popped and truncated bytes, previous contents on assign, the old block when the storage grows or shrinks, and the whole block in the destructor are zeroed with writes the compiler cannot drop. Equality runs in constant time for equal sizes.

Each block it owns is also locked in memory (mlock, VirtualLock on Windows) so it is not written to swap. This is best effort: when the process limit is reached (RLIMIT_MEMLOCK, the Windows minimum working set) the block stays unlocked and everything else still works. Pages shared with other blocks are counted and stay locked until the last of them goes.

Not covered: a move, swap or append(&&) with a plain Binary hands the block over as is. The secret is then no longer wiped or locked by this type. Copies made through span() or a const Binary& are the caller's responsibility.

There is no conversion to std::vector, no HexDump, and no StormByte::Serializable support: each would copy the secret into memory that is never wiped.

Constructor & Destructor Documentation

◆ SecureBinary() [1/14]

StormByte::Safe::SecureBinary::SecureBinary ( )
noexcept

Construct an empty sequence.

◆ SecureBinary() [2/14]

StormByte::Safe::SecureBinary::SecureBinary ( const ByteSize & count,
std::byte value )

Construct count bytes filled with value.

Parameters
countElement count.
valueFill byte.

◆ SecureBinary() [3/14]

StormByte::Safe::SecureBinary::SecureBinary ( const ByteSize & count)
explicit

Construct count zeroed bytes.

Parameters
countElement count.

◆ SecureBinary() [4/14]

StormByte::Safe::SecureBinary::SecureBinary ( std::span< const std::byte > bytes)
explicit

Copy bytes from a contiguous span.

Parameters
bytesSource view. Not owned and not wiped.

◆ SecureBinary() [5/14]

StormByte::Safe::SecureBinary::SecureBinary ( const std::byte * bytes,
const ByteSize & count )

Copy count bytes starting at bytes.

Parameters
bytesSource pointer. May be null when count is zero.
countByte count.
Exceptions
OutOfBoundsErrorbytes is null and count is not zero.

◆ SecureBinary() [6/14]

StormByte::Safe::SecureBinary::SecureBinary ( std::initializer_list< std::byte > list)

Copy from an initializer list.

Parameters
listSource bytes.

◆ SecureBinary() [7/14]

StormByte::Safe::SecureBinary::SecureBinary ( std::string_view text)
explicit

Copy character bytes from a string view.

No trailing NUL.

Parameters
textSource characters.

◆ SecureBinary() [8/14]

StormByte::Safe::SecureBinary::SecureBinary ( const char * text)
explicit

Copy character bytes from a C string.

No trailing NUL.

Parameters
textSource. A null pointer yields an empty sequence.

◆ SecureBinary() [9/14]

STORMBYTE_FORCE_INLINE StormByte::Safe::SecureBinary::SecureBinary ( const std::vector< std::byte > & bytes)
inlineexplicit

Copy bytes from a caller-owned vector.

The vector is unchanged.

Parameters
bytesSource.

◆ SecureBinary() [10/14]

STORMBYTE_FORCE_INLINE StormByte::Safe::SecureBinary::SecureBinary ( std::vector< std::byte > && bytes)
inlineexplicit

Copy bytes from a caller-owned vector, then zero and release it.

Parameters
bytesSource. Its bytes are zeroed before it is cleared. Reallocations the vector made earlier are not covered.

◆ SecureBinary() [11/14]

template<Type::ByteInputRange R>
StormByte::Safe::SecureBinary::SecureBinary ( const R & range)
explicit

Copy from an input range of byte-convertible values.

Template Parameters
RRange type satisfying Type::ByteInputRange.
Parameters
rangeSource range.

◆ SecureBinary() [12/14]

template<Type::ByteInputRange R>
StormByte::Safe::SecureBinary::SecureBinary ( R && range)
explicit

Consume an rvalue range.

Takes the block when R is an rvalue Binary or derived.

Template Parameters
RRange type satisfying Type::ByteInputRange.
Parameters
rangeSource range.

◆ SecureBinary() [13/14]

StormByte::Safe::SecureBinary::SecureBinary ( const SecureBinary & other)

Copy construct.

The copy is allocated once.

Parameters
otherSource sequence.

◆ SecureBinary() [14/14]

StormByte::Safe::SecureBinary::SecureBinary ( SecureBinary && other)
noexcept

Move construct.

other is left empty.

Parameters
otherSource sequence.

◆ ~SecureBinary()

StormByte::Safe::SecureBinary::~SecureBinary ( )
overridenoexcept

Zero the whole block, then release it.

Member Function Documentation

◆ Acquire()

void StormByte::Safe::SecureBinary::Acquire ( std::span< std::byte > block)
overrideprotectedvirtualnoexcept

Best effort: lock the pages of block in memory so they are not written to swap.

Parameters
blockBlock now owned by this object.

Reimplemented from StormByte::Safe::Binary.

◆ ConstantTimeCompare()

bool StormByte::Safe::SecureBinary::ConstantTimeCompare ( ) const
overrideprotectedvirtualnoexcept

Equality with this object never stops at the first difference.

Returns
Always true.

Reimplemented from StormByte::Safe::Binary.

◆ Discard()

void StormByte::Safe::SecureBinary::Discard ( std::span< std::byte > bytes)
overrideprotectedvirtualnoexcept

Zero bytes.

Parameters
bytesBytes being dropped.

Reimplemented from StormByte::Safe::Binary.

◆ HexDump() [1/2]

String StormByte::Safe::SecureBinary::HexDump ( ) const
delete

Not available: the dump would hold the secret in memory that is never wiped.

◆ HexDump() [2/2]

String StormByte::Safe::SecureBinary::HexDump ( Size columns) const
delete

Not available: the dump would hold the secret in memory that is never wiped.

Parameters
columnsUnused.

◆ operator std::vector< std::byte >() [1/2]

StormByte::Safe::SecureBinary::operator std::vector< std::byte > ( ) &&
explicitdelete

Not available: the vector would hold the secret in memory that is never wiped.

Use span().

◆ operator std::vector< std::byte >() [2/2]

StormByte::Safe::SecureBinary::operator std::vector< std::byte > ( ) const &
explicitdelete

Not available: the vector would hold the secret in memory that is never wiped.

Use span().

◆ operator=() [1/3]

SecureBinary & StormByte::Safe::SecureBinary::operator= ( const SecureBinary & other)

Copy assign.

Previous contents are zeroed.

Parameters
otherSource sequence.
Returns
This sequence.

◆ operator=() [2/3]

SecureBinary & StormByte::Safe::SecureBinary::operator= ( SecureBinary && other)
noexcept

Move assign.

The previous block is zeroed. other is left empty.

Parameters
otherSource sequence.
Returns
This sequence.

◆ operator=() [3/3]

SecureBinary & StormByte::Safe::SecureBinary::operator= ( std::initializer_list< std::byte > list)

Replace contents with an initializer list.

Previous contents are zeroed.

Parameters
listSource bytes.
Returns
This sequence.

◆ Release()

void StormByte::Safe::SecureBinary::Release ( std::span< std::byte > block)
overrideprotectedvirtualnoexcept

Unlock the pages of block once no other block on the same pages is locked.

Parameters
blockBlock no longer owned by this object.

Reimplemented from StormByte::Safe::Binary.


The documentation for this class was generated from the following file: