Utility functions for the Crypto++ library. More...

Classes
class	Empty
	An Empty class. More...

class	ObjectHolder< T >
	Uses encapsulation to hide an object in derived classes. More...

class	NotCopyable
	Ensures an object is not copyable. More...

struct	NewObject< T >
	An object factory function. More...

class	Singleton< T, F, instance >
	Restricts the instantiation of a class to one static object without locks. More...

class	GetBlock< T, B, A >
	Access a block of memory. More...

class	PutBlock< T, B, A >
	Access a block of memory. More...

struct	BlockGetAndPut< T, B, GA, PA >
	Access a block of memory. More...

struct	SafeShifter< true >
	Shifts a value in the presence of overflow. More...

struct	SafeShifter< false >
	Shifts a value in the absence of overflow. More...

Macros
#define	SIZE_MAX ...
	The maximum value of a machine word.

#define	CRYPTOPP_COMPILE_ASSERT(expr) { ... }
	Compile time assertion.

#define	COUNTOF(arr)
	Counts elements in an array.

#define	MEMORY_BARRIER ...
	A memory barrier.

#define	EnumToInt(v) static_cast<int>(v)
	Integer value.

#define	RETURN_IF_NONZERO(x) size_t returnedValue = x; if (returnedValue) return returnedValue

#define	GETBYTE(x, y) (unsigned int)byte((x)>>(8*(y)))

#define	CRYPTOPP_GET_BYTE_AS_BYTE(x, y) byte((x)>>(8*(y)))

#define	CRYPTOPP_BLOCK_1(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+0);} size_t SS1() {return sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_2(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS1());} size_t SS2() {return SS1()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_3(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS2());} size_t SS3() {return SS2()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_4(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS3());} size_t SS4() {return SS3()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_5(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS4());} size_t SS5() {return SS4()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_6(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS5());} size_t SS6() {return SS5()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_7(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS6());} size_t SS7() {return SS6()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCK_8(n, t, s) t* m_##n() {return (t )(void )(m_aggregate+SS7());} size_t SS8() {return SS7()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

#define	CRYPTOPP_BLOCKS_END(i) size_t SST() {return SS##i();} void AllocateBlocks() {m_aggregate.New(SST());} AlignedSecByteBlock m_aggregate;

Typedefs
typedef LittleEndian	NativeByteOrder

Functions
template<typename PTR , typename OFF >
PTR	PtrAdd (PTR pointer, OFF offset)
	Create a pointer with an offset.

template<typename PTR , typename OFF >
PTR	PtrSub (PTR pointer, OFF offset)
	Create a pointer with an offset.

template<typename PTR >
ptrdiff_t	PtrDiff (const PTR pointer1, const PTR pointer2)
	Determine pointer difference.

template<typename PTR >
size_t	PtrByteDiff (const PTR pointer1, const PTR pointer2)
	Determine pointer difference.

byte *	BytePtr (std::string &str)
	Pointer to the first element of a string.

byte *	BytePtr (SecByteBlock &str)
	Pointer to the first element of a string.

const byte *	ConstBytePtr (const std::string &str)
	Const pointer to the first element of a string.

const byte *	ConstBytePtr (const SecByteBlock &str)
	Const pointer to the first element of a string.

size_t	BytePtrSize (const std::string &str)
	Size of a string.

size_t	BytePtrSize (const SecByteBlock &str)
	Size of a string.

void	memcpy_s (void dest, size_t sizeInBytes, const void src, size_t count)
	Bounds checking replacement for memcpy()

void	memmove_s (void dest, size_t sizeInBytes, const void src, size_t count)
	Bounds checking replacement for memmove()

template<class T >
void	vec_swap (T &a, T &b)
	Swaps two variables which are arrays.

void *	memset_z (void *ptr, int val, size_t num)
	Memory block initializer.

template<class T >
const T &	STDMIN (const T &a, const T &b)
	Replacement function for std::min.

template<class T >
const T &	STDMAX (const T &a, const T &b)
	Replacement function for std::max.

template<class T1 , class T2 >
const T1	UnsignedMin (const T1 &a, const T2 &b)
	Safe comparison of values that could be negative and incorrectly promoted.

template<class T1 , class T2 >
bool	SafeConvert (T1 from, T2 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword64 from, word64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word32 from, word64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword32 from, word64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word64 from, sword64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word32 from, sword64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword32 from, sword64 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word64 from, word32 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword64 from, word32 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword32 from, word32 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word64 from, sword32 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (sword64 from, sword32 &to)
	Perform a conversion from `from` to `to`.

template<>
bool	SafeConvert (word32 from, sword32 &to)
	Perform a conversion from `from` to `to`.

template<class T >
std::string	IntToString (T value, unsigned int base=10)
	Converts a value to a string.

template<>
CRYPTOPP_DLL std::string	IntToString< word64 > (word64 value, unsigned int base)
	Converts an unsigned value to a string.

template<>
CRYPTOPP_DLL std::string	IntToString< Integer > (Integer value, unsigned int base)
	Converts an Integer to a string.

template<class T >
unsigned int	Parity (T value)
	Returns the parity of a value.

template<class T >
unsigned int	BytePrecision (const T &value)
	Returns the number of 8-bit bytes or octets required for a value.

template<class T >
unsigned int	BitPrecision (const T &value)
	Returns the number of bits required for a value.

unsigned int	TrailingZeros (word32 v)
	Determines the number of trailing 0-bits in a value.

unsigned int	TrailingZeros (word64 v)
	Determines the number of trailing 0-bits in a value.

template<class T >
T	Crop (T value, size_t bits)
	Truncates the value to the specified number of bits.

size_t	BitsToBytes (size_t bitCount)
	Returns the number of 8-bit bytes or octets required for the specified number of bits.

size_t	BytesToWords (size_t byteCount)
	Returns the number of words required for the specified number of bytes.

size_t	BitsToWords (size_t bitCount)
	Returns the number of words required for the specified number of bits.

size_t	BitsToDwords (size_t bitCount)
	Returns the number of double words required for the specified number of bits.

CRYPTOPP_DLL void	xorbuf (byte buf, const byte mask, size_t count)
	Performs an XOR of a buffer with a mask.

CRYPTOPP_DLL void	xorbuf (byte output, const byte input, const byte *mask, size_t count)
	Performs an XOR of an input buffer with a mask and stores the result in an output buffer.

CRYPTOPP_DLL bool	VerifyBufsEqual (const byte buf1, const byte buf2, size_t count)
	Performs a near constant-time comparison of two equally sized buffers.

template<class T >
bool	IsPowerOf2 (const T &value)
	Tests whether a value is a power of 2.

template<class T >
T	NumericLimitsMin ()
	Provide the minimum value for a type.

template<class T >
T	NumericLimitsMax ()
	Provide the maximum value for a type.

template<>
word128	NumericLimitsMin ()

template<>
word128	NumericLimitsMax ()

template<class T1 , class T2 >
T1	SaturatingSubtract (const T1 &a, const T2 &b)
	Performs a saturating subtract clamped at 0.

template<class T1 , class T2 >
T1	SaturatingSubtract1 (const T1 &a, const T2 &b)
	Performs a saturating subtract clamped at 1.

template<class T1 , class T2 >
T2	ModPowerOf2 (const T1 &a, const T2 &b)
	Reduces a value to a power of 2.

template<class T1 , class T2 >
T1	RoundDownToMultipleOf (const T1 &n, const T2 &m)
	Rounds a value down to a multiple of a second value.

template<class T1 , class T2 >
T1	RoundUpToMultipleOf (const T1 &n, const T2 &m)
	Rounds a value up to a multiple of a second value.

template<class T >
unsigned int	GetAlignmentOf ()
	Returns the minimum alignment requirements of a type.

bool	IsAlignedOn (const void *ptr, unsigned int alignment)
	Determines whether ptr is aligned to a minimum value.

template<class T >
bool	IsAligned (const void *ptr)
	Determines whether ptr is minimally aligned.

ByteOrder	GetNativeByteOrder ()
	Returns NativeByteOrder as an enumerated ByteOrder value.

bool	NativeByteOrderIs (ByteOrder order)
	Determines whether order follows native byte ordering.

template<class T >
CipherDir	GetCipherDir (const T &obj)
	Returns the direction the cipher is being operated.

void	IncrementCounterByOne (byte *inout, unsigned int size)
	Performs an addition with carry on a block of bytes.

void	IncrementCounterByOne (byte output, const byte input, unsigned int size)
	Performs an addition with carry on a block of bytes.

template<class T >
void	ConditionalSwap (bool c, T &a, T &b)
	Performs a branch-less swap of values a and b if condition c is true.

template<class T >
void	ConditionalSwapPointers (bool c, T &a, T &b)
	Performs a branch-less swap of pointers a and b if condition c is true.

template<class T >
void	SecureWipeBuffer (T *buf, size_t n)
	Sets each element of an array to 0.

template<>
void	SecureWipeBuffer (byte *buf, size_t n)
	Sets each byte of an array to 0.

template<>
void	SecureWipeBuffer (word16 *buf, size_t n)
	Sets each 16-bit element of an array to 0.

template<>
void	SecureWipeBuffer (word32 *buf, size_t n)
	Sets each 32-bit element of an array to 0.

template<>
void	SecureWipeBuffer (word64 *buf, size_t n)
	Sets each 64-bit element of an array to 0.

template<class T >
void	SecureWipeArray (T *buf, size_t n)
	Sets each element of an array to 0.

std::string	StringNarrow (const wchar_t *str, bool throwOnError=true)
	Converts a wide character C-string to a multibyte string.

std::wstring	StringWiden (const char *str, bool throwOnError=true)
	Converts a multibyte C-string to a wide character string.

template<unsigned int R, class T >
T	rotlConstant (T x)
	Performs a left rotate.

template<unsigned int R, class T >
T	rotrConstant (T x)
	Performs a right rotate.

template<class T >
T	rotlFixed (T x, unsigned int y)
	Performs a left rotate.

template<class T >
T	rotrFixed (T x, unsigned int y)
	Performs a right rotate.

template<class T >
T	rotlVariable (T x, unsigned int y)
	Performs a left rotate.

template<class T >
T	rotrVariable (T x, unsigned int y)
	Performs a right rotate.

template<class T >
T	rotlMod (T x, unsigned int y)
	Performs a left rotate.

template<class T >
T	rotrMod (T x, unsigned int y)
	Performs a right rotate.

template<class T >
unsigned int	GetByte (ByteOrder order, T value, unsigned int index)
	Gets a byte from a value.

byte	ByteReverse (byte value)
	Reverses bytes in a 8-bit value.

word16	ByteReverse (word16 value)
	Reverses bytes in a 16-bit value.

word32	ByteReverse (word32 value)
	Reverses bytes in a 32-bit value.

word64	ByteReverse (word64 value)
	Reverses bytes in a 64-bit value.

word128	ByteReverse (word128 value)
	Reverses bytes in a 128-bit value.

byte	BitReverse (byte value)
	Reverses bits in a 8-bit value.

word16	BitReverse (word16 value)
	Reverses bits in a 16-bit value.

word32	BitReverse (word32 value)
	Reverses bits in a 32-bit value.

word64	BitReverse (word64 value)
	Reverses bits in a 64-bit value.

template<class T >
T	BitReverse (T value)
	Reverses bits in a value.

template<class T >
T	ConditionalByteReverse (ByteOrder order, T value)
	Reverses bytes in a value depending upon endianness.

template<class T >
void	ByteReverse (T out, const T in, size_t byteCount)
	Reverses bytes in an element from an array of elements.

template<class T >
void	ConditionalByteReverse (ByteOrder order, T out, const T in, size_t byteCount)
	Conditionally reverses bytes in an element from an array of elements.

template<class T >
void	GetUserKey (ByteOrder order, T out, size_t outlen, const byte in, size_t inlen)
	Copy bytes in a buffer to an array of elements in big-endian order.

byte	UnalignedGetWordNonTemplate (ByteOrder order, const byte block, const byte unused)
	Retrieve a byte from an unaligned buffer.

word16	UnalignedGetWordNonTemplate (ByteOrder order, const byte block, const word16 unused)
	Retrieve a word16 from an unaligned buffer.

word32	UnalignedGetWordNonTemplate (ByteOrder order, const byte block, const word32 unused)
	Retrieve a word32 from an unaligned buffer.

word64	UnalignedGetWordNonTemplate (ByteOrder order, const byte block, const word64 unused)
	Retrieve a word64 from an unaligned buffer.

word128	UnalignedGetWordNonTemplate (ByteOrder order, const byte block, const word128 unused)
	Retrieve a word128 from an unaligned buffer.

void	UnalignedbyteNonTemplate (ByteOrder order, byte block, byte value, const byte xorBlock)
	Write a byte to an unaligned buffer.

void	UnalignedbyteNonTemplate (ByteOrder order, byte block, word16 value, const byte xorBlock)
	Write a word16 to an unaligned buffer.

void	UnalignedbyteNonTemplate (ByteOrder order, byte block, word32 value, const byte xorBlock)
	Write a word32 to an unaligned buffer.

void	UnalignedbyteNonTemplate (ByteOrder order, byte block, word64 value, const byte xorBlock)
	Write a word64 to an unaligned buffer.

void	UnalignedbyteNonTemplate (ByteOrder order, byte block, word128 value, const byte xorBlock)
	Write a word128 to an unaligned buffer.

template<class T >
T	GetWord (bool assumeAligned, ByteOrder order, const byte *block)
	Access a block of memory.

template<class T >
void	GetWord (bool assumeAligned, ByteOrder order, T &result, const byte *block)
	Access a block of memory.

template<class T >
void	PutWord (bool assumeAligned, ByteOrder order, byte block, T value, const byte xorBlock=NULL)
	Access a block of memory.

template<class T >
std::string	WordToString (T value, ByteOrder order=BIG_ENDIAN_ORDER)
	Convert a word to a string.

template<class T >
T	StringToWord (const std::string &str, ByteOrder order=BIG_ENDIAN_ORDER)
	Convert a string to a word.

template<unsigned int bits, class T >
T	SafeRightShift (T value)
	Safely right shift values when undefined behavior could occur.

template<unsigned int bits, class T >
T	SafeLeftShift (T value)
	Safely left shift values when undefined behavior could occur.

template<typename InputIt , typename T >
InputIt	FindIfNot (InputIt first, InputIt last, const T &value)
	Finds first element not in a range.

Detailed Description

Utility functions for the Crypto++ library.

Definition in file misc.h.

Macro Definition Documentation

◆ SIZE_MAX

#define SIZE_MAX ...

The maximum value of a machine word.

SIZE_MAX provides the maximum value of a machine word. The value is 0xffffffff on 32-bit targets, and 0xffffffffffffffff on 64-bit targets.

If SIZE_MAX is not defined, then __SIZE_MAX__ is used if defined. If not defined, then SIZE_T_MAX is used if defined. If not defined, then the library uses std::numeric_limits<size_t>::max().

The library prefers __SIZE_MAX__ or __SIZE_T_MAX__ because they are effectively constexpr that is optimized well by all compilers. std::numeric_limits<size_t>::max() is not always a constexpr, and it is not always optimized well.

Definition at line 120 of file misc.h.

◆ CRYPTOPP_COMPILE_ASSERT

#define CRYPTOPP_COMPILE_ASSERT ( expr ) { ... }

Compile time assertion.

Parameters

expr	the expression to evaluate

Asserts the expression expr during compile. If C++14 and N3928 are available, then C++14 static_assert is used. Otherwise, a CompileAssert structure is used. When the structure is used a negative-sized array triggers the assert at compile time.

Definition at line 153 of file misc.h.

◆ COUNTOF

#define COUNTOF ( arr )

Counts elements in an array.

Parameters

arr	an array of elements

COUNTOF counts elements in an array. On Windows COUNTOF(x) is defined to _countof(x) to ensure correct results for pointers.

Note: COUNTOF does not produce correct results with pointers, and an array must be used. sizeof(x)/sizeof(x[0]) suffers the same problem. The risk is eliminated by using _countof(x) on Windows. Windows will provide the immunity for other platforms.

Definition at line 193 of file misc.h.

◆ MEMORY_BARRIER

#define MEMORY_BARRIER ...

A memory barrier.

MEMORY_BARRIER attempts to ensure reads and writes are completed in the absence of a language synchronization point. It is used by the Singleton class if the compiler supports it. The barrier is provided at the customary places in a double-checked initialization.

Internally, MEMORY_BARRIER uses std::atomic_thread_fence if C++11 atomics are available. Otherwise, intrinsic(_ReadWriteBarrier), _ReadWriteBarrier() or __asm__("" ::: "memory") is used.

Definition at line 272 of file misc.h.

◆ EnumToInt

#define EnumToInt ( v ) static_cast<int>(v)

Integer value.

EnumToInt avoids C++20 enum-enum conversion warnings under GCC and Clang. C++11 and above use a constexpr function. C++03 and below use a macro due to [lack of] constexpr-ness in early versions of C++.

Since: Crypto++ 8.6

Definition at line 504 of file misc.h.

◆ RETURN_IF_NONZERO

#define RETURN_IF_NONZERO ( x ) size_t returnedValue = x; if (returnedValue) return returnedValue

Definition at line 997 of file misc.h.

◆ GETBYTE

#define GETBYTE	(		x,
			y ) (unsigned int)byte((x)>>(8*(y)))

Definition at line 1000 of file misc.h.

◆ CRYPTOPP_GET_BYTE_AS_BYTE

#define CRYPTOPP_GET_BYTE_AS_BYTE	(		x,
			y ) byte((x)>>(8*(y)))

Definition at line 1005 of file misc.h.

◆ CRYPTOPP_BLOCK_1

#define CRYPTOPP_BLOCK_1	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+0);} size_t SS1() {return sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3202 of file misc.h.

◆ CRYPTOPP_BLOCK_2

#define CRYPTOPP_BLOCK_2	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS1());} size_t SS2() {return SS1()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3203 of file misc.h.

◆ CRYPTOPP_BLOCK_3

#define CRYPTOPP_BLOCK_3	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS2());} size_t SS3() {return SS2()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3204 of file misc.h.

◆ CRYPTOPP_BLOCK_4

#define CRYPTOPP_BLOCK_4	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS3());} size_t SS4() {return SS3()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3205 of file misc.h.

◆ CRYPTOPP_BLOCK_5

#define CRYPTOPP_BLOCK_5	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS4());} size_t SS5() {return SS4()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3206 of file misc.h.

◆ CRYPTOPP_BLOCK_6

#define CRYPTOPP_BLOCK_6	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS5());} size_t SS6() {return SS5()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3207 of file misc.h.

◆ CRYPTOPP_BLOCK_7

#define CRYPTOPP_BLOCK_7	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS6());} size_t SS7() {return SS6()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3208 of file misc.h.

◆ CRYPTOPP_BLOCK_8

#define CRYPTOPP_BLOCK_8	(	n,
		t,
		s ) t* m_##n() {return (t )(void )(m_aggregate+SS7());} size_t SS8() {return SS7()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}

Definition at line 3209 of file misc.h.

◆ CRYPTOPP_BLOCKS_END

#define CRYPTOPP_BLOCKS_END ( i ) size_t SST() {return SS##i();} void AllocateBlocks() {m_aggregate.New(SST());} AlignedSecByteBlock m_aggregate;

Definition at line 3210 of file misc.h.

Typedef Documentation

◆ NativeByteOrder

typedef LittleEndian NativeByteOrder

Definition at line 1456 of file misc.h.

Function Documentation

◆ PtrAdd()

template<typename PTR , typename OFF >

PTR PtrAdd	(	PTR	pointer,
		OFF	offset )

inline

Create a pointer with an offset.

Template Parameters

PTR	a pointer type
OFF	a size type

Parameters

pointer	a pointer
offset	a offset into the pointer

PtrAdd can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction.

Definition at line 388 of file misc.h.

◆ PtrSub()

template<typename PTR , typename OFF >

PTR PtrSub	(	PTR	pointer,
		OFF	offset )

inline

Create a pointer with an offset.

Template Parameters

PTR	a pointer type
OFF	a size type

Parameters

pointer	a pointer
offset	a offset into the pointer

PtrSub can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction.

Definition at line 401 of file misc.h.

◆ PtrDiff()

template<typename PTR >

ptrdiff_t PtrDiff	(	const PTR	pointer1,
		const PTR	pointer2 )

inline

Determine pointer difference.

Template Parameters

PTR	a pointer type

Parameters

pointer1	the first pointer
pointer2	the second pointer

PtrDiff can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction. pointer1 and pointer2 must point to the same object or array (or one past the end), and yields the number of elements (not bytes) difference.

Definition at line 416 of file misc.h.

◆ PtrByteDiff()

template<typename PTR >

size_t PtrByteDiff	(	const PTR	pointer1,
		const PTR	pointer2 )

inline

Determine pointer difference.

Template Parameters

PTR	a pointer type

Parameters

pointer1	the first pointer
pointer2	the second pointer

PtrByteDiff can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction. pointer1 and pointer2 must point to the same object or array (or one past the end), and yields the number of bytes (not elements) difference.

Definition at line 431 of file misc.h.

◆ BytePtr() [1/2]

byte * BytePtr ( std::string & str )

inline

Pointer to the first element of a string.

Parameters

str string

BytePtr returns NULL pointer for an empty string.

Returns: Pointer to the first element of a string

Since: Crypto++ 8.0

Definition at line 441 of file misc.h.

◆ BytePtr() [2/2]

byte * BytePtr ( SecByteBlock & str )

Pointer to the first element of a string.

Parameters

str	SecByteBlock

BytePtr returns NULL pointer for an empty string.

Returns: Pointer to the first element of a string

Since: Crypto++ 8.3

◆ ConstBytePtr() [1/2]

const byte * ConstBytePtr ( const std::string & str )

inline

Const pointer to the first element of a string.

Parameters

str string

ConstBytePtr returns non-NULL pointer for an empty string.

Returns: Pointer to the first element of a string

Since: Crypto++ 8.0

Definition at line 463 of file misc.h.

◆ ConstBytePtr() [2/2]

const byte * ConstBytePtr ( const SecByteBlock & str )

Const pointer to the first element of a string.

Parameters

str	SecByteBlock

ConstBytePtr returns non-NULL pointer for an empty string.

Returns: Pointer to the first element of a string

Since: Crypto++ 8.3

◆ BytePtrSize() [1/2]

size_t BytePtrSize ( const std::string & str )

inline

Size of a string.

Parameters

str string

Returns: size of a string

Since: Crypto++ 8.3

Definition at line 481 of file misc.h.

◆ BytePtrSize() [2/2]

size_t BytePtrSize ( const SecByteBlock & str )

Size of a string.

Parameters

str	SecByteBlock

Returns: size of a string

Since: Crypto++ 8.3

◆ memcpy_s()

void memcpy_s	(	void *	dest,
		size_t	sizeInBytes,
		const void *	src,
		size_t	count )

inline

Bounds checking replacement for memcpy()

Parameters

dest	pointer to the destination memory block
sizeInBytes	size of the destination memory block, in bytes
src	pointer to the source memory block
count	the number of bytes to copy

Exceptions

InvalidArgument

ISO/IEC TR-24772 provides bounds checking interfaces for potentially unsafe functions like memcpy(), strcpy() and memmove(). However, not all standard libraries provides them, like Glibc. The library's memcpy_s() is a near-drop in replacement. Its only a near-replacement because the library's version throws an InvalidArgument on a bounds violation.

memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. If __STDC_WANT_SECURE_LIB__ is not defined or defined to 0, then the library makes memcpy_s() and memmove_s() available. The library will also optionally make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default.

memcpy_s() will assert the pointers src and dest are not NULL in debug builds. Passing NULL for either pointer is undefined behavior.

Definition at line 527 of file misc.h.

◆ memmove_s()

void memmove_s	(	void *	dest,
		size_t	sizeInBytes,
		const void *	src,
		size_t	count )

inline

Bounds checking replacement for memmove()

Parameters

dest	pointer to the destination memory block
sizeInBytes	size of the destination memory block, in bytes
src	pointer to the source memory block
count	the number of bytes to copy

Exceptions

InvalidArgument

ISO/IEC TR-24772 provides bounds checking interfaces for potentially unsafe functions like memcpy(), strcpy() and memmove(). However, not all standard libraries provides them, like Glibc. The library's memmove_s() is a near-drop in replacement. Its only a near-replacement because the library's version throws an InvalidArgument on a bounds violation.

memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. If __STDC_WANT_SECURE_LIB__ is not defined or defined to 0, then the library makes memcpy_s() and memmove_s() available. The library will also optionally make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default.

memmove_s() will assert the pointers src and dest are not NULL in debug builds. Passing NULL for either pointer is undefined behavior.

Definition at line 573 of file misc.h.

◆ vec_swap()

template<class T >

void vec_swap	(	T &	a,
		T &	b )

inline

Swaps two variables which are arrays.

Template Parameters

T	class or type

Parameters

a	the first value
b	the second value

C++03 does not provide support for std::swap(__m128i a, __m128i b) because __m128i is an unsigned long long[2]. Most compilers support it out of the box, but Sun Studio C++ compilers 12.2 and 12.3 do not.

See also: How to swap two __m128i variables in C++03 given its an opaque type and an array? on Stack Overflow.

Definition at line 618 of file misc.h.

◆ memset_z()

void * memset_z	(	void *	ptr,
		int	val,
		size_t	num )

inline

Memory block initializer.

Parameters

ptr	pointer to the memory block being written
val	the integer value to write for each byte
num	the size of the source memory block, in bytes

Internally the function calls memset with the value val. memset_z can be used to initialize a freshly allocated memory block. To zeroize a memory block on destruction use SecureWipeBuffer.

Returns: the pointer to the memory block

See also: SecureWipeBuffer

Definition at line 640 of file misc.h.

◆ STDMIN()

template<class T >

const T & STDMIN	(	const T &	a,
		const T &	b )

inline

Replacement function for std::min.

Template Parameters

T	class or type

Parameters

a	the first value
b	the second value

Returns: the minimum value based on a comparison of b < a using operator<

STDMIN was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0

Definition at line 657 of file misc.h.

◆ STDMAX()

template<class T >

const T & STDMAX	(	const T &	a,
		const T &	b )

inline

Replacement function for std::max.

Template Parameters

T	class or type

Parameters

a	the first value
b	the second value

Returns: the minimum value based on a comparison of a < b using operator<

STDMAX was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0

Definition at line 668 of file misc.h.

◆ UnsignedMin()

template<class T1 , class T2 >

const T1 UnsignedMin	(	const T1 &	a,
		const T2 &	b )

inline

Safe comparison of values that could be negative and incorrectly promoted.

Template Parameters

T1	class or type
T2	class or type

Parameters

a	the first value
b	the second value

Returns: the minimum value based on a comparison a and b using operator<.

The comparison b < a is performed and the value returned is type T1.

Definition at line 695 of file misc.h.

◆ SafeConvert() [1/13]

template<class T1 , class T2 >

bool SafeConvert	(	T1	from,
		T2 &	to )

inline

Perform a conversion from from to to.

Template Parameters

T1	class or type
T2	class or type

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Note: for integral conversions, a template specialization should be provided. The specialization will perform more efficiently, and avoid warnings for truncation and sign compares.

Definition at line 718 of file misc.h.

◆ SafeConvert() [2/13]

template<>

bool SafeConvert	(	sword64	from,
		word64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 741 of file misc.h.

◆ SafeConvert() [3/13]

template<>

bool SafeConvert	(	word32	from,
		word64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 757 of file misc.h.

◆ SafeConvert() [4/13]

template<>

bool SafeConvert	(	sword32	from,
		word64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 771 of file misc.h.

◆ SafeConvert() [5/13]

template<>

bool SafeConvert	(	word64	from,
		sword64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 787 of file misc.h.

◆ SafeConvert() [6/13]

template<>

bool SafeConvert	(	word32	from,
		sword64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 803 of file misc.h.

◆ SafeConvert() [7/13]

template<>

bool SafeConvert	(	sword32	from,
		sword64 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 817 of file misc.h.

◆ SafeConvert() [8/13]

template<>

bool SafeConvert	(	word64	from,
		word32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 831 of file misc.h.

◆ SafeConvert() [9/13]

template<>

bool SafeConvert	(	sword64	from,
		word32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 847 of file misc.h.

◆ SafeConvert() [10/13]

template<>

bool SafeConvert	(	sword32	from,
		word32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 865 of file misc.h.

◆ SafeConvert() [11/13]

template<>

bool SafeConvert	(	word64	from,
		sword32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 881 of file misc.h.

◆ SafeConvert() [12/13]

template<>

bool SafeConvert	(	sword64	from,
		sword32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 897 of file misc.h.

◆ SafeConvert() [13/13]

template<>

bool SafeConvert	(	word32	from,
		sword32 &	to )

inline

Perform a conversion from from to to.

Parameters

from	the first value
to	the second value

Returns: true if its safe to convert from from to to, false otherwise.

if the function returns true, then it is safe to use to. If the function returns false, then to is undefined and should not be used.

Since: Crypto++ 8.8

Definition at line 915 of file misc.h.

◆ IntToString()

template<class T >

std::string IntToString	(	T	value,
		unsigned int	base = 10 )

Converts a value to a string.

Template Parameters

T	class or type

Parameters

value	the value to convert
base	the base to use during the conversion

Returns: the string representation of value in base.

Definition at line 929 of file misc.h.

◆ IntToString< word64 >()

template<>

CRYPTOPP_DLL std::string IntToString< word64 >	(	word64	value,
		unsigned int	base )

Converts an unsigned value to a string.

Parameters

value	the value to convert
base	the base to use during the conversion

Returns: the string representation of value in base.

this template function specialization was added to suppress Coverity findings on IntToString() with unsigned types.

◆ IntToString< Integer >()

template<>

CRYPTOPP_DLL std::string IntToString< Integer >	(	Integer	value,
		unsigned int	base )

Converts an Integer to a string.

Parameters

value	the Integer to convert
base	the base to use during the conversion

Returns: the string representation of value in base.

This is a template specialization of IntToString(). Use it like IntToString():

 // Print integer in base 10
 Integer n...
 std::string s = IntToString(n, 10);

The string is presented with lowercase letters by default. A hack is available to switch to uppercase letters without modifying the function signature.

 // Print integer in base 16, uppercase letters
 Integer n...
 const unsigned int UPPER = (1 << 31);
 std::string s = IntToString(n, (UPPER | 16));

◆ Parity()

template<class T >

unsigned int Parity ( T value )

Returns the parity of a value.

Template Parameters

T	class or type

Parameters

value the value to provide the parity

Returns: 1 if the number 1-bits in the value is odd, 0 otherwise

Definition at line 1012 of file misc.h.

◆ BytePrecision()

template<class T >

unsigned int BytePrecision ( const T & value )

Returns the number of 8-bit bytes or octets required for a value.

Template Parameters

T	class or type

Parameters

value the value to test

Returns: the minimum number of 8-bit bytes or octets required to represent a value

Definition at line 1024 of file misc.h.

◆ BitPrecision()

template<class T >

unsigned int BitPrecision ( const T & value )

Returns the number of bits required for a value.

Template Parameters

T	class or type

Parameters

value the value to test

Returns: the maximum number of bits required to represent a value.

Definition at line 1047 of file misc.h.

◆ TrailingZeros() [1/2]

unsigned int TrailingZeros ( word32 v )

inline

Determines the number of trailing 0-bits in a value.

Parameters

v	the 32-bit value to test

Returns: the number of trailing 0-bits in v, starting at the least significant bit position

TrailingZeros returns the number of trailing 0-bits in v, starting at the least significant bit position. The return value is undefined if there are no 1-bits set in the value v.

Note: The function does not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position.

Definition at line 1072 of file misc.h.

◆ TrailingZeros() [2/2]

unsigned int TrailingZeros ( word64 v )

inline

Determines the number of trailing 0-bits in a value.

Parameters

v	the 64-bit value to test

Returns: the number of trailing 0-bits in v, starting at the least significant bit position

TrailingZeros returns the number of trailing 0-bits in v, starting at the least significant bit position. The return value is undefined if there are no 1-bits set in the value v.

Note: The function does not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position.

Definition at line 1103 of file misc.h.

◆ Crop()

template<class T >

T Crop	(	T	value,
		size_t	bits )

inline

Truncates the value to the specified number of bits.

Template Parameters

T	class or type

Parameters

value	the value to truncate or mask
bits	the number of bits to truncate or mask

Returns: the value truncated to the specified number of bits, starting at the least significant bit position

This function masks the low-order bits of value and returns the result. The mask is created with (1 << bits) - 1.

Definition at line 1131 of file misc.h.

◆ BitsToBytes()

size_t BitsToBytes ( size_t bitCount )

inline

Returns the number of 8-bit bytes or octets required for the specified number of bits.

Parameters

bitCount the number of bits

Returns: the minimum number of 8-bit bytes or octets required by bitCount

BitsToBytes is effectively a ceiling function based on 8-bit bytes.

Definition at line 1143 of file misc.h.

◆ BytesToWords()

size_t BytesToWords ( size_t byteCount )

inline

Returns the number of words required for the specified number of bytes.

Parameters

byteCount the number of bytes

Returns: the minimum number of words required by byteCount

BytesToWords is effectively a ceiling function based on WORD_SIZE. WORD_SIZE is defined in config.h

Definition at line 1153 of file misc.h.

◆ BitsToWords()

size_t BitsToWords ( size_t bitCount )

inline

Returns the number of words required for the specified number of bits.

Parameters

bitCount the number of bits

Returns: the minimum number of words required by bitCount

BitsToWords is effectively a ceiling function based on WORD_BITS. WORD_BITS is defined in config.h

Definition at line 1163 of file misc.h.

◆ BitsToDwords()

size_t BitsToDwords ( size_t bitCount )

inline

Returns the number of double words required for the specified number of bits.

Parameters

bitCount the number of bits

Returns: the minimum number of double words required by bitCount

BitsToDwords is effectively a ceiling function based on 2*WORD_BITS. WORD_BITS is defined in config.h

Definition at line 1173 of file misc.h.

◆ xorbuf() [1/2]

CRYPTOPP_DLL void xorbuf	(	byte *	buf,
		const byte *	mask,
		size_t	count )

Performs an XOR of a buffer with a mask.

Parameters

buf	the buffer to XOR with the mask
mask	the mask to XOR with the buffer
count	the size of the buffers, in bytes

The function effectively visits each element in the buffers and performs buf[i] ^= mask[i]. buf and mask must be of equal size.

◆ xorbuf() [2/2]

CRYPTOPP_DLL void xorbuf	(	byte *	output,
		const byte *	input,
		const byte *	mask,
		size_t	count )

Performs an XOR of an input buffer with a mask and stores the result in an output buffer.

Parameters

output	the destination buffer
input	the source buffer to XOR with the mask
mask	the mask buffer to XOR with the input buffer
count	the size of the buffers, in bytes

The function effectively visits each element in the buffers and performs output[i] = input[i] ^ mask[i]. output, input and mask must be of equal size.

◆ VerifyBufsEqual()

CRYPTOPP_DLL bool VerifyBufsEqual	(	const byte *	buf1,
		const byte *	buf2,
		size_t	count )

Performs a near constant-time comparison of two equally sized buffers.

Parameters

buf1	the first buffer
buf2	the second buffer
count	the size of the buffers, in bytes

VerifyBufsEqual performs an XOR of the elements in two equally sized buffers and returns a result based on the XOR operation. A count of 0 returns true because two empty buffers are considered equal.

The function is near constant-time because CPU micro-code timings could affect the "constant-ness". Calling code is responsible for mitigating timing attacks if the buffers are not equally sized.

See also: ModPowerOf2

◆ IsPowerOf2()

template<class T >

bool IsPowerOf2 ( const T & value )

inline

Tests whether a value is a power of 2.

Parameters

value the value to test

Returns: true if value is a power of 2, false otherwise

The function creates a mask of value - 1 and returns the result of an AND operation compared to 0. If value is 0 or less than 0, then the function returns false.

Definition at line 1215 of file misc.h.

◆ NumericLimitsMin() [1/2]

template<class T >

T NumericLimitsMin ( )

inline

Provide the minimum value for a type.

Template Parameters

T	type of class

Returns: the minimum value of the type or class

NumericLimitsMin() was introduced for Clang at Issue 364, Apple Clang 6.0 and numeric_limits<word128>::max() returns 0.

NumericLimitsMin() requires a specialization for T, meaning std::numeric_limits<T>::is_specialized must return true. In the case of word128 Clang did not specialize numeric_limits for the type.

Since: Crypto++ 8.1

Definition at line 1248 of file misc.h.

◆ NumericLimitsMax() [1/2]

template<class T >

T NumericLimitsMax ( )

inline

Provide the maximum value for a type.

Template Parameters

T	type of class

Returns: the maximum value of the type or class

NumericLimitsMax() was introduced for Clang at Issue 364, Apple Clang 6.0 and numeric_limits<word128>::max() returns 0.

NumericLimitsMax() requires a specialization for T, meaning std::numeric_limits<T>::is_specialized must return true. In the case of word128 Clang did not specialize numeric_limits for the type.

Since: Crypto++ 8.1

Definition at line 1266 of file misc.h.

◆ NumericLimitsMin() [2/2]

template<>

word128 NumericLimitsMin ( )

inline

Definition at line 1276 of file misc.h.

◆ NumericLimitsMax() [2/2]

template<>

word128 NumericLimitsMax ( )

inline

Definition at line 1281 of file misc.h.

◆ SaturatingSubtract()

template<class T1 , class T2 >

T1 SaturatingSubtract	(	const T1 &	a,
		const T2 &	b )

inline

Performs a saturating subtract clamped at 0.

Template Parameters

T1	class or type
T2	class or type

Parameters

a	the minuend
b	the subtrahend

Returns: the difference produced by the saturating subtract

Saturating arithmetic restricts results to a fixed range. Results that are less than 0 are clamped at 0.

Use of saturating arithmetic in places can be advantageous because it can avoid a branch by using an instruction like a conditional move (CMOVE).

Definition at line 1302 of file misc.h.

◆ SaturatingSubtract1()

template<class T1 , class T2 >

T1 SaturatingSubtract1	(	const T1 &	a,
		const T2 &	b )

inline

Performs a saturating subtract clamped at 1.

Template Parameters

T1	class or type
T2	class or type

Parameters

a	the minuend
b	the subtrahend

Returns: the difference produced by the saturating subtract

Saturating arithmetic restricts results to a fixed range. Results that are less than 1 are clamped at 1.

Use of saturating arithmetic in places can be advantageous because it can avoid a branch by using an instruction like a conditional move (CMOVE).

Definition at line 1319 of file misc.h.

◆ ModPowerOf2()

template<class T1 , class T2 >

T2 ModPowerOf2	(	const T1 &	a,
		const T2 &	b )

inline

Reduces a value to a power of 2.

Template Parameters

T1	class or type
T2	class or type

Parameters

a	the first value
b	the second value

Returns: ModPowerOf2() returns a & (b-1). b must be a power of 2. Use IsPowerOf2() to determine if b is a suitable candidate.

See also: IsPowerOf2

Definition at line 1334 of file misc.h.

◆ RoundDownToMultipleOf()

template<class T1 , class T2 >

T1 RoundDownToMultipleOf	(	const T1 &	n,
		const T2 &	m )

inline

Rounds a value down to a multiple of a second value.

Template Parameters

T1	class or type
T2	class or type

Parameters

n	the value to reduce
m	the value to reduce `n` to a multiple

Returns: the possibly unmodified value

RoundDownToMultipleOf is effectively a floor function based on m. The function returns the value n - n%m. If n is a multiple of m, then the original value is returned.

Note: T1 and T2 should be unsigned arithmetic types. If T1 or T2 is signed, then the value should be non-negative. The library asserts in debug builds when practical, but allows you to perform the operation in release builds.

Definition at line 1354 of file misc.h.

◆ RoundUpToMultipleOf()

template<class T1 , class T2 >

T1 RoundUpToMultipleOf	(	const T1 &	n,
		const T2 &	m )

inline

Rounds a value up to a multiple of a second value.

Template Parameters

T1	class or type
T2	class or type

Parameters

n	the value to reduce
m	the value to reduce `n` to a multiple

Returns: the possibly unmodified value

RoundUpToMultipleOf is effectively a ceiling function based on m. The function returns the value n + n%m. If n is a multiple of m, then the original value is returned. If the value n would overflow, then an InvalidArgument exception is thrown.

Note: T1 and T2 should be unsigned arithmetic types. If T1 or T2 is signed, then the value should be non-negative. The library asserts in debug builds when practical, but allows you to perform the operation in release builds.

Definition at line 1384 of file misc.h.

◆ GetAlignmentOf()

template<class T >

unsigned int GetAlignmentOf ( )

inline

Returns the minimum alignment requirements of a type.

Template Parameters

T	class or type

Returns: the minimum alignment requirements of T, in bytes

Internally the function calls C++11's alignof if available. If not available, then the function uses compiler specific extensions such as __alignof and _alignof_. If an extension is not available, then the function uses sizeof(T).

Definition at line 1409 of file misc.h.

◆ IsAlignedOn()

bool IsAlignedOn	(	const void *	ptr,
		unsigned int	alignment )

inline

Determines whether ptr is aligned to a minimum value.

Parameters

ptr	the pointer being checked for alignment
alignment	the alignment value to test the pointer against

Returns: true if ptr is aligned on at least alignment boundary, false otherwise

Internally the function tests whether alignment is 1. If so, the function returns true. If not, then the function effectively performs a modular reduction and returns true if the residue is 0.

Definition at line 1436 of file misc.h.

◆ IsAligned()

template<class T >

bool IsAligned ( const void * ptr )

inline

Determines whether ptr is minimally aligned.

Template Parameters

T	class or type

Parameters

ptr	the pointer to check for alignment

Returns: true if ptr is aligned to at least T boundary, false otherwise

Internally the function calls IsAlignedOn with a second parameter of GetAlignmentOf<T>.

Definition at line 1450 of file misc.h.

◆ GetNativeByteOrder()

ByteOrder GetNativeByteOrder ( )

inline

Returns NativeByteOrder as an enumerated ByteOrder value.

Returns: LittleEndian if the native byte order is little-endian, and BigEndian if the native byte order is big-endian

NativeByteOrder is a typedef depending on the platform. If CRYPTOPP_LITTLE_ENDIAN is set in config.h, then GetNativeByteOrder returns LittleEndian. If CRYPTOPP_BIG_ENDIAN is set, then GetNativeByteOrder returns BigEndian.

Note: There are other byte orders besides little- and big-endian, and they include bi-endian and PDP-endian. If a system is neither little-endian nor big-endian, then a compile time error occurs.

Definition at line 1473 of file misc.h.

◆ NativeByteOrderIs()

bool NativeByteOrderIs ( ByteOrder order )

inline

Determines whether order follows native byte ordering.

Parameters

order the ordering being tested against native byte ordering

Returns: true if order follows native byte ordering, false otherwise

Definition at line 1481 of file misc.h.

◆ GetCipherDir()

template<class T >

CipherDir GetCipherDir ( const T & obj )

inline

Returns the direction the cipher is being operated.

Template Parameters

T	class or type

Parameters

obj	the cipher object being queried

Returns: ENCRYPTION if the cipher obj is being operated in its forward direction, DECRYPTION otherwise

A cipher can be operated in a "forward" direction (encryption) or a "reverse" direction (decryption). The operations do not have to be symmetric, meaning a second application of the transformation does not necessarily return the original message. That is, E(D(m)) may not equal E(E(m)); and D(E(m)) may not equal D(D(m)).

Definition at line 1497 of file misc.h.

◆ IncrementCounterByOne() [1/2]

void IncrementCounterByOne	(	byte *	inout,
		unsigned int	size )

inline

Performs an addition with carry on a block of bytes.

Parameters

inout	the byte block
size	the size of the block, in bytes

Performs an addition with carry by adding 1 on a block of bytes starting at the least significant byte. Once carry is 0, the function terminates and returns to the caller.

Note: The function is not constant time because it stops processing when the carry is 0.

Definition at line 1508 of file misc.h.

◆ IncrementCounterByOne() [2/2]

void IncrementCounterByOne	(	byte *	output,
		const byte *	input,
		unsigned int	size )

inline

Performs an addition with carry on a block of bytes.

Parameters

output	the destination block of bytes
input	the source block of bytes
size	the size of the block

Performs an addition with carry on a block of bytes starting at the least significant byte. Once carry is 0, the remaining bytes from input are copied to output using memcpy.

The function is close to near-constant time because it operates on all the bytes in the blocks.

Definition at line 1528 of file misc.h.

◆ ConditionalSwap()

template<class T >

void ConditionalSwap	(	bool	c,
		T &	a,
		T &	b )

inline

Performs a branch-less swap of values a and b if condition c is true.

Template Parameters

T	class or type

Parameters

c	the condition to perform the swap
a	the first value
b	the second value

Definition at line 1554 of file misc.h.

◆ ConditionalSwapPointers()

template<class T >

void ConditionalSwapPointers	(	bool	c,
		T &	a,
		T &	b )

inline

Performs a branch-less swap of pointers a and b if condition c is true.

Template Parameters

T	class or type

Parameters

c	the condition to perform the swap
a	the first pointer
b	the second pointer

Definition at line 1567 of file misc.h.

◆ SecureWipeBuffer() [1/5]

template<class T >

void SecureWipeBuffer	(	T *	buf,
		size_t	n )

Sets each element of an array to 0.

Template Parameters

T	class or type

Parameters

buf	an array of elements
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1584 of file misc.h.

◆ SecureWipeBuffer() [2/5]

template<>

void SecureWipeBuffer	(	byte *	buf,
		size_t	n )

inline

Sets each byte of an array to 0.

Parameters

buf	an array of bytes
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1602 of file misc.h.

◆ SecureWipeBuffer() [3/5]

template<>

void SecureWipeBuffer	(	word16 *	buf,
		size_t	n )

inline

Sets each 16-bit element of an array to 0.

Parameters

buf	an array of 16-bit words
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1617 of file misc.h.

◆ SecureWipeBuffer() [4/5]

template<>

void SecureWipeBuffer	(	word32 *	buf,
		size_t	n )

inline

Sets each 32-bit element of an array to 0.

Parameters

buf	an array of 32-bit words
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1632 of file misc.h.

◆ SecureWipeBuffer() [5/5]

template<>

void SecureWipeBuffer	(	word64 *	buf,
		size_t	n )

inline

Sets each 64-bit element of an array to 0.

Parameters

buf	an array of 64-bit words
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1647 of file misc.h.

◆ SecureWipeArray()

template<class T >

void SecureWipeArray	(	T *	buf,
		size_t	n )

inline

Sets each element of an array to 0.

Template Parameters

T	class or type

Parameters

buf	an array of elements
n	the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1700 of file misc.h.

◆ StringNarrow()

std::string StringNarrow	(	const wchar_t *	str,
		bool	throwOnError = true )

Converts a wide character C-string to a multibyte string.

Parameters

str	C-string consisting of wide characters
throwOnError	flag indicating the function should throw on error

Returns: str converted to a multibyte string or an empty string.

StringNarrow() converts a wide string to a narrow string using C++ std::wcstombs() under the executing thread's locale. A locale must be set before using this function, and it can be set with std::setlocale() if needed. Upon success, the converted string is returned.

Upon failure with throwOnError as false, the function returns an empty string. If throwOnError as true, the function throws an InvalidArgument() exception.

Note: If you try to convert, say, the Chinese character for "bone" from UTF-16 (0x9AA8) to UTF-8 (0xE9 0xAA 0xA8), then you must ensure the locale is available. If the locale is not available, then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception.

◆ StringWiden()

std::wstring StringWiden	(	const char *	str,
		bool	throwOnError = true )

Converts a multibyte C-string to a wide character string.

Parameters

str	C-string consisting of wide characters
throwOnError	flag indicating the function should throw on error

Returns: str converted to a multibyte string or an empty string.

StringWiden() converts a narrow string to a wide string using C++ std::mbstowcs() under the executing thread's locale. A locale must be set before using this function, and it can be set with std::setlocale() if needed. Upon success, the converted string is returned.

Upon failure with throwOnError as false, the function returns an empty string. If throwOnError as true, the function throws an InvalidArgument() exception.

Note: If you try to convert, say, the Chinese character for "bone" from UTF-8 (0xE9 0xAA 0xA8) to UTF-16 (0x9AA8), then you must ensure the locale is available. If the locale is not available, then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception.

◆ rotlConstant()

template<unsigned int R, class T >

T rotlConstant ( T x )

inline

Performs a left rotate.

Template Parameters

R	the number of bit positions to rotate the value
T	the word type

Parameters

x	the value to rotate

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

R must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotlMod if the rotate amount R is outside the range.

Use rotlConstant when the rotate amount is constant. The template function was added because Clang did not propagate the constant when passed as a function parameter. Clang's need for a constexpr meant rotlFixed failed to compile on occasion.

Note: rotlConstant attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 6.0

Definition at line 1757 of file misc.h.

◆ rotrConstant()

template<unsigned int R, class T >

T rotrConstant ( T x )

inline

Performs a right rotate.

Template Parameters

R	the number of bit positions to rotate the value
T	the word type

Parameters

x	the value to rotate

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

R must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotrMod if the rotate amount R is outside the range.

Use rotrConstant when the rotate amount is constant. The template function was added because Clang did not propagate the constant when passed as a function parameter. Clang's need for a constexpr meant rotrFixed failed to compile on occasion.

Note: rotrConstant attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Definition at line 1783 of file misc.h.

◆ rotlFixed()

template<class T >

T rotlFixed	(	T	x,
		unsigned int	y )

inline

Performs a left rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotlMod if the rotate amount y is outside the range.

Note: rotlFixed attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts. New code should use rotlConstant, which accepts the rotate amount as a template parameter.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 6.0

Definition at line 1808 of file misc.h.

◆ rotrFixed()

template<class T >

T rotrFixed	(	T	x,
		unsigned int	y )

inline

Performs a right rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotrMod if the rotate amount y is outside the range.

Note: rotrFixed attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts. New code should use rotrConstant, which accepts the rotate amount as a template parameter.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 3.0

Definition at line 1833 of file misc.h.

◆ rotlVariable()

template<class T >

T rotlVariable	(	T	x,
		unsigned int	y )

inline

Performs a left rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotlMod if the rotate amount y is outside the range.

Note: rotlVariable attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 3.0

Definition at line 1857 of file misc.h.

◆ rotrVariable()

template<class T >

T rotrVariable	(	T	x,
		unsigned int	y )

inline

Performs a right rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. Use rotrMod if the rotate amount y is outside the range.

Note: rotrVariable attempts to enlist a rotate IMM instruction because its often faster than a rotate REG. Immediate rotates can be up to three times faster than their register counterparts.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 3.0

Definition at line 1877 of file misc.h.

◆ rotlMod()

template<class T >

T rotlMod	(	T	x,
		unsigned int	y )

inline

Performs a left rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior.

Note: rotrVariable will use either rotate IMM or rotate REG.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 3.0

Definition at line 1894 of file misc.h.

◆ rotrMod()

template<class T >

T rotrMod	(	T	x,
		unsigned int	y )

inline

Performs a right rotate.

Template Parameters

T	the word type

Parameters

x	the value to rotate
y	the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior.

Note: rotrVariable will use either rotate IMM or rotate REG.

See also: rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since: Crypto++ 3.0

Definition at line 1910 of file misc.h.

◆ GetByte()

template<class T >

unsigned int GetByte	(	ByteOrder	order,
		T	value,
		unsigned int	index )

inline

Gets a byte from a value.

Parameters

order	the ByteOrder of the value
value	the value to retrieve the byte
index	the location of the byte to retrieve

Definition at line 2219 of file misc.h.

◆ ByteReverse() [1/6]

byte ByteReverse ( byte value )

inline

Reverses bytes in a 8-bit value.

Parameters

value the 8-bit value to reverse

Note: ByteReverse returns the value passed to it since there is nothing to reverse.

Definition at line 2231 of file misc.h.

◆ ByteReverse() [2/6]

word16 ByteReverse ( word16 value )

inline

Reverses bytes in a 16-bit value.

Parameters

value the 16-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function performs a 8-bit rotate on the word16.

Definition at line 2240 of file misc.h.

◆ ByteReverse() [3/6]

word32 ByteReverse ( word32 value )

inline

Reverses bytes in a 32-bit value.

Parameters

value the 32-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word32.

Definition at line 2255 of file misc.h.

◆ ByteReverse() [4/6]

word64 ByteReverse ( word64 value )

inline

Reverses bytes in a 64-bit value.

Parameters

value the 64-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word64.

Definition at line 2284 of file misc.h.

◆ ByteReverse() [5/6]

word128 ByteReverse ( word128 value )

inline

Reverses bytes in a 128-bit value.

Parameters

value the 128-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word128.

Note: word128 is available on some 64-bit platforms when the compiler supports it.

Since: Crypto++ 8.7

Definition at line 2309 of file misc.h.

◆ BitReverse() [1/5]

byte BitReverse ( byte value )

inline

Reverses bits in a 8-bit value.

Parameters

value the 8-bit value to reverse

BitReverse performs a combination of shifts on the byte.

Definition at line 2319 of file misc.h.

◆ BitReverse() [2/5]

word16 BitReverse ( word16 value )

inline

Reverses bits in a 16-bit value.

Parameters

value the 16-bit value to reverse

BitReverse performs a combination of shifts on the word16.

Definition at line 2329 of file misc.h.

◆ BitReverse() [3/5]

word32 BitReverse ( word32 value )

inline

Reverses bits in a 32-bit value.

Parameters

value the 32-bit value to reverse

BitReverse performs a combination of shifts on the word32.

Definition at line 2348 of file misc.h.

◆ BitReverse() [4/5]

word64 BitReverse ( word64 value )

inline

Reverses bits in a 64-bit value.

Parameters

value the 64-bit value to reverse

BitReverse performs a combination of shifts on the word64.

Definition at line 2367 of file misc.h.

◆ BitReverse() [5/5]

template<class T >

T BitReverse ( T value )

inline

Reverses bits in a value.

Parameters

value the value to reverse

The template overload of BitReverse operates on signed and unsigned values. Internally the size of T is checked, and then value is cast to a byte, word16, word32 or word64. After the cast, the appropriate BitReverse overload is called.

Note: word128 is available on some 64-bit platforms when the compiler supports it.

Since: Crypto++ 1.0, word128 since Crypto++ 8.7

Definition at line 2388 of file misc.h.

◆ ConditionalByteReverse() [1/2]

template<class T >

T ConditionalByteReverse	(	ByteOrder	order,
		T	value )

inline

Reverses bytes in a value depending upon endianness.

Template Parameters

T	the class or type

Parameters

order	the ByteOrder of the data
value	the value to conditionally reverse

Internally, the ConditionalByteReverse calls NativeByteOrderIs. If order matches native byte order, then the original value is returned. If not, then ByteReverse is called on the value before returning to the caller.

Definition at line 2417 of file misc.h.

◆ ByteReverse() [6/6]

template<class T >

void ByteReverse	(	T *	out,
		const T *	in,
		size_t	byteCount )

Reverses bytes in an element from an array of elements.

Template Parameters

T	the class or type

Parameters

out	the output array of elements
in	the input array of elements
byteCount	the total number of bytes in the array

Internally, ByteReverse visits each element in the in array calls ByteReverse on it, and writes the result to out.

ByteReverse does not process tail byes, or bytes that are not part of a full element. If T is int (and int is 4 bytes), then byteCount = 10 means only the first 2 elements or 8 bytes are reversed.

The following program should help illustrate the behavior.

vector<word32> v1, v2;

v1.push_back(1);
v1.push_back(2);
v1.push_back(3);
v1.push_back(4);

v2.resize(v1.size());
ByteReverse<word32>(&v2[0], &v1[0], 16);

cout << "V1: ";
for(unsigned int i = 0; i < v1.size(); i++)
  cout << std::hex << v1[i] << " ";
cout << endl;

cout << "V2: ";
for(unsigned int i = 0; i < v2.size(); i++)
  cout << std::hex << v2[i] << " ";
cout << endl;

The program above results in the following output.

V1: 00000001 00000002 00000003 00000004
V2: 01000000 02000000 03000000 04000000

See also: ConditionalByteReverse

Definition at line 2458 of file misc.h.

◆ ConditionalByteReverse() [2/2]

template<class T >

void ConditionalByteReverse	(	ByteOrder	order,
		T *	out,
		const T *	in,
		size_t	byteCount )

inline

Conditionally reverses bytes in an element from an array of elements.

Template Parameters

T	the class or type

Parameters

order	the ByteOrder of the data
out	the output array of elements
in	the input array of elements
byteCount	the byte count of the arrays

ConditionalByteReverse visits each element in the in array calls ByteReverse on it depending on the desired endianness, and writes the result to out.

ByteReverse does not process tail byes, or bytes that are not part of a full element. If T is int (and int is 4 bytes), then byteCount = 10 means only the first 2 elements or 8 bytes are reversed.

See also: ByteReverse

Definition at line 2484 of file misc.h.

◆ GetUserKey()

template<class T >

void GetUserKey	(	ByteOrder	order,
		T *	out,
		size_t	outlen,
		const byte *	in,
		size_t	inlen )

inline

Copy bytes in a buffer to an array of elements in big-endian order.

Template Parameters

T	the class or type

Parameters

order	the ByteOrder of the data
out	the output array of elements
outlen	the byte count of the array
in	the input array of elements
inlen	the byte count of the array

Definition at line 2500 of file misc.h.

◆ UnalignedGetWordNonTemplate() [1/5]

byte UnalignedGetWordNonTemplate	(	ByteOrder	order,
		const byte *	block,
		const byte *	unused )

inline

Retrieve a byte from an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned buffer
unused	dummy parameter

Returns: byte value

UnalignedGetWordNonTemplate accesses an unaligned buffer and returns a byte value.

Since: Crypto++ 1.0

Definition at line 2516 of file misc.h.

◆ UnalignedGetWordNonTemplate() [2/5]

word16 UnalignedGetWordNonTemplate	(	ByteOrder	order,
		const byte *	block,
		const word16 *	unused )

inline

Retrieve a word16 from an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned buffer
unused	dummy parameter

Returns: byte value

UnalignedGetWordNonTemplate accesses an unaligned buffer and returns a word16 value.

Since: Crypto++ 1.0

Definition at line 2529 of file misc.h.

◆ UnalignedGetWordNonTemplate() [3/5]

word32 UnalignedGetWordNonTemplate	(	ByteOrder	order,
		const byte *	block,
		const word32 *	unused )

inline

Retrieve a word32 from an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned buffer
unused	dummy parameter

Returns: byte value

UnalignedGetWordNonTemplate accesses an unaligned buffer and returns a word32 value.

Since: Crypto++ 1.0

Definition at line 2544 of file misc.h.

◆ UnalignedGetWordNonTemplate() [4/5]

word64 UnalignedGetWordNonTemplate	(	ByteOrder	order,
		const byte *	block,
		const word64 *	unused )

inline

Retrieve a word64 from an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned buffer
unused	dummy parameter

Returns: byte value

UnalignedGetWordNonTemplate accesses an unaligned buffer and returns a word64 value.

Since: Crypto++ 1.0

Definition at line 2559 of file misc.h.

◆ UnalignedGetWordNonTemplate() [5/5]

word128 UnalignedGetWordNonTemplate	(	ByteOrder	order,
		const byte *	block,
		const word128 *	unused )

inline

Retrieve a word128 from an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned buffer
unused	dummy parameter

Returns: byte value

UnalignedGetWordNonTemplate accesses an unaligned buffer and returns a word128 value.

Note: word128 is available on some 64-bit platforms when the compiler supports it.

Since: Crypto++ 8.7

Definition at line 2592 of file misc.h.

◆ UnalignedbyteNonTemplate() [1/5]

void UnalignedbyteNonTemplate	(	ByteOrder	order,
		byte *	block,
		byte	value,
		const byte *	xorBlock )

inline

Write a byte to an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned output buffer
value	byte value
xorBlock	optional unaligned xor buffer

UnalignedbyteNonTemplate writes a byte value to an unaligned buffer.

Since: Crypto++ 1.0

Definition at line 2640 of file misc.h.

◆ UnalignedbyteNonTemplate() [2/5]

void UnalignedbyteNonTemplate	(	ByteOrder	order,
		byte *	block,
		word16	value,
		const byte *	xorBlock )

inline

Write a word16 to an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned output buffer
value	word16 value
xorBlock	optional unaligned xor buffer

UnalignedbyteNonTemplate writes a word16 value to an unaligned buffer.

Since: Crypto++ 1.0

Definition at line 2653 of file misc.h.

◆ UnalignedbyteNonTemplate() [3/5]

void UnalignedbyteNonTemplate	(	ByteOrder	order,
		byte *	block,
		word32	value,
		const byte *	xorBlock )

inline

Write a word32 to an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned output buffer
value	word32 value
xorBlock	optional unaligned xor buffer

UnalignedbyteNonTemplate writes a word32 value to an unaligned buffer.

Since: Crypto++ 1.0

Definition at line 2690 of file misc.h.

◆ UnalignedbyteNonTemplate() [4/5]

void UnalignedbyteNonTemplate	(	ByteOrder	order,
		byte *	block,
		word64	value,
		const byte *	xorBlock )

inline

Write a word64 to an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned output buffer
value	word64 value
xorBlock	optional unaligned xor buffer

UnalignedbyteNonTemplate writes a word64 value to an unaligned buffer.

Since: Crypto++ 1.0

Definition at line 2735 of file misc.h.

◆ UnalignedbyteNonTemplate() [5/5]

void UnalignedbyteNonTemplate	(	ByteOrder	order,
		byte *	block,
		word128	value,
		const byte *	xorBlock )

inline

Write a word128 to an unaligned buffer.

Parameters

order	the ByteOrder of the data
block	an unaligned output buffer
value	word128 value
xorBlock	optional unaligned xor buffer

UnalignedbyteNonTemplate writes a word128 value to an unaligned buffer.

Note: word128 is available on some 64-bit platforms when the compiler supports it.

Since: Crypto++ 8.7

Definition at line 2798 of file misc.h.

◆ GetWord() [1/2]

template<class T >

T GetWord	(	bool	assumeAligned,
		ByteOrder	order,
		const byte *	block )

inline

Access a block of memory.

Template Parameters

T	class or type

Parameters

assumeAligned	flag indicating alignment
order	the ByteOrder of the data
block	the byte buffer to be processed

Returns: the word in the specified byte order

GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

An example of reading two word32 values from a block of memory is shown below. w will be 0x03020100.

  word32 w;
  byte buffer[4] = {0,1,2,3};
  w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

Definition at line 2906 of file misc.h.

◆ GetWord() [2/2]

template<class T >

void GetWord	(	bool	assumeAligned,
		ByteOrder	order,
		T &	result,
		const byte *	block )

inline

Access a block of memory.

Template Parameters

T	class or type

Parameters

assumeAligned	flag indicating alignment
order	the ByteOrder of the data
result	the word in the specified byte order
block	the byte buffer to be processed

GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

An example of reading two word32 values from a block of memory is shown below. w will be 0x03020100.

  word32 w;
  byte buffer[4] = {0,1,2,3};
  w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

Definition at line 2932 of file misc.h.

◆ PutWord()

template<class T >

void PutWord	(	bool	assumeAligned,
		ByteOrder	order,
		byte *	block,
		T	value,
		const byte *	xorBlock = NULL )

inline

Access a block of memory.

Template Parameters

T	class or type

Parameters

assumeAligned	flag indicating alignment
order	the ByteOrder of the data
block	the destination byte buffer
value	the word in the specified byte order
xorBlock	an optional byte buffer to xor

PutWord() provides alternate write access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

Definition at line 2948 of file misc.h.

◆ WordToString()

template<class T >

std::string WordToString	(	T	value,
		ByteOrder	order = BIG_ENDIAN_ORDER )

Convert a word to a string.

Template Parameters

T	class or type

Parameters

value	the word to convert
order	byte order

Returns: a string representing the value of the word

Definition at line 3065 of file misc.h.

◆ StringToWord()

template<class T >

T StringToWord	(	const std::string &	str,
		ByteOrder	order = BIG_ENDIAN_ORDER )

Convert a string to a word.

Template Parameters

T	class or type

Parameters

str	the string to convert
order	byte order

Returns: a word representing the value of the string

Definition at line 3079 of file misc.h.

◆ SafeRightShift()

template<unsigned int bits, class T >

T SafeRightShift ( T value )

inline

Safely right shift values when undefined behavior could occur.

Template Parameters

bits	the number of bit positions to shift the value
T	class or type

Parameters

value the value to right shift

Returns: the shifted value or 0

SafeRightShift safely shifts the value to the right when undefined behavior could occur under C/C++ rules. SafeRightShift will return the shifted value or 0 if undefined behavior would occur.

Definition at line 3163 of file misc.h.

◆ SafeLeftShift()

template<unsigned int bits, class T >

T SafeLeftShift ( T value )

inline

Safely left shift values when undefined behavior could occur.

Template Parameters

bits	the number of bit positions to shift the value
T	class or type

Parameters

value the value to left shift

Returns: the shifted value or 0

SafeLeftShift safely shifts the value to the left when undefined behavior could occur under C/C++ rules. SafeLeftShift will return the shifted value or 0 if undefined behavior would occur.

Definition at line 3177 of file misc.h.

◆ FindIfNot()

template<typename InputIt , typename T >

InputIt FindIfNot	(	InputIt	first,
		InputIt	last,
		const T &	value )

inline

Finds first element not in a range.

Template Parameters

InputIt	Input iterator type
T	class or type

Parameters

first	iterator to first element
last	iterator to last element
value	the value used as a predicate

Returns: iterator to the first element in the range that is not value

Definition at line 3190 of file misc.h.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SIZE_MAX

◆ CRYPTOPP_COMPILE_ASSERT

◆ COUNTOF

◆ MEMORY_BARRIER

◆ EnumToInt

◆ RETURN_IF_NONZERO

◆ GETBYTE

◆ CRYPTOPP_GET_BYTE_AS_BYTE

◆ CRYPTOPP_BLOCK_1

◆ CRYPTOPP_BLOCK_2

◆ CRYPTOPP_BLOCK_3

◆ CRYPTOPP_BLOCK_4

◆ CRYPTOPP_BLOCK_5

◆ CRYPTOPP_BLOCK_6

◆ CRYPTOPP_BLOCK_7

◆ CRYPTOPP_BLOCK_8

◆ CRYPTOPP_BLOCKS_END

Typedef Documentation

◆ NativeByteOrder

Function Documentation

◆ PtrAdd()

◆ PtrSub()

◆ PtrDiff()

◆ PtrByteDiff()

◆ BytePtr() [1/2]

◆ BytePtr() [2/2]

◆ ConstBytePtr() [1/2]

◆ ConstBytePtr() [2/2]

◆ BytePtrSize() [1/2]

◆ BytePtrSize() [2/2]

◆ memcpy_s()

◆ memmove_s()

◆ vec_swap()

◆ memset_z()

◆ STDMIN()

◆ STDMAX()

◆ UnsignedMin()

◆ SafeConvert() [1/13]

◆ SafeConvert() [2/13]

◆ SafeConvert() [3/13]

◆ SafeConvert() [4/13]

◆ SafeConvert() [5/13]

◆ SafeConvert() [6/13]

◆ SafeConvert() [7/13]

◆ SafeConvert() [8/13]

◆ SafeConvert() [9/13]

◆ SafeConvert() [10/13]

◆ SafeConvert() [11/13]

◆ SafeConvert() [12/13]

◆ SafeConvert() [13/13]

◆ IntToString()

◆ IntToString< word64 >()

◆ IntToString< Integer >()

◆ Parity()

◆ BytePrecision()

◆ BitPrecision()

◆ TrailingZeros() [1/2]

◆ TrailingZeros() [2/2]

◆ Crop()

◆ BitsToBytes()

◆ BytesToWords()

◆ BitsToWords()

◆ BitsToDwords()

◆ xorbuf() [1/2]

◆ xorbuf() [2/2]

◆ VerifyBufsEqual()

◆ IsPowerOf2()

◆ NumericLimitsMin() [1/2]

◆ NumericLimitsMax() [1/2]

◆ NumericLimitsMin() [2/2]

◆ NumericLimitsMax() [2/2]

◆ SaturatingSubtract()

◆ SaturatingSubtract1()

◆ ModPowerOf2()