Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY > Class Template Reference

Alignment buffer helper. More...

#include <alignment_buffer.h>

Public Member Functions
std::tuple< std::span< const uint8_t >, size_t >	aligned_data_to_process (BufferSlicer &slicer) const
	AlignmentBuffer ()
	AlignmentBuffer (AlignmentBuffer &&other) noexcept=default
	AlignmentBuffer (const AlignmentBuffer &other)=default
void	append (std::span< const T > elements)
void	clear ()
std::span< const T >	consume ()
std::span< const T >	consume_partial ()
constexpr bool	defers_final_block () const
std::span< T >	directly_modify_first (size_t elements)
std::span< T >	directly_modify_last (size_t elements)
size_t	elements_in_buffer () const
size_t	elements_until_alignment () const
void	fill_up_with_zeros ()
std::optional< std::span< const T > >	handle_unaligned_data (BufferSlicer &slicer)
bool	in_alignment () const
std::optional< std::span< const uint8_t > >	next_aligned_block_to_process (BufferSlicer &slicer) const
AlignmentBuffer &	operator= (AlignmentBuffer &&other) noexcept=default
AlignmentBuffer &	operator= (const AlignmentBuffer &other)=default
bool	ready_to_consume () const
constexpr size_t	size () const
	~AlignmentBuffer ()

Detailed Description

template<typename T, size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>
requires (BLOCK_SIZE > 0)
class Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >

Alignment buffer helper.

Many algorithms have an intrinsic block size in which they consume input data. When streaming arbitrary data chunks to such algorithms we must store some data intermittently to honor the algorithm's alignment requirements.

This helper encapsulates such an alignment buffer. The API of this class is designed to minimize user errors in the algorithm implementations. Therefore, it is strongly opinionated on its use case. Don't try to use it for anything but the described circumstance.

Template Parameters

T	the element type of the internal buffer
BLOCK_SIZE	the buffer size to use for the alignment buffer
FINAL_BLOCK_STRATEGY	defines whether the final input data block is retained in handle_unaligned_data() and must be manually consumed

Definition at line 61 of file alignment_buffer.h.

Constructor & Destructor Documentation

AlignmentBuffer() [1/3]

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::AlignmentBuffer ( )

inline

Definition at line 63 of file alignment_buffer.h.

: m_position(0) {}

~AlignmentBuffer()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::~AlignmentBuffer ( )

inline

Definition at line 65 of file alignment_buffer.h.

{ secure_scrub_memory(m_buffer.data(), m_buffer.size()); }

References Botan::secure_scrub_memory().

AlignmentBuffer() [2/3]

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::AlignmentBuffer ( const AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY > & other )

default

AlignmentBuffer() [3/3]

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::AlignmentBuffer ( AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY > && other )

defaultnoexcept

Member Function Documentation

aligned_data_to_process()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::tuple< std::span< const uint8_t >, size_t > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::aligned_data_to_process ( BufferSlicer & slicer ) const

inlinenodiscard

Once the buffer reached alignment, this can be used to consume as many input bytes from the given slider as possible. The output always contains data elements that are a multiple of the intrinsic block size.

Returns

a view onto the aligned data from slicer and the number of full blocks that are represented by this view.

Definition at line 127 of file alignment_buffer.h.

                                                                                                                 {
         BOTAN_ASSERT_NOMSG(in_alignment());
 
         // When the final block is to be deferred, the last block must not be
         // selected for processing if there is no (unaligned) extra input data.
         const size_t defer = (defers_final_block()) ? 1 : 0;
         const size_t full_blocks_to_process = (slicer.remaining() - defer) / m_buffer.size();
         return {slicer.take(full_blocks_to_process * m_buffer.size()), full_blocks_to_process};
      }

References BOTAN_ASSERT_NOMSG, Botan::BufferSlicer::remaining(), and Botan::BufferSlicer::take().

Referenced by Botan::BLAKE2b::add_data(), and Botan::MerkleDamgard_Hash< MD >::update().

append()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

void Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::append ( std::span< const T > elements )

inline

Appends the provided elements to the buffer. The user has to make sure that elements fits in the remaining capacity of the buffer.

Definition at line 91 of file alignment_buffer.h.

                                             {
         BOTAN_ASSERT_NOMSG(elements.size() <= elements_until_alignment());
         std::copy(elements.begin(), elements.end(), m_buffer.begin() + m_position);
         m_position += elements.size();
      }

References BOTAN_ASSERT_NOMSG.

Referenced by Botan::Streebog::final_result().

clear()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

void Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::clear ( )

inline

Definition at line 72 of file alignment_buffer.h.

                   {
         clear_mem(m_buffer.data(), m_buffer.size());
         m_position = 0;
      }

References Botan::clear_mem().

Referenced by Botan::BLAKE2b::clear(), Botan::GMAC::clear(), Botan::GOST_34_11::clear(), Botan::MerkleDamgard_Hash< MD >::clear(), Botan::Poly1305::clear(), Botan::Skein_512::clear(), and Botan::Streebog::clear().

consume()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::span< const T > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::consume ( )

inlinenodiscard

Explicitly consume the currently collected block. It is the caller's responsibility to ensure that the buffer is filled fully. After consumption, the buffer is cleared and ready to collect new data.

Definition at line 201 of file alignment_buffer.h.

                                               {
         BOTAN_ASSERT_NOMSG(ready_to_consume());
         m_position = 0;
         return m_buffer;
      }

References BOTAN_ASSERT_NOMSG.

Referenced by Botan::BLAKE2b::final_result(), and Botan::Streebog::final_result().

consume_partial()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::span< const T > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::consume_partial ( )

inlinenodiscard

Explicitly consumes however many bytes are currently stored in the buffer. After consumption, the buffer is cleared and ready to collect new data.

Definition at line 212 of file alignment_buffer.h.

                                                       {
         const auto elements = elements_in_buffer();
         m_position = 0;
         return std::span(m_buffer).first(elements);
      }

defers_final_block()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

bool Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::defers_final_block ( ) const

inlineconstexpr

Definition at line 234 of file alignment_buffer.h.

                                                {
         return FINAL_BLOCK_STRATEGY == AlignmentBufferFinalBlock::must_be_deferred;
      }

References Botan::must_be_deferred.

directly_modify_first()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::span< T > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::directly_modify_first ( size_t elements )

inline

Allows direct modification of the first elements in the buffer. This is a low-level accessor that neither takes the buffer's current capacity into account nor does it change the internal cursor. Beware not to overwrite unconsumed bytes.

Definition at line 103 of file alignment_buffer.h.

                                                        {
         BOTAN_ASSERT_NOMSG(size() >= elements);
         return std::span(m_buffer).first(elements);
      }

References BOTAN_ASSERT_NOMSG.

Referenced by Botan::Streebog::final_result().

directly_modify_last()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::span< T > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::directly_modify_last ( size_t elements )

inline

Allows direct modification of the last elements in the buffer. This is a low-level accessor that neither takes the buffer's current capacity into account nor does it change the internal cursor. Beware not to overwrite unconsumed bytes.

Definition at line 114 of file alignment_buffer.h.

                                                       {
         BOTAN_ASSERT_NOMSG(size() >= elements);
         return std::span(m_buffer).last(elements);
      }

References BOTAN_ASSERT_NOMSG.

elements_in_buffer()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

size_t Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::elements_in_buffer ( ) const

inline

Definition at line 220 of file alignment_buffer.h.

{ return m_position; }

Referenced by Botan::BLAKE2b::final_result(), and Botan::Streebog::final_result().

elements_until_alignment()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

size_t Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::elements_until_alignment ( ) const

inline

Definition at line 222 of file alignment_buffer.h.

{ return m_buffer.size() - m_position; }

fill_up_with_zeros()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

void Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::fill_up_with_zeros ( )

inline

Fills the currently unused bytes of the buffer with zero bytes

Definition at line 80 of file alignment_buffer.h.

                                {
         if(!ready_to_consume()) {
            clear_mem(&m_buffer[m_position], elements_until_alignment());
            m_position = m_buffer.size();
         }
      }

References Botan::clear_mem().

Referenced by Botan::BLAKE2b::final_result(), and Botan::Streebog::final_result().

handle_unaligned_data()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::optional< std::span< const T > > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::handle_unaligned_data ( BufferSlicer & slicer )

inlinenodiscard

Intermittently buffers potentially unaligned data provided in slicer. If the internal buffer already contains some elements, data is appended. Once a full block is collected, it is returned to the caller for processing.

Parameters

slicer

the input data source to be (partially) consumed

Returns

a view onto a full block once enough data was collected, or std::nullopt if no full block is available yet

Definition at line 167 of file alignment_buffer.h.

                                                                                              {
         // When the final block is to be deferred, we would need to store and
         // hold a buffer that contains exactly one block until more data is
         // passed or it is explicitly consumed.
         const size_t defer = (defers_final_block()) ? 1 : 0;
 
         if(in_alignment() && slicer.remaining() >= m_buffer.size() + defer) {
            // We are currently in alignment and the passed-in data source
            // contains enough data to benefit from aligned processing.
            // Therefore, we don't copy anything into the intermittent buffer.
            return std::nullopt;
         }
 
         // Fill the buffer with as much input data as needed to reach alignment
         // or until the input source is depleted.
         const auto elements_to_consume = std::min(m_buffer.size() - m_position, slicer.remaining());
         append(slicer.take(elements_to_consume));
 
         // If we collected enough data, we push out one full block. When
         // deferring the final block is enabled, we additionally check that
         // more input data is available to continue processing a consecutive
         // block.
         if(ready_to_consume() && (!defers_final_block() || !slicer.empty())) {
            return consume();
         } else {
            return std::nullopt;
         }
      }

References Botan::BufferSlicer::empty(), Botan::BufferSlicer::remaining(), and Botan::BufferSlicer::take().

Referenced by Botan::BLAKE2b::add_data(), Botan::Streebog::add_data(), and Botan::MerkleDamgard_Hash< MD >::update().

in_alignment()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

bool Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::in_alignment ( ) const

inline

Returns

true if the buffer is empty (i.e. contains no unaligned data)

Definition at line 227 of file alignment_buffer.h.

{ return m_position == 0; }

Referenced by Botan::BLAKE2b::add_data(), Botan::Streebog::add_data(), and Botan::MerkleDamgard_Hash< MD >::update().

next_aligned_block_to_process()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

std::optional< std::span< const uint8_t > > Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::next_aligned_block_to_process ( BufferSlicer & slicer ) const

inlinenodiscard

Once the buffer reached alignment, this can be used to consume full blocks from the input data represented by slicer.

Returns

a view onto the next full block from slicer or std::nullopt if not enough data is available in slicer.

Definition at line 144 of file alignment_buffer.h.

                                                                                                                  {
         BOTAN_ASSERT_NOMSG(in_alignment());
 
         // When the final block is to be deferred, the last block must not be
         // selected for processing if there is no (unaligned) extra input data.
         const size_t defer = (defers_final_block()) ? 1 : 0;
         if(slicer.remaining() < m_buffer.size() + defer) {
            return std::nullopt;
         }
 
         return slicer.take(m_buffer.size());
      }

References BOTAN_ASSERT_NOMSG, Botan::BufferSlicer::remaining(), and Botan::BufferSlicer::take().

Referenced by Botan::Streebog::add_data().

operator=() [1/2]

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

AlignmentBuffer & Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::operator= ( AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY > && other )

defaultnoexcept

operator=() [2/2]

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

AlignmentBuffer & Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::operator= ( const AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY > & other )

default

ready_to_consume()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

bool Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::ready_to_consume ( ) const

inline

Returns

true if the buffer is full (i.e. a block is ready to be consumed)

Definition at line 232 of file alignment_buffer.h.

{ return m_position == m_buffer.size(); }

size()

template<typename T , size_t BLOCK_SIZE, AlignmentBufferFinalBlock FINAL_BLOCK_STRATEGY = AlignmentBufferFinalBlock::is_not_special>

size_t Botan::AlignmentBuffer< T, BLOCK_SIZE, FINAL_BLOCK_STRATEGY >::size ( ) const

inlineconstexpr

Definition at line 218 of file alignment_buffer.h.

{ return m_buffer.size(); }

Referenced by Botan::BLAKE2b::key_schedule().

---

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

• src/lib/utils/alignment_buffer.h