DiceKeys Seeded Cryptography Library
SodiumBuffer Class Reference

A byte array containing a length and a pointer to memory (the data field), which ensures data is erased (replaced with zeros) before the memory it occupies is released for re-use by other objects. More...

#include <sodium-buffer.hpp>

Public Member Functions

 SodiumBuffer (size_t length=0, const unsigned char *bufferData=NULL)
 Construct a new SodiumBuffer by specifying its length and optionally specifying a pointer to a buffer of that length or greater. More...
 
 SodiumBuffer (const std::vector< unsigned char > &bufferData)
 Construct a SodiumBuffer by copying the length and data of an array of bytes.
 
 SodiumBuffer (const SodiumBuffer &other)
 Construct a new SodiumBuffer by copying another SodiumBuffer. More...
 
 SodiumBuffer (const std::string str)
 
const std::vector< SodiumBuffersplitFixedLengthList (int count) const
 Deserialize a fixed-length list of SodiumBuffers that had been serialized to a single buffer via a call to the static combineFixedLengthList method. More...
 
 ~SodiumBuffer ()
 Destroy the SodiumBuffer object, freeing and zero-ing the buffer.
 
const std::vector< unsigned char > toVector () const
 Copy the buffer into a byte vector, which by nature of being a standard library class will be stored in a region of memory that is not guaranteed to be erased when the object is destroyed. More...
 
const std::string toUtf8String () const
 If the data in the buffer represents a UTF8-format string, reconstitute the data back into a UTF8 std::string. Note that the result will be in a region of memor that is not guaranteed to be erased when the object is destroyed.
 
const std::string toHexString () const
 Convert the data in the buffer to a lowercase hex string, which by nature of being stored in a string will be in a region of memory that is not guaranteed to be erased when the object is destroyed. More...
 

Static Public Member Functions

static const SodiumBuffer combineFixedLengthList (const std::vector< const SodiumBuffer * > &buffers)
 Create a new SodiumBuffer that stored a fixed-length array of other $n$ other sodium buffers. More...
 
static SodiumBuffer fromHexString (const std::string &hexStr)
 Create a SodiumBuffer from a string of hex digits. More...
 

Public Attributes

unsigned char * data
 A pointer to the buffer of bytes. More...
 
const size_t length
 The length of the buffer. More...
 

Detailed Description

A byte array containing a length and a pointer to memory (the data field), which ensures data is erased (replaced with zeros) before the memory it occupies is released for re-use by other objects.

Built on top of sodium_malloc and sodium_free from LibSodium.

Note: while this class exists to serve a security function, in that it provides memory that will be erased before re-use, it does not serve all security functions. Specifically, it cannot:

  1. guarantee if or when the object will be de-allocated an memory erased
  2. and it does not provide any bounds-checked operations. (though that feature should be on the to-do list.)

Constructor & Destructor Documentation

◆ SodiumBuffer() [1/3]

SodiumBuffer::SodiumBuffer ( size_t  length = 0,
const unsigned char *  bufferData = NULL 
)

Construct a new SodiumBuffer by specifying its length and optionally specifying a pointer to a buffer of that length or greater.

Parameters
lengthThe number of bytes to allocate to the buffer
bufferDataAn optional pointer to data to copy, which must be at least length bytes long.

◆ SodiumBuffer() [2/3]

SodiumBuffer::SodiumBuffer ( const SodiumBuffer other)

Construct a new SodiumBuffer by copying another SodiumBuffer.

Parameters
other

◆ SodiumBuffer() [3/3]

SodiumBuffer::SodiumBuffer ( const std::string  str)

Construct a buffer that stores a string

Member Function Documentation

◆ combineFixedLengthList()

const SodiumBuffer SodiumBuffer::combineFixedLengthList ( const std::vector< const SodiumBuffer * > &  buffers)
static

Create a new SodiumBuffer that stored a fixed-length array of other $n$ other sodium buffers.

Each of the first $n_-1$ buffers is preceded by a four-byte big-endian length field. The length of the final field is the number of bytes remaining in the resulting SodiumBuffer (it is implicit since SodiumBuffer objects track their total length).

Parameters
buffersA vector of pointers to SodiumBuffer objects. You may pass null pointers which will create fields of zero bytes in length. (They will be de-serialized as zero-length SodiumBuffer objects).

This is handy for serializing objects with a fixed set of members that can be serialized into SodiumBuffer objects (e.g. byte arrays & strings).

◆ fromHexString()

SodiumBuffer SodiumBuffer::fromHexString ( const std::string &  hexStr)
static

Create a SodiumBuffer from a string of hex digits.

Parameters
hexStrA string of hex digits, optionally preceeded by the two-character hex-string signifier "0x".
Returns
SodiumBuffer A buffer of bytes reconstituted from hexStr

◆ splitFixedLengthList()

const std::vector< SodiumBuffer > SodiumBuffer::splitFixedLengthList ( int  count) const

Deserialize a fixed-length list of SodiumBuffers that had been serialized to a single buffer via a call to the static combineFixedLengthList method.

The result is a vector of SodiumBuffers.

Parameters
countThe number of buffers in the list that was combined to form this SodiumBuffer
Returns
const std::vector<SodiumBuffer> The list of SodiumBuffer objects that were combined into a list when this SodiumBuffer was constructed via combineFixedLengthList.

◆ toHexString()

const std::string SodiumBuffer::toHexString ( ) const

Convert the data in the buffer to a lowercase hex string, which by nature of being stored in a string will be in a region of memory that is not guaranteed to be erased when the object is destroyed.

Returns
const std::vector<unsigned char> A copy of the data in the SodiumBuffer

◆ toVector()

const std::vector< unsigned char > SodiumBuffer::toVector ( ) const

Copy the buffer into a byte vector, which by nature of being a standard library class will be stored in a region of memory that is not guaranteed to be erased when the object is destroyed.

Returns
const std::vector<unsigned char> A copy of the data in the SodiumBuffer

Member Data Documentation

◆ data

unsigned char* SodiumBuffer::data

A pointer to the buffer of bytes.

◆ length

const size_t SodiumBuffer::length

The length of the buffer.


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