Secure memory block with allocator and cleanup. More...

Inheritance diagram for SecBlock< T, A >:

Public Types
typedef A::value_type	value_type

typedef A::pointer	iterator

typedef A::const_pointer	const_iterator

typedef A::size_type	size_type

Public Member Functions
	SecBlock (size_type size=0)
	Construct a SecBlock with space for size elements. More...

	SecBlock (const SecBlock< T, A > &t)
	Copy construct a SecBlock from another SecBlock. More...

	SecBlock (const T *ptr, size_type len)
	Construct a SecBlock from an array of elements. More...

	operator const void * () const
	Cast operator. More...

	operator void * ()
	Cast operator. More...

	operator const T * () const
	Cast operator. More...

	operator T* ()
	Cast operator. More...

iterator	begin ()
	Provides an iterator pointing to the first element in the memory block. More...

const_iterator	begin () const
	Provides a constant iterator pointing to the first element in the memory block. More...

iterator	end ()
	Provides an iterator pointing beyond the last element in the memory block. More...

const_iterator	end () const
	Provides a constant iterator pointing beyond the last element in the memory block. More...

A::pointer	data ()
	Provides a pointer to the first element in the memory block. More...

A::const_pointer	data () const
	Provides a pointer to the first element in the memory block. More...

size_type	size () const
	Provides the count of elements in the SecBlock. More...

bool	empty () const
	Determines if the SecBlock is empty. More...

byte *	BytePtr ()
	Provides a byte pointer to the first element in the memory block. More...

const byte *	BytePtr () const
	Return a byte pointer to the first element in the memory block. More...

size_type	SizeInBytes () const
	Provides the number of bytes in the SecBlock. More...

void	Assign (const T *ptr, size_type len)
	Set contents and size from an array. More...

void	Assign (size_type count, T value)
	Set contents from a value. More...

void	Assign (const SecBlock< T, A > &t)
	Copy contents from another SecBlock. More...

void	Append (const T *ptr, size_type len)
	Append contents from an array. More...

void	Append (const SecBlock< T, A > &t)
	Append contents from another SecBlock. More...

void	Append (size_type count, T value)
	Append contents from a value. More...

void	SetMark (size_t count)
	Sets the number of elements to zeroize. More...

SecBlock< T, A > &	operator= (const SecBlock< T, A > &t)
	Assign contents from another SecBlock. More...

SecBlock< T, A > &	operator+= (const SecBlock< T, A > &t)
	Append contents from another SecBlock. More...

SecBlock< T, A >	operator+ (const SecBlock< T, A > &t)
	Construct a SecBlock from this and another SecBlock. More...

bool	operator== (const SecBlock< T, A > &t) const
	Bitwise compare two SecBlocks. More...

bool	operator!= (const SecBlock< T, A > &t) const
	Bitwise compare two SecBlocks. More...

void	New (size_type newSize)
	Change size without preserving contents. More...

void	CleanNew (size_type newSize)
	Change size without preserving contents. More...

void	Grow (size_type newSize)
	Change size and preserve contents. More...

void	CleanGrow (size_type newSize)
	Change size and preserve contents. More...

void	resize (size_type newSize)
	Change size and preserve contents. More...

void	swap (SecBlock< T, A > &b)
	Swap contents with another SecBlock. More...

Static Public Attributes
static const size_type	ELEMS_MAX = ...
	Returns the maximum number of elements the block can hold. More...

Detailed Description

template<class T, class A = AllocatorWithCleanup<T>>
class SecBlock< T, A >

Secure memory block with allocator and cleanup.

Template Parameters

T	a class or type
A	AllocatorWithCleanup derived class for allocation and cleanup

See also: SecBlock on the Crypto++ wiki.

Since: Crypto++ 2.0

Definition at line 730 of file secblock.h.

Constructor & Destructor Documentation

◆ SecBlock() [1/3]

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::SecBlock ( size_type size = 0 )

inlineexplicit

Construct a SecBlock with space for size elements.

Parameters

size	the size of the allocation, in elements

Exceptions

std::bad_alloc

The elements are not initialized.

Since: Crypto++ 2.0

Note: size is the count of elements, and not the number of bytes

Definition at line 766 of file secblock.h.

◆ SecBlock() [2/3]

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::SecBlock ( const SecBlock< T, A > & t )

inline

Copy construct a SecBlock from another SecBlock.

Parameters

t	the other SecBlock

Exceptions

std::bad_alloc

Since: Crypto++ 2.0

Definition at line 773 of file secblock.h.

◆ SecBlock() [3/3]

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::SecBlock	(	const T *	ptr,
		size_type	len
	)

inline

Construct a SecBlock from an array of elements.

Parameters

ptr	a pointer to an array of T
len	the number of elements in the memory block

Exceptions

std::bad_alloc

If ptr!=NULL and len!=0, then the block is initialized from the pointer ptr. If ptr==NULL and len!=0, then the block is initialized to 0. Otherwise, the block is empty and not initialized.

Since: Crypto++ 2.0

Note: size is the count of elements, and not the number of bytes

Definition at line 789 of file secblock.h.

Member Function Documentation

◆ operator const void *()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::operator const void * ( ) const

inline

Cast operator.

Returns: block pointer cast to const void *

Since: Crypto++ 2.0

Definition at line 811 of file secblock.h.

◆ operator void *()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::operator void * ( )

inline

Cast operator.

Returns: block pointer cast to non-const void *

Since: Crypto++ 2.0

Definition at line 817 of file secblock.h.

◆ operator const T *()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::operator const T * ( ) const

inline

Cast operator.

Returns: block pointer cast to const T *

Since: Crypto++ 2.0

Definition at line 823 of file secblock.h.

◆ operator T*()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock< T, A >::operator T* ( )

inline

Cast operator.

Returns: block pointer cast to non-const T *

Since: Crypto++ 2.0

Definition at line 829 of file secblock.h.

◆ begin() [1/2]

template<class T , class A = AllocatorWithCleanup<T>>

iterator SecBlock< T, A >::begin ( )

inline

Provides an iterator pointing to the first element in the memory block.

Returns: iterator pointing to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 836 of file secblock.h.

◆ begin() [2/2]

template<class T , class A = AllocatorWithCleanup<T>>

const_iterator SecBlock< T, A >::begin ( ) const

inline

Provides a constant iterator pointing to the first element in the memory block.

Returns: constant iterator pointing to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 841 of file secblock.h.

◆ end() [1/2]

template<class T , class A = AllocatorWithCleanup<T>>

iterator SecBlock< T, A >::end ( )

inline

Provides an iterator pointing beyond the last element in the memory block.

Returns: iterator pointing beyond the last element in the memory block

Since: Crypto++ 2.0

Definition at line 846 of file secblock.h.

◆ end() [2/2]

template<class T , class A = AllocatorWithCleanup<T>>

const_iterator SecBlock< T, A >::end ( ) const

inline

Provides a constant iterator pointing beyond the last element in the memory block.

Returns: constant iterator pointing beyond the last element in the memory block

Since: Crypto++ 2.0

Definition at line 851 of file secblock.h.

◆ data() [1/2]

template<class T , class A = AllocatorWithCleanup<T>>

A::pointer SecBlock< T, A >::data ( )

inline

Provides a pointer to the first element in the memory block.

Returns: pointer to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 857 of file secblock.h.

◆ data() [2/2]

template<class T , class A = AllocatorWithCleanup<T>>

A::const_pointer SecBlock< T, A >::data ( ) const

inline

Provides a pointer to the first element in the memory block.

Returns: constant pointer to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 861 of file secblock.h.

◆ size()

template<class T , class A = AllocatorWithCleanup<T>>

size_type SecBlock< T, A >::size ( ) const

inline

Provides the count of elements in the SecBlock.

Returns: number of elements in the memory block

Note: the return value is the count of elements, and not the number of bytes

Since: Crypto++ 2.0

Definition at line 867 of file secblock.h.

◆ empty()

template<class T , class A = AllocatorWithCleanup<T>>

bool SecBlock< T, A >::empty ( ) const

inline

Determines if the SecBlock is empty.

Returns: true if number of elements in the memory block is 0, false otherwise

Since: Crypto++ 2.0

Definition at line 871 of file secblock.h.

◆ BytePtr() [1/2]

template<class T , class A = AllocatorWithCleanup<T>>

byte* SecBlock< T, A >::BytePtr ( )

inline

Provides a byte pointer to the first element in the memory block.

Returns: byte pointer to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 876 of file secblock.h.

◆ BytePtr() [2/2]

template<class T , class A = AllocatorWithCleanup<T>>

const byte* SecBlock< T, A >::BytePtr ( ) const

inline

Return a byte pointer to the first element in the memory block.

Returns: constant byte pointer to the first element in the memory block

Since: Crypto++ 2.0

Definition at line 880 of file secblock.h.

◆ SizeInBytes()

template<class T , class A = AllocatorWithCleanup<T>>

size_type SecBlock< T, A >::SizeInBytes ( ) const

inline

Provides the number of bytes in the SecBlock.

Returns: the number of bytes in the memory block

Note: the return value is the number of bytes, and not count of elements.

Since: Crypto++ 2.0

Definition at line 885 of file secblock.h.

◆ Assign() [1/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Assign	(	const T *	ptr,
		size_type	len
	)

inline

Set contents and size from an array.

Parameters

ptr	a pointer to an array of T
len	the number of elements in the memory block

The array pointed to by ptr must be distinct from this SecBlock because Assign() calls New() and then std::memcpy(). The call to New() will invalidate all pointers and iterators, like the pointer returned from data().

If the memory block is reduced in size, then the reclaimed memory is set to 0. If an assignment occurs, then Assign() resets the element count after the previous block is zeroized.

Since: Crypto++ 2.0

Definition at line 898 of file secblock.h.

◆ Assign() [2/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Assign	(	size_type	count,
		T	value
	)

inline

Set contents from a value.

Parameters

count	the number of values to copy
value	the value, repeated count times

If the memory block is reduced in size, then the reclaimed memory is set to 0. If an assignment occurs, then Assign() resets the element count after the previous block is zeroized.

Since: Crypto++ 6.0

Definition at line 913 of file secblock.h.

◆ Assign() [3/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Assign ( const SecBlock< T, A > & t )

inline

Copy contents from another SecBlock.

Parameters

t	the other SecBlock

Assign checks for self assignment.

If the memory block is reduced in size, then the reclaimed memory is set to 0. If an assignment occurs, then Assign() resets the element count after the previous block is zeroized.

Since: Crypto++ 2.0

Definition at line 928 of file secblock.h.

◆ Append() [1/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Append	(	const T *	ptr,
		size_type	len
	)

inline

Append contents from an array.

Parameters

ptr	a pointer to an array of T
len	the number of elements in the memory block

Exceptions

InvalidArgument if resulting size would overflow

The array pointed to by ptr must be distinct from this SecBlock because Append() calls Grow() and then std::memcpy(). The call to Grow() will invalidate all pointers and iterators, like the pointer returned from data().

Append() may be less efficient than a ByteQueue because Append() must Grow() the internal array and then copy elements. The ByteQueue can copy elements without growing.

See also: ByteQueue

Since: Crypto++ 8.6

Definition at line 952 of file secblock.h.

◆ Append() [2/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Append ( const SecBlock< T, A > & t )

inline

Append contents from another SecBlock.

Parameters

t	the other SecBlock

Exceptions

InvalidArgument if resulting size would overflow

Internally, this SecBlock calls Grow() and then appends t.

Append() may be less efficient than a ByteQueue because Append() must Grow() the internal array and then copy elements. The ByteQueue can copy elements without growing.

See also: ByteQueue

Since: Crypto++ 8.6

Definition at line 973 of file secblock.h.

◆ Append() [3/3]

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Append	(	size_type	count,
		T	value
	)

inline

Append contents from a value.

Parameters

count	the number of values to copy
value	the value, repeated count times

Exceptions

InvalidArgument if resulting size would overflow

Internally, this SecBlock calls Grow() and then appends value.

Append() may be less efficient than a ByteQueue because Append() must Grow() the internal array and then copy elements. The ByteQueue can copy elements without growing.

See also: ByteQueue

Since: Crypto++ 8.6

Definition at line 1004 of file secblock.h.

◆ SetMark()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::SetMark ( size_t count )

inline

Sets the number of elements to zeroize.

Parameters

count the number of elements

SetMark is a remediation for Issue 346/CVE-2016-9939 while preserving the streaming interface. The count controls the number of elements zeroized, which can be less than size or 0.

An internal variable, m_mark, is initialized to the maximum number of elements. The maximum number of elements is ELEMS_MAX. Deallocation triggers a zeroization, and the number of elements zeroized is STDMIN(m_size, m_mark). After zeroization, the memory is returned to the system.

The ASN.1 decoder uses SetMark() to set the element count to 0 before throwing an exception. In this case, the attacker provides a large BER encoded length (say 64MB) but only a small number of content octets (say 16). If the allocator zeroized all 64MB, then a transient DoS could occur as CPU cycles are spent zeroizing uninitialized memory.

Generally speaking, any operation which changes the size of the SecBlock results in the mark being reset to ELEMS_MAX. In particular, if Assign(), New(), Grow(), CleanNew(), CleanGrow() are called, then the count is reset to ELEMS_MAX. The list is not exhaustive.

Since: Crypto++ 6.0

See also: Issue 346/CVE-2016-9939

Definition at line 1037 of file secblock.h.

◆ operator=()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock<T, A>& SecBlock< T, A >::operator= ( const SecBlock< T, A > & t )

inline

Assign contents from another SecBlock.

Parameters

t	the other SecBlock

Returns: reference to this SecBlock

Internally, operator=() calls Assign().

If the memory block is reduced in size, then the reclaimed memory is set to 0. If an assignment occurs, then Assign() resets the element count after the previous block is zeroized.

Since: Crypto++ 2.0

Definition at line 1047 of file secblock.h.

◆ operator+=()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock<T, A>& SecBlock< T, A >::operator+= ( const SecBlock< T, A > & t )

inline

Append contents from another SecBlock.

Parameters

t	the other SecBlock

Returns: reference to this SecBlock

Internally, operator+=() calls Append().

Since: Crypto++ 2.0

Definition at line 1059 of file secblock.h.

◆ operator+()

template<class T , class A = AllocatorWithCleanup<T>>

SecBlock<T, A> SecBlock< T, A >::operator+ ( const SecBlock< T, A > & t )

inline

Construct a SecBlock from this and another SecBlock.

Parameters

t	the other SecBlock

Returns: a newly constructed SecBlock that is a concatenation of this and t.

Internally, a new SecBlock is created from this and a concatenation of t.

Since: Crypto++ 2.0

Definition at line 1073 of file secblock.h.

◆ operator==()

template<class T , class A = AllocatorWithCleanup<T>>

bool SecBlock< T, A >::operator== ( const SecBlock< T, A > & t ) const

inline

Bitwise compare two SecBlocks.

Parameters

t	the other SecBlock

Returns: true if the size and bits are equal, false otherwise

Uses a constant time compare if the arrays are equal size. The constant time compare is VerifyBufsEqual() found in misc.h.

See also: operator!=()

Since: Crypto++ 2.0

Definition at line 1095 of file secblock.h.

◆ operator!=()

template<class T , class A = AllocatorWithCleanup<T>>

bool SecBlock< T, A >::operator!= ( const SecBlock< T, A > & t ) const

inline

Bitwise compare two SecBlocks.

Parameters

t	the other SecBlock

Returns: true if the size and bits are equal, false otherwise

Uses a constant time compare if the arrays are equal size. The constant time compare is VerifyBufsEqual() found in misc.h.

Internally, operator!=() returns the inverse of operator==().

See also: operator==()

Since: Crypto++ 2.0

Definition at line 1111 of file secblock.h.

◆ New()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::New ( size_type newSize )

inline

Change size without preserving contents.

Parameters

newSize the new size of the memory block

Old content is not preserved. If the memory block is reduced in size, then the reclaimed content is set to 0. If the memory block grows in size, then the new memory is initialized to 0. New() resets the element count after the previous block is zeroized.

Internally, this SecBlock calls reallocate().

See also: New(), CleanNew(), Grow(), CleanGrow(), resize()

Since: Crypto++ 2.0

Definition at line 1126 of file secblock.h.

◆ CleanNew()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::CleanNew ( size_type newSize )

inline

Change size without preserving contents.

Parameters

newSize the new size of the memory block

Old content is not preserved. If the memory block is reduced in size, then the reclaimed content is set to 0. If the memory block grows in size, then the new memory is initialized to 0. CleanNew() resets the element count after the previous block is zeroized.

Internally, this SecBlock calls New().

See also: New(), CleanNew(), Grow(), CleanGrow(), resize()

Since: Crypto++ 2.0

Definition at line 1143 of file secblock.h.

◆ Grow()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::Grow ( size_type newSize )

inline

Change size and preserve contents.

Parameters

newSize the new size of the memory block

Old content is preserved. New content is not initialized.

Internally, this SecBlock calls reallocate() when size must increase. If the size does not increase, then CleanGrow() does not take action. If the size must change, then use resize(). CleanGrow() resets the element count after the previous block is zeroized.

See also: New(), CleanNew(), Grow(), CleanGrow(), resize(); New(), CleanNew(), Grow(), CleanGrow(), resize()

Since: Crypto++ 2.0

Definition at line 1160 of file secblock.h.

◆ CleanGrow()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::CleanGrow ( size_type newSize )

inline

Change size and preserve contents.

Parameters

newSize the new size of the memory block

Old content is preserved. New content is initialized to 0.

Internally, this SecBlock calls reallocate() when size must increase. If the size does not increase, then CleanGrow() does not take action. If the size must change, then use resize(). CleanGrow() resets the element count after the previous block is zeroized.

See also: New(), CleanNew(), Grow(), CleanGrow(), resize()

Since: Crypto++ 2.0

Definition at line 1179 of file secblock.h.

◆ resize()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::resize ( size_type newSize )

inline

Change size and preserve contents.

Parameters

newSize the new size of the memory block

Old content is preserved. If the memory block grows in size, then new memory is not initialized. resize() resets the element count after the previous block is zeroized.

Internally, this SecBlock calls reallocate().

See also: New(), CleanNew(), Grow(), CleanGrow(), resize()

Since: Crypto++ 2.0

Definition at line 1198 of file secblock.h.

◆ swap()

template<class T , class A = AllocatorWithCleanup<T>>

void SecBlock< T, A >::swap ( SecBlock< T, A > & b )

inline

Swap contents with another SecBlock.

Parameters

b	the other SecBlock

Internally, std::swap() is called on m_alloc, m_size and m_ptr.

Since: Crypto++ 2.0

Definition at line 1209 of file secblock.h.

Member Data Documentation

◆ ELEMS_MAX

template<class T , class A = AllocatorWithCleanup<T>>

const size_type SecBlock< T, A >::ELEMS_MAX = ...

static

Returns the maximum number of elements the block can hold.

ELEMS_MAX is the maximum number of elements the SecBlock can hold. The value of ELEMS_MAX is SIZE_MAX/sizeof(T). std::numeric_limits was avoided due to lack of constexpr-ness in C++03 and below.

Note: In C++03 and below ELEMS_MAX is a static data member of type size_type. In C++11 and above ELEMS_MAX is an enum inheriting from size_type. In both cases ELEMS_MAX can be used before objects are fully constructed, and it does not suffer the limitations of class methods like max_size.

See also: Issue 346/CVE-2016-9939

Since: Crypto++ 6.0

Definition at line 751 of file secblock.h.

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

secblock.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

template<class T, class A = AllocatorWithCleanup<T>> class SecBlock< T, A >

Constructor & Destructor Documentation

◆ SecBlock() [1/3]

◆ SecBlock() [2/3]

◆ SecBlock() [3/3]

Member Function Documentation

◆ operator const void *()

◆ operator void *()

◆ operator const T *()

◆ operator T*()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ data() [1/2]

◆ data() [2/2]

◆ size()

◆ empty()

◆ BytePtr() [1/2]

◆ BytePtr() [2/2]

◆ SizeInBytes()

◆ Assign() [1/3]

◆ Assign() [2/3]

◆ Assign() [3/3]

◆ Append() [1/3]

◆ Append() [2/3]

◆ Append() [3/3]

◆ SetMark()

◆ operator=()

◆ operator+=()

◆ operator+()

◆ operator==()

◆ operator!=()

◆ New()

◆ CleanNew()

◆ Grow()

◆ CleanGrow()

◆ resize()

◆ swap()

Member Data Documentation

◆ ELEMS_MAX

template<class T, class A = AllocatorWithCleanup<T>>
class SecBlock< T, A >