From 0c82df181c98912a01b00bed298b567724feafba Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Sat, 31 Aug 2019 07:46:19 -0400 Subject: [PATCH] Update documentation --- secblock.h | 329 ++++++++++++++++++++++++++++------------------------- 1 file changed, 174 insertions(+), 155 deletions(-) diff --git a/secblock.h b/secblock.h index af1d96f0..361fb94c 100644 --- a/secblock.h +++ b/secblock.h @@ -43,14 +43,14 @@ public: /// \brief Returns the maximum number of elements the allocator can provide /// \details ELEMS_MAX is the maximum number of elements the - /// Allocator can provide. 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. + /// Allocator can provide. 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. + /// 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. /// \sa Issue 346/CVE-2016-9939 /// \since Crypto++ 6.0 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) @@ -66,15 +66,15 @@ public: /// \brief Returns the maximum number of elements the allocator can provide /// \returns the maximum number of elements the allocator can provide /// \details Internally, preprocessor macros are used rather than std::numeric_limits - /// because the latter is not a constexpr. Some compilers, like Clang, do not - /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear - /// to optimize it well in either form. + /// because the latter is not a constexpr. Some compilers, like Clang, do not + /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear + /// to optimize it well in either form. CRYPTOPP_CONSTEXPR size_type max_size() const {return ELEMS_MAX;} #if defined(__SUNPRO_CC) // https://github.com/weidai11/cryptopp/issues/770 // and https://stackoverflow.com/q/53999461/608639 - CRYPTOPP_CONSTEXPR size_type max_size(size_type n) const {return (~(size_type)0)/n;} + CRYPTOPP_CONSTEXPR size_type max_size(size_type n) const {return SIZE_MAX/n;} #endif #if defined(CRYPTOPP_CXX11_VARIADIC_TEMPLATES) || defined(CRYPTOPP_DOXYGEN_PROCESSING) @@ -85,14 +85,14 @@ public: /// \param ptr pointer to type V /// \param args variadic arguments /// \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES - /// is defined. The define is controlled by compiler versions detected in config.h. + /// is defined. The define is controlled by compiler versions detected in config.h. template void construct(V* ptr, Args&&... args) {::new ((void*)ptr) V(std::forward(args)...);} /// \brief Destroys an V constructed with variadic arguments /// \tparam V the type to be forwarded /// \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES - /// is defined. The define is controlled by compiler versions detected in config.h. + /// is defined. The define is controlled by compiler versions detected in config.h. template void destroy(V* ptr) {if (ptr) ptr->~V();} @@ -105,15 +105,15 @@ protected: /// \throws InvalidArgument /// \details CheckSize verifies the number of elements requested is valid. /// \details If size is greater than max_size(), then InvalidArgument is thrown. - /// The library throws InvalidArgument if the size is too large to satisfy. + /// The library throws InvalidArgument if the size is too large to satisfy. /// \details Internally, preprocessor macros are used rather than std::numeric_limits - /// because the latter is not a constexpr. Some compilers, like Clang, do not - /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear - /// to optimize it well in either form. + /// because the latter is not a constexpr. Some compilers, like Clang, do not + /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear + /// to optimize it well in either form. /// \details The sizeof(T) != 1 in the condition attempts to help the - /// compiler optimize the check for byte types. Coverity findings for - /// CONSTANT_EXPRESSION_RESULT were generated without it. For byte types, - /// size never exceeded ELEMS_MAX but the code was not removed. + /// compiler optimize the check for byte types. Coverity findings for + /// CONSTANT_EXPRESSION_RESULT were generated without it. For byte types, + /// size never exceeded ELEMS_MAX but the code was not removed. /// \note size is the count of elements, and not the number of bytes static void CheckSize(size_t size) { @@ -143,7 +143,7 @@ typedef typename AllocatorBase::const_reference const_reference; /// \param newSize the new, requested size /// \param preserve flag that indicates if the old allocation should be preserved /// \note oldSize and newSize are the count of elements, and not the -/// number of bytes. +/// number of bytes. template typename A::pointer StandardReallocate(A& alloc, T *oldPtr, typename A::size_type oldSize, typename A::size_type newSize, bool preserve) { @@ -171,10 +171,10 @@ typename A::pointer StandardReallocate(A& alloc, T *oldPtr, typename A::size_typ /// \tparam T class or type /// \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary /// \details If T_Align16 is true, then AllocatorWithCleanup calls AlignedAllocate() -/// for memory allocations. If T_Align16 is false, then AllocatorWithCleanup() calls -/// UnalignedAllocate() for memory allocations. +/// for memory allocations. If T_Align16 is false, then AllocatorWithCleanup() calls +/// UnalignedAllocate() for memory allocations. /// \details Template parameter T_Align16 is effectively controlled by cryptlib.h and mirrors -/// CRYPTOPP_BOOL_ALIGN16. CRYPTOPP_BOOL_ALIGN16 is often used as the template parameter. +/// CRYPTOPP_BOOL_ALIGN16. CRYPTOPP_BOOL_ALIGN16 is often used as the template parameter. template class AllocatorWithCleanup : public AllocatorBase { @@ -187,14 +187,14 @@ public: /// \returns a memory block /// \throws InvalidArgument /// \details allocate() first checks the size of the request. If it is non-0 - /// and less than max_size(), then an attempt is made to fulfill the request using either - /// AlignedAllocate() or UnalignedAllocate(). + /// and less than max_size(), then an attempt is made to fulfill the request using either + /// AlignedAllocate() or UnalignedAllocate(). /// \details AlignedAllocate() is used if T_Align16 is true. - /// UnalignedAllocate() used if T_Align16 is false. + /// UnalignedAllocate() used if T_Align16 is false. /// \details This is the C++ *Placement New* operator. ptr is not used, and the function - /// CRYPTOPP_ASSERTs in Debug builds if ptr is non-NULL. + /// CRYPTOPP_ASSERTs in Debug builds if ptr is non-NULL. /// \sa CallNewHandler() for the methods used to recover from a failed - /// allocation attempt. + /// allocation attempt. /// \note size is the count of elements, and not the number of bytes pointer allocate(size_type size, const void *ptr = NULLPTR) { @@ -216,14 +216,14 @@ public: /// \param ptr the pointer for the allocation /// \param size the size of the allocation, in elements /// \details Internally, SecureWipeArray() is called before deallocating the memory. - /// Once the memory block is wiped or zeroized, AlignedDeallocate() or - /// UnalignedDeallocate() is called. + /// Once the memory block is wiped or zeroized, AlignedDeallocate() or + /// UnalignedDeallocate() is called. /// \details AlignedDeallocate() is used if T_Align16 is true. - /// UnalignedDeallocate() used if T_Align16 is false. + /// UnalignedDeallocate() used if T_Align16 is false. void deallocate(void *ptr, size_type size) { // This will fire if SetMark(0) was called in the SecBlock - // Our self tests exercise it, disable it now. + // Our self tests exercise it, disable it now. // CRYPTOPP_ASSERT((ptr && size) || !(ptr || size)); SecureWipeArray(reinterpret_cast(ptr), size); @@ -243,11 +243,11 @@ public: /// \returns pointer to the new memory block /// \details Internally, reallocate() calls StandardReallocate(). /// \details If preserve is true, then index 0 is used to begin copying the - /// old memory block to the new one. If the block grows, then the old array - /// is copied in its entirety. If the block shrinks, then only newSize - /// elements are copied from the old block to the new one. + /// old memory block to the new one. If the block grows, then the old array + /// is copied in its entirety. If the block shrinks, then only newSize + /// elements are copied from the old block to the new one. /// \note oldSize and newSize are the count of elements, and not the - /// number of bytes. + /// number of bytes. pointer reallocate(T *oldPtr, size_type oldSize, size_type newSize, bool preserve) { CRYPTOPP_ASSERT((oldPtr && oldSize) || !(oldPtr || oldSize)); @@ -257,10 +257,10 @@ public: /// \brief Template class member Rebind /// \tparam V bound class or type /// \details Rebind allows a container class to allocate a different type of object - /// to store elements. For example, a std::list will allocate std::list_node to - /// store elements in the list. + /// to store elements. For example, a std::list will allocate std::list_node to + /// store elements in the list. /// \details VS.NET STL enforces the policy of "All STL-compliant allocators - /// have to provide a template class member called rebind". + /// have to provide a template class member called rebind". template struct rebind { typedef AllocatorWithCleanup other; }; #if _MSC_VER >= 1500 AllocatorWithCleanup() {} @@ -282,10 +282,10 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AllocatorWithCleanup; // for Integer /// \brief NULL allocator /// \tparam T class or type /// \details A NullAllocator is useful for fixed-size, stack based allocations -/// (i.e., static arrays used by FixedSizeAllocatorWithCleanup). +/// (i.e., static arrays used by FixedSizeAllocatorWithCleanup). /// \details A NullAllocator always returns 0 for max_size(), and always returns -/// NULL for allocation requests. Though the allocator does not allocate at -/// runtime, it does perform a secure wipe or zeroization during cleanup. +/// NULL for allocation requests. Though the allocator does not allocate at +/// runtime, it does perform a secure wipe or zeroization during cleanup. template class NullAllocator : public AllocatorBase { @@ -316,14 +316,14 @@ public: /// \tparam T class or type /// \tparam S fixed-size of the stack-based memory block, in elements /// \tparam T_Align16 boolean that determines whether allocations should -/// be aligned on a 16-byte boundary +/// be aligned on a 16-byte boundary /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- -/// based allocation at compile time. The class can grow its memory -/// block at runtime if a suitable allocator is available. If size -/// grows beyond S and a suitable allocator is available, then the -/// statically allocated array is obsoleted. +/// based allocation at compile time. The class can grow its memory +/// block at runtime if a suitable allocator is available. If size +/// grows beyond S and a suitable allocator is available, then the +/// statically allocated array is obsoleted. /// \note This allocator can't be used with standard collections because -/// they require that all objects of the same allocator type are equivalent. +/// they require that all objects of the same allocator type are equivalent. template , bool T_Align16 = false> class FixedSizeAllocatorWithCleanup : public AllocatorBase { @@ -338,12 +338,12 @@ class FixedSizeAllocatorWithCleanup : public AllocatorBase /// \tparam T class or type /// \tparam S fixed-size of the stack-based memory block, in elements /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- -/// based allocation at compile time. The class can grow its memory -/// block at runtime if a suitable allocator is available. If size -/// grows beyond S and a suitable allocator is available, then the -/// statically allocated array is obsoleted. +/// based allocation at compile time. The class can grow its memory +/// block at runtime if a suitable allocator is available. If size +/// grows beyond S and a suitable allocator is available, then the +/// statically allocated array is obsoleted. /// \note This allocator can't be used with standard collections because -/// they require that all objects of the same allocator type are equivalent. +/// they require that all objects of the same allocator type are equivalent. template class FixedSizeAllocatorWithCleanup : public AllocatorBase { @@ -356,14 +356,14 @@ public: /// \brief Allocates a block of memory /// \param size the count elements in the memory block /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack-based - /// allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size) { @@ -382,14 +382,14 @@ public: /// \param size the count elements in the memory block /// \param hint an unused hint /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - /// based allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size, const void *hint) { @@ -406,10 +406,10 @@ public: /// \param ptr a pointer to the memory block to deallocate /// \param size the count elements in the memory block /// \details The memory block is wiped or zeroized before deallocation. - /// If the statically allocated memory block is active, then no - /// additional actions are taken after the wipe. + /// If the statically allocated memory block is active, then no + /// additional actions are taken after the wipe. /// \details If a dynamic memory block is active, then the pointer and - /// size are passed to the allocator for deallocation. + /// size are passed to the allocator for deallocation. void deallocate(void *ptr, size_type size) { if (ptr == GetAlignedArray()) @@ -432,17 +432,17 @@ public: /// \param oldSize the size of the previous allocation /// \param newSize the new, requested size /// \param preserve flag that indicates if the old allocation should - /// be preserved + /// be preserved /// \returns pointer to the new memory block /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - /// based allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \note size is the count of elements, and not the number of bytes. /// \sa reallocate(), SecBlockWithHint pointer reallocate(pointer oldPtr, size_type oldSize, size_type newSize, bool preserve) @@ -537,12 +537,12 @@ private: /// \tparam T class or type /// \tparam S fixed-size of the stack-based memory block, in elements /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- -/// based allocation at compile time. The class can grow its memory -/// block at runtime if a suitable allocator is available. If size -/// grows beyond S and a suitable allocator is available, then the -/// statically allocated array is obsoleted. +/// based allocation at compile time. The class can grow its memory +/// block at runtime if a suitable allocator is available. If size +/// grows beyond S and a suitable allocator is available, then the +/// statically allocated array is obsoleted. /// \note This allocator can't be used with standard collections because -/// they require that all objects of the same allocator type are equivalent. +/// they require that all objects of the same allocator type are equivalent. template class FixedSizeAllocatorWithCleanup : public AllocatorBase { @@ -555,14 +555,14 @@ public: /// \brief Allocates a block of memory /// \param size the count elements in the memory block /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack-based - /// allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size) { @@ -581,14 +581,14 @@ public: /// \param size the count elements in the memory block /// \param hint an unused hint /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - /// based allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size, const void *hint) { @@ -605,8 +605,8 @@ public: /// \param ptr a pointer to the memory block to deallocate /// \param size the count elements in the memory block /// \details The memory block is wiped or zeroized before deallocation. - /// If the statically allocated memory block is active, then no - /// additional actions are taken after the wipe. + /// If the statically allocated memory block is active, then no + /// additional actions are taken after the wipe. /// \details If a dynamic memory block is active, then the pointer and /// size are passed to the allocator for deallocation. void deallocate(void *ptr, size_type size) @@ -629,17 +629,17 @@ public: /// \param oldSize the size of the previous allocation /// \param newSize the new, requested size /// \param preserve flag that indicates if the old allocation should - /// be preserved + /// be preserved /// \returns pointer to the new memory block /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - /// based allocation at compile time. If size is less than or equal to - /// S, then a pointer to the static array is returned. + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. /// \details The class can grow its memory block at runtime if a suitable - /// allocator is available. If size grows beyond S and a suitable - /// allocator is available, then the statically allocated array is - /// obsoleted. If a suitable allocator is not available, as with a - /// NullAllocator, then the function returns NULL and a runtime error - /// eventually occurs. + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. /// \note size is the count of elements, and not the number of bytes. /// \sa reallocate(), SecBlockWithHint pointer reallocate(pointer oldPtr, size_type oldSize, size_type newSize, bool preserve) @@ -695,14 +695,14 @@ public: /// \brief Returns the maximum number of elements the block can hold /// \details 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. + /// 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. + /// 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. /// \sa Issue 346/CVE-2016-9939 /// \since Crypto++ 6.0 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) @@ -737,8 +737,8 @@ public: /// \param len the number of elements in the memory block /// \throws std::bad_alloc /// \details 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. + /// 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 SecBlock(const T *ptr, size_type len) : m_mark(ELEMS_MAX), m_size(len), m_ptr(m_alloc.allocate(len, NULLPTR)) { @@ -753,16 +753,28 @@ public: {m_alloc.deallocate(m_ptr, STDMIN(m_size, m_mark));} #ifdef __BORLANDC__ + /// \brief Cast operator + /// \returns block pointer cast to non-const T * operator T *() const {return (T*)m_ptr;} #else + /// \brief Cast operator + /// \returns block pointer cast to const void * operator const void *() const {return m_ptr;} + + /// \brief Cast operator + /// \returns block pointer cast to non-const void * operator void *() {return m_ptr;} + /// \brief Cast operator + /// \returns block pointer cast to const T * operator const T *() const {return m_ptr;} + + /// \brief Cast operator + /// \returns block pointer cast to non-const T * operator T *() {return m_ptr;} #endif @@ -813,22 +825,22 @@ public: /// \brief Sets the number of elements to zeroize /// \param count the number of elements /// \details 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. + /// preserving the streaming interface. The count controls the number of + /// elements zeroized, which can be less than size or 0. /// \details 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. + /// 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. /// \details 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. + /// 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. /// \details 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. + /// 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 /// \sa Issue 346/CVE-2016-9939 void SetMark(size_t count) {m_mark = count;} @@ -837,7 +849,7 @@ public: /// \param ptr a pointer to an array of T /// \param len the number of elements in the memory block /// \details 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. + /// Assign() resets the element count after the previous block is zeroized. void Assign(const T *ptr, size_type len) { New(len); @@ -850,7 +862,7 @@ public: /// \param count the number of values to copy /// \param value the value, repeated count times /// \details 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. + /// Assign() resets the element count after the previous block is zeroized. void Assign(size_type count, T value) { New(count); @@ -864,8 +876,8 @@ public: /// \param t the other SecBlock /// \details Assign checks for self assignment. /// \details 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. + /// If an assignment occurs, then Assign() resets the element count after the previous block + /// is zeroized. void Assign(const SecBlock &t) { if (this != &t) @@ -881,8 +893,8 @@ public: /// \param t the other SecBlock /// \details Internally, operator=() calls Assign(). /// \details 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. + /// If an assignment occurs, then Assign() resets the element count after the previous block + /// is zeroized. SecBlock& operator=(const SecBlock &t) { // Assign guards for self-assignment @@ -934,19 +946,20 @@ public: /// \param t the other SecBlock /// \returns true if the size and bits are equal, false otherwise /// \details Uses a constant time compare if the arrays are equal size. The constant time - /// compare is VerifyBufsEqual() found in misc.h. + /// compare is VerifyBufsEqual() found in misc.h. /// \sa operator!=() bool operator==(const SecBlock &t) const { - return m_size == t.m_size && - VerifyBufsEqual(reinterpret_cast(m_ptr), reinterpret_cast(t.m_ptr), m_size*sizeof(T)); + return m_size == t.m_size && VerifyBufsEqual( + reinterpret_cast(m_ptr), + reinterpret_cast(t.m_ptr), m_size*sizeof(T)); } /// \brief Bitwise compare two SecBlocks /// \param t the other SecBlock /// \returns true if the size and bits are equal, false otherwise /// \details Uses a constant time compare if the arrays are equal size. The constant time - /// compare is VerifyBufsEqual() found in misc.h. + /// compare is VerifyBufsEqual() found in misc.h. /// \details Internally, operator!=() returns the inverse of operator==(). /// \sa operator==() bool operator!=(const SecBlock &t) const @@ -957,9 +970,9 @@ public: /// \brief Change size without preserving contents /// \param newSize the new size of the memory block /// \details 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. + /// 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. /// \details Internally, this SecBlock calls reallocate(). /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void New(size_type newSize) @@ -972,9 +985,9 @@ public: /// \brief Change size without preserving contents /// \param newSize the new size of the memory block /// \details 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. + /// 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. /// \details Internally, this SecBlock calls New(). /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void CleanNew(size_type newSize) @@ -988,9 +1001,9 @@ public: /// \param newSize the new size of the memory block /// \details Old content is preserved. New content is not initialized. /// \details 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. + /// 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. /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void Grow(size_type newSize) { @@ -1006,9 +1019,9 @@ public: /// \param newSize the new size of the memory block /// \details Old content is preserved. New content is initialized to 0. /// \details 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. + /// 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. /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void CleanGrow(size_type newSize) { @@ -1024,8 +1037,8 @@ public: /// \brief Change size and preserve contents /// \param newSize the new size of the memory block /// \details 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. + /// new memory is not initialized. resize() resets the element count after + /// the previous block is zeroized. /// \details Internally, this SecBlock calls reallocate(). /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void resize(size_type newSize) @@ -1067,7 +1080,7 @@ typedef SecBlock > AlignedSecByteBlock; #endif // No need for move semantics on derived class *if* the class does not add any -// data members; see http://stackoverflow.com/q/31755703, and Rule of {0|3|5}. +// data members; see http://stackoverflow.com/q/31755703, and Rule of {0|3|5}. /// \brief Fixed size stack-based SecBlock /// \tparam T class or type @@ -1110,6 +1123,12 @@ inline bool operator!=(const CryptoPP::AllocatorWithCleanup&, const Crypto NAMESPACE_END NAMESPACE_BEGIN(std) + +/// \brief Swap two SecBlocks +/// \tparam T class or type +/// \tparam A AllocatorBase derived class for allocation and cleanup +/// \param a the first SecBlock +/// \param b the second SecBlock template inline void swap(CryptoPP::SecBlock &a, CryptoPP::SecBlock &b) {