Crypto++  5.6.5
Free C++ class library of cryptographic schemes
Public Types | Public Member Functions | Public Attributes | List of all members
SecBlock< T, A > Class Template Reference

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
 
 operator void * ()
 
 operator const T * () const
 
 operator T* ()
 
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 SetMark (size_t count)
 Sets the number of elements to zeroize. More...
 
void Assign (const T *ptr, size_type len)
 Set contents and size from an array. More...
 
void Assign (const SecBlock< T, A > &t)
 Copy contents from another SecBlock. 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...
 

Public Attributes

m_alloc
 
size_type m_mark
 
size_type m_size
 
T * m_ptr
 

Detailed Description

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

Secure memory block with allocator and cleanup.

Template Parameters
Ta class or type
AAllocatorWithCleanup derived class for allocation and cleanup

Definition at line 483 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
sizethe size of the allocation, in elements
Exceptions
std::bad_alloc

The elements are not initialized.

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

Definition at line 496 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
tthe other SecBlock
Exceptions
std::bad_alloc

Definition at line 502 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
ptra pointer to an array of T
lenthe 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.

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

Definition at line 516 of file secblock.h.

Member Function Documentation

◆ 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

Definition at line 545 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

Definition at line 549 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

Definition at line 553 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

Definition at line 557 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

Definition at line 562 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

Definition at line 565 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

Definition at line 570 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

Definition at line 573 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

Definition at line 577 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

Definition at line 580 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.

Definition at line 584 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
countthe 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. 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 unintialized memory.

If Assign(), New(), Grow(), CleanNew(), CleanGrow() are called, then the count is reset to its default state, which is the maxmimum number of elements.

Since
Crypto++ 6.0

Definition at line 603 of file secblock.h.

◆ Assign() [1/2]

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
ptra pointer to an array of T
lenthe number of elements in the memory block

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

Definition at line 610 of file secblock.h.

◆ Assign() [2/2]

template<class T, class A = AllocatorWithCleanup<T>>
void SecBlock< T, A >::Assign ( const SecBlock< T, A > &  t)
inline

Copy contents from another SecBlock.

Parameters
tthe 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.

Definition at line 623 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
tthe other 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.

Definition at line 639 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
tthe other SecBlock

Internally, this SecBlock calls Grow and then appends t.

Definition at line 649 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
tthe other SecBlock
Returns
a newly constructed SecBlock that is a conacentation of this and t

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

Definition at line 673 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
tthe 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!=()

Definition at line 691 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
tthe 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==()

Definition at line 704 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
newSizethe new size of the memory block

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

Internally, this SecBlock calls reallocate().

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

Definition at line 717 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
newSizethe 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()

Definition at line 732 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
newSizethe 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 Grow() does not take action. If the size must change, then use resize(). Grow() resets the element count after the previous block is zeroized.

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

Definition at line 746 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
newSizethe 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()

Definition at line 764 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
newSizethe 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()

Definition at line 782 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
bthe other SecBlock

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

Definition at line 792 of file secblock.h.


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