Guard XOR of optional xorBlock. Updated documentation

3 files changed, 59 insertions, 23 deletions

diff --git a/cryptlib.h b/cryptlib.h
index 90ce1389..ce287217 100644
--- a/cryptlib.h
+++ b/cryptlib.h
@@ -1400,14 +1400,14 @@ public:
 

 		//! Input a 16-bit word for processing.

 		//! \param value the 16-bit value to be processed

-		//! \param order the  ByteOrder in which the word should be processed

+		//! \param order the ByteOrder of the value to be processed.

 		//! \param blocking specifies whether the object should block when processing input

 		//! \return the number of bytes that remain in the block (i.e., bytes not processed)

 		size_t PutWord16(word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);

 

 		//! Input a 32-bit word for processing.

 		//! \param value the 32-bit value to be processed.

-		//! \param order the  ByteOrder in which the word should be processed.

+		//! \param order the ByteOrder of the value to be processed.

 		//! \param blocking specifies whether the object should block when processing input.

 		//! \return the number of bytes that remain in the block (i.e., bytes not processed)

 		size_t PutWord32(word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);

@@ -1627,21 +1627,21 @@ public:
 

 		//! \brief Retrieve a 16-bit word

 		//! \param value the 16-bit value to be retrieved

-		//! \param order the  ByteOrder in which the word should be retrieved

+		//! \param order the ByteOrder of the value to be processed.

 		//! \return the number of bytes consumed during the call.

 		//! \details Use the return value of  GetWord16 to detect short reads.

 		size_t GetWord16(word16 &value, ByteOrder order=BIG_ENDIAN_ORDER);

 

 		//! \brief Retrieve a 32-bit word

 		//! \param value the 32-bit value to be retrieved

-		//! \param order the  ByteOrder in which the word should be retrieved

+		//! \param order the ByteOrder of the value to be processed.

 		//! \return the number of bytes consumed during the call.

 		//! \details Use the return value of  GetWord16 to detect short reads.

 		size_t GetWord32(word32 &value, ByteOrder order=BIG_ENDIAN_ORDER);

 

 		//! \brief Peek a 16-bit word

 		//! \param value the 16-bit value to be retrieved

-		//! \param order the  ByteOrder in which the word should be retrieved

+		//! \param order the ByteOrder of the value to be processed.

 		//! \return the number of bytes consumed during the call.

 		//! \details Peek does not consume bytes in the stream. Use the return value

 		//!    of  GetWord16 to detect short reads.

@@ -1649,7 +1649,7 @@ public:
 

 		//! \brief Peek a 32-bit word

 		//! \param value the 32-bit value to be retrieved

-		//! \param order the  ByteOrder in which the word should be retrieved

+		//! \param order the ByteOrder of the value to be processed.

 		//! \return the number of bytes consumed during the call.

 		//! \details Peek does not consume bytes in the stream. Use the return value

 		//!    of  GetWord16 to detect short reads.

@@ -1900,7 +1900,7 @@ public:
 		//! \brief Input a 16-bit word for processing on a channel.

 		//! \param channel the channel to process the data.

 		//! \param value the 16-bit value to be processed.

-		//! \param order the  ByteOrder in which the word should be processed.

+		//! \param order the ByteOrder of the value to be processed.

 		//! \param blocking specifies whether the object should block when processing input.

 		//! \return 0 indicates all bytes were processed during the call. Non-0 indicates the

 		//!   number of bytes that were \a not processed.

@@ -1909,7 +1909,7 @@ public:
 		//! \brief Input a 32-bit word for processing on a channel.

 		//! \param channel the channel to process the data.

 		//! \param value the 32-bit value to be processed.

-		//! \param order the  ByteOrder in which the word should be processed.

+		//! \param order the ByteOrder of the value to be processed.

 		//! \param blocking specifies whether the object should block when processing input.

 		//! \return 0 indicates all bytes were processed during the call. Non-0 indicates the

 		//!   number of bytes that were \a not processed.

diff --git a/integer.h b/integer.h
index f289779a..e59b0a56 100644
--- a/integer.h
+++ b/integer.h
@@ -115,7 +115,7 @@ public:
 

 		//! \brief Convert from a C-string

 		//! \param str C-string value

-		//! \param order byte order

+		//! \param order the ByteOrder of the string to be processed

 		//! \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case

 		//!   insensitive suffix of 'h', 'o', or 'b'.  No suffix means base 10.

 		//! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian

@@ -124,7 +124,7 @@ public:
 

 		//! \brief Convert from a wide C-string

 		//! \param str wide C-string value

-		//! \param order byte order

+		//! \param order the ByteOrder of the string to be processed

 		//! \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case

 		//!   insensitive suffix of 'h', 'o', or 'b'.  No suffix means base 10.

 		//! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian

@@ -135,7 +135,7 @@ public:
 		//! \param encodedInteger big-endian byte array

 		//! \param byteCount length of the byte array

 		//! \param sign enumeration indicating Signedness

-		//! \param order byte order

+		//! \param order the ByteOrder of the array to be processed

 		//! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian

 		//!   integers with curve25519, Poly1305 and Microsoft CAPI.

 		Integer(const byte *encodedInteger, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order = BIG_ENDIAN_ORDER);

@@ -144,7 +144,7 @@ public:
 		//! \param bt BufferedTransformation object with big-endian byte array

 		//! \param byteCount length of the byte array

 		//! \param sign enumeration indicating Signedness

-		//! \param order byte order

+		//! \param order the ByteOrder of the data to be processed

 		//! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian

 		//!   integers with curve25519, Poly1305 and Microsoft CAPI.

 		Integer(BufferedTransformation &bt, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order = BIG_ENDIAN_ORDER);

diff --git a/misc.h b/misc.h
index f36a5bce..ccbb5db9 100644
--- a/misc.h
+++ b/misc.h
@@ -1853,7 +1853,7 @@ inline T BitReverse(T value)
 

 //! \brief Reverses bytes in a value depending upon endianess

 //! \tparam T the class or type

-//! \param order the ByteOrder the data is represented

+//! \param order the ByteOrder of the data

 //! \param value the value to conditionally reverse

 //! \details Internally, the ConditionalByteReverse calls NativeByteOrderIs.

 //!   If order matches native byte order, then the original value is returned.

@@ -1910,7 +1910,7 @@ void ByteReverse(T *out, const T *in, size_t byteCount)
 

 //! \brief Conditionally reverses bytes in an element from an array of elements

 //! \tparam T the class or type

-//! \param order the ByteOrder the data is represented

+//! \param order the ByteOrder of the data

 //! \param out the output array of elements

 //! \param in the input array of elements

 //! \param byteCount the byte count of the arrays

@@ -2113,15 +2113,25 @@ inline void UnalignedbyteNonTemplate(ByteOrder order, byte *block, word64 value,
 }

 #endif	// #ifndef CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS

 

+//! \brief Access a block of memory

+//! \tparam T class or type

+//! \param assumeAligned flag indicating alignment

+//! \param order the ByteOrder of the data

+//! \param block the byte buffer to be processed

+//! \returns the word in the specified byte order

+//! \details 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.

+//! \details An example of reading two word32 values from a block of memory is shown below. <tt>w</tt>

+//!   will be <tt>0x03020100</tt>.

+//! <pre>

+//!    word32 w;

+//!    byte buffer[4] = {0,1,2,3};

+//!    w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

+//! </pre>

 template <class T>

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

 {

-//#ifndef CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS

-//	if (!assumeAligned)

-//		return UnalignedGetWordNonTemplate(order, block, (T*)NULL);

-//	CRYPTOPP_ASSERT(IsAligned<T>(block));

-//#endif

-//	return ConditionalByteReverse(order, *reinterpret_cast<const T *>(block));

 	CRYPTOPP_UNUSED(assumeAligned);

 #ifdef CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS

 	return ConditionalByteReverse(order, *reinterpret_cast<const T *>((const void *)block));

@@ -2132,12 +2142,38 @@ inline T GetWord(bool assumeAligned, ByteOrder order, const byte *block)
 #endif

 }

 

+//! \brief Access a block of memory

+//! \tparam T class or type

+//! \param assumeAligned flag indicating alignment

+//! \param order the ByteOrder of the data

+//! \param result the word in the specified byte order

+//! \param block the byte buffer to be processed

+//! \details 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.

+//! \details An example of reading two word32 values from a block of memory is shown below. <tt>w</tt>

+//!   will be <tt>0x03020100</tt>.

+//! <pre>

+//!    word32 w;

+//!    byte buffer[4] = {0,1,2,3};

+//!    w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

+//! </pre>

 template <class T>

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

 {

 	result = GetWord<T>(assumeAligned, order, block);

 }

 

+//! \brief Access a block of memory

+//! \tparam T class or type

+//! \param assumeAligned flag indicating alignment

+//! \param order the ByteOrder of the data

+//! \param block the destination byte buffer

+//! \param value the word in the specified byte order

+//! \param xorBlock an optional byte buffer to xor

+//! \details 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.

 template <class T>

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

 {

@@ -2145,10 +2181,10 @@ inline void PutWord(bool assumeAligned, ByteOrder order, byte *block, T value, c
 #ifdef CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS

 	*reinterpret_cast<T *>((void *)block) = ConditionalByteReverse(order, value) ^ (xorBlock ? *reinterpret_cast<const T *>((const void *)xorBlock) : 0);

 #else

-	T t1, t2 = 0;

+	T t1, t2;

 	t1 = ConditionalByteReverse(order, value);

-	if (xorBlock) memcpy(&t2, xorBlock, sizeof(T));

-	memmove(block, &(t1 ^= t2), sizeof(T));

+	if (xorBlock) {memcpy(&t2, xorBlock, sizeof(T)); t1 ^= t2;}

+	memcpy(block, &t1, sizeof(T));

 #endif

 }