Crypto++ 8.1 Free C++ class library of cryptographic schemes

Public Types | Public Member Functions | Static 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 (size_type count, T value)
| Set contents from a value. 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...

## 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

Definition at line 688 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` | ) |
| inline explicit

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.

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

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

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

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

Definition at line 743 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 772 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 776 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 780 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 784 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 789 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 792 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 797 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 800 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 804 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 807 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 811 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 unintialized 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 834 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

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 841 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. Assign() resets the element count after the previous block is zeroized.

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

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

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 886 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

Internally, this SecBlock calls Grow and then appends t.

Definition at line 896 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 conacentation of this and t

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

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

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

Definition at line 952 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 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 965 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()

Definition at line 980 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 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 995 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()

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

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

Definition at line 1041 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 709 of file secblock.h.

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

- secblock.h