propagate from branch 'net.randombit.botan' (head 647eeb4f4cf8fa4cf487cdc463d48f09fe18658e)

            to branch 'net.randombit.botan.c++0x' (head 2539675db91883b11895ddc5244721e93c413321)

8 files changed, 324 insertions, 33 deletions

diff --git a/src/utils/bit_ops.h b/src/utils/bit_ops.h
index c02ec536f..36bac9f73 100644
--- a/src/utils/bit_ops.h
+++ b/src/utils/bit_ops.h
@@ -12,9 +12,10 @@
 
 namespace Botan {
 
-/*
-* Return true iff arg is 2**n for some n > 0
-* T should be an unsigned integer type
+/**
+* Power of 2 test. T should be an unsigned integer type
+* @param arg an integer value
+* @return true iff arg is 2^n for some n > 0
 */
 template<typename T>
 inline bool power_of_2(T arg)
@@ -22,9 +23,11 @@ inline bool power_of_2(T arg)
    return ((arg != 0 && arg != 1) && ((arg & (arg-1)) == 0));
    }
 
-/*
+/**
 * Return the index of the highest set bit
 * T is an unsigned integer type
+* @param n an integer value
+* @return index of the highest set bit in n
 */
 template<typename T>
 inline u32bit high_bit(T n)
@@ -35,8 +38,11 @@ inline u32bit high_bit(T n)
    return 0;
    }
 
-/*
+/**
 * Return the index of the lowest set bit
+* T is an unsigned integer type
+* @param n an integer value
+* @return index of the lowest set bit in n
 */
 template<typename T>
 inline u32bit low_bit(T n)
@@ -47,8 +53,10 @@ inline u32bit low_bit(T n)
    return 0;
    }
 
-/*
+/**
 * Return the number of significant bytes in n
+* @param n an integer value
+* @return number of significant bytes in n
 */
 template<typename T>
 inline u32bit significant_bytes(T n)
@@ -59,8 +67,10 @@ inline u32bit significant_bytes(T n)
    return 0;
    }
 
-/*
-* Return the Hamming weight of n
+/**
+* Compute Hamming weights
+* @param n an integer value
+* @return number of bits in n set to 1
 */
 template<typename T>
 inline u32bit hamming_weight(T n)
@@ -74,8 +84,10 @@ inline u32bit hamming_weight(T n)
    return weight;
    }
 
-/*
+/**
 * Count the trailing zero bits in n
+* @param n an integer value
+* @return maximum x st 2^x divides n
 */
 template<typename T>
 inline u32bit ctz(T n)
diff --git a/src/utils/cpuid.h b/src/utils/cpuid.h
index a41e932fb..dbac89455 100644
--- a/src/utils/cpuid.h
+++ b/src/utils/cpuid.h
@@ -18,15 +18,6 @@ namespace Botan {
 class BOTAN_DLL CPUID
    {
    public:
-      enum CPUID_bits {
-         CPUID_RDTSC_BIT = 4,
-         CPUID_SSE2_BIT = 26,
-         CPUID_SSSE3_BIT = 41,
-         CPUID_SSE41_BIT = 51,
-         CPUID_SSE42_BIT = 52,
-         CPUID_INTEL_AES_BIT = 57
-      };
-
       /**
       * Return a best guess of the cache line size
       */
@@ -73,6 +64,15 @@ class BOTAN_DLL CPUID
       */
       static bool has_altivec();
    private:
+      enum CPUID_bits {
+         CPUID_RDTSC_BIT = 4,
+         CPUID_SSE2_BIT = 26,
+         CPUID_SSSE3_BIT = 41,
+         CPUID_SSE41_BIT = 51,
+         CPUID_SSE42_BIT = 52,
+         CPUID_INTEL_AES_BIT = 57
+      };
+
       static u64bit x86_processor_flags();
    };
 
diff --git a/src/utils/get_byte.h b/src/utils/get_byte.h
index fce87af83..7eedbd783 100644
--- a/src/utils/get_byte.h
+++ b/src/utils/get_byte.h
@@ -12,8 +12,11 @@
 
 namespace Botan {
 
-/*
-* Byte Extraction Function
+/**
+* Byte extraction
+* @param byte_num which byte to extract, 0 == highest byte
+* @param input the value to extract from
+* @return byte byte_num of input
 */
 template<typename T> inline byte get_byte(u32bit byte_num, T input)
    {
diff --git a/src/utils/loadstor.h b/src/utils/loadstor.h
index ffd27540d..e812fca4e 100644
--- a/src/utils/loadstor.h
+++ b/src/utils/loadstor.h
@@ -38,14 +38,25 @@
 
 namespace Botan {
 
-/*
-* Byte to Word Conversions
+/**
+* Make a u16bit from two bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @return i0 || i1
 */
 inline u16bit make_u16bit(byte i0, byte i1)
    {
    return ((static_cast<u16bit>(i0) << 8) | i1);
    }
 
+/**
+* Make a u32bit from four bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @param i2 the third byte
+* @param i3 the fourth byte
+* @return i0 || i1 || i2 || i3
+*/
 inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3)
    {
    return ((static_cast<u32bit>(i0) << 24) |
@@ -54,6 +65,18 @@ inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3)
            (static_cast<u32bit>(i3)));
    }
 
+/**
+* Make a u32bit from eight bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @param i2 the third byte
+* @param i3 the fourth byte
+* @param i4 the fifth byte
+* @param i5 the sixth byte
+* @param i6 the seventh byte
+* @param i7 the eighth byte
+* @return i0 || i1 || i2 || i3 || i4 || i5 || i6 || i7
+*/
 inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3,
                           byte i4, byte i5, byte i6, byte i7)
     {
@@ -67,8 +90,11 @@ inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3,
            (static_cast<u64bit>(i7)));
     }
 
-/*
-* Endian-Specific Word Loading Operations
+/**
+* Load a big-endian word
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th T of in, as a big-endian value
 */
 template<typename T>
 inline T load_be(const byte in[], u32bit off)
@@ -80,6 +106,12 @@ inline T load_be(const byte in[], u32bit off)
    return out;
    }
 
+/**
+* Load a little-endian word
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th T of in, as a litte-endian value
+*/
 template<typename T>
 inline T load_le(const byte in[], u32bit off)
    {
@@ -90,6 +122,12 @@ inline T load_le(const byte in[], u32bit off)
    return out;
    }
 
+/**
+* Load a big-endian u16bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u16bit of in, as a big-endian value
+*/
 template<>
 inline u16bit load_be<u16bit>(const byte in[], u32bit off)
    {
@@ -101,6 +139,12 @@ inline u16bit load_be<u16bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u16bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u16bit of in, as a little-endian value
+*/
 template<>
 inline u16bit load_le<u16bit>(const byte in[], u32bit off)
    {
@@ -112,6 +156,12 @@ inline u16bit load_le<u16bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a big-endian u32bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u32bit of in, as a big-endian value
+*/
 template<>
 inline u32bit load_be<u32bit>(const byte in[], u32bit off)
    {
@@ -123,6 +173,12 @@ inline u32bit load_be<u32bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u32bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u32bit of in, as a little-endian value
+*/
 template<>
 inline u32bit load_le<u32bit>(const byte in[], u32bit off)
    {
@@ -134,6 +190,12 @@ inline u32bit load_le<u32bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a big-endian u64bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u64bit of in, as a big-endian value
+*/
 template<>
 inline u64bit load_be<u64bit>(const byte in[], u32bit off)
    {
@@ -146,6 +208,12 @@ inline u64bit load_be<u64bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u64bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u64bit of in, as a little-endian value
+*/
 template<>
 inline u64bit load_le<u64bit>(const byte in[], u32bit off)
    {
@@ -158,6 +226,12 @@ inline u64bit load_le<u64bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load two little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[], T& x0, T& x1)
    {
@@ -165,6 +239,14 @@ inline void load_le(const byte in[], T& x0, T& x1)
    x1 = load_le<T>(in, 1);
    }
 
+/**
+* Load four little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[],
                     T& x0, T& x1, T& x2, T& x3)
@@ -175,6 +257,18 @@ inline void load_le(const byte in[],
    x3 = load_le<T>(in, 3);
    }
 
+/**
+* Load eight little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+* @param x4 where the fifth word will be written
+* @param x5 where the sixth word will be written
+* @param x6 where the seventh word will be written
+* @param x7 where the eighth word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[],
                     T& x0, T& x1, T& x2, T& x3,
@@ -190,6 +284,12 @@ inline void load_le(const byte in[],
    x7 = load_le<T>(in, 7);
    }
 
+/**
+* Load a variable number of little-endian words
+* @param out the output array of words
+* @param in the input array of bytes
+* @param count how many words are in in
+*/
 template<typename T>
 inline void load_le(T out[],
                     const byte in[],
@@ -215,6 +315,12 @@ inline void load_le(T out[],
 #endif
    }
 
+/**
+* Load two big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[], T& x0, T& x1)
    {
@@ -222,6 +328,14 @@ inline void load_be(const byte in[], T& x0, T& x1)
    x1 = load_be<T>(in, 1);
    }
 
+/**
+* Load four big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[],
                     T& x0, T& x1, T& x2, T& x3)
@@ -232,6 +346,18 @@ inline void load_be(const byte in[],
    x3 = load_be<T>(in, 3);
    }
 
+/**
+* Load eight big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+* @param x4 where the fifth word will be written
+* @param x5 where the sixth word will be written
+* @param x6 where the seventh word will be written
+* @param x7 where the eighth word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[],
                     T& x0, T& x1, T& x2, T& x3,
@@ -247,6 +373,12 @@ inline void load_be(const byte in[],
    x7 = load_be<T>(in, 7);
    }
 
+/**
+* Load a variable number of big-endian words
+* @param out the output array of words
+* @param in the input array of bytes
+* @param count how many words are in in
+*/
 template<typename T>
 inline void load_be(T out[],
                     const byte in[],
@@ -272,8 +404,10 @@ inline void load_be(T out[],
 #endif
    }
 
-/*
-* Endian-Specific Word Storing Operations
+/**
+* Store a big-endian u16bit
+* @param in the input u16bit
+* @param out the byte array to write to
 */
 inline void store_be(u16bit in, byte out[2])
    {
@@ -285,6 +419,11 @@ inline void store_be(u16bit in, byte out[2])
 #endif
    }
 
+/**
+* Store a little-endian u16bit
+* @param in the input u16bit
+* @param out the byte array to write to
+*/
 inline void store_le(u16bit in, byte out[2])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -295,6 +434,11 @@ inline void store_le(u16bit in, byte out[2])
 #endif
    }
 
+/**
+* Store a big-endian u32bit
+* @param in the input u32bit
+* @param out the byte array to write to
+*/
 inline void store_be(u32bit in, byte out[4])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -307,6 +451,11 @@ inline void store_be(u32bit in, byte out[4])
 #endif
    }
 
+/**
+* Store a little-endian u32bit
+* @param in the input u32bit
+* @param out the byte array to write to
+*/
 inline void store_le(u32bit in, byte out[4])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -319,6 +468,11 @@ inline void store_le(u32bit in, byte out[4])
 #endif
    }
 
+/**
+* Store a big-endian u64bit
+* @param in the input u64bit
+* @param out the byte array to write to
+*/
 inline void store_be(u64bit in, byte out[8])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -335,6 +489,11 @@ inline void store_be(u64bit in, byte out[8])
 #endif
    }
 
+/**
+* Store a little-endian u64bit
+* @param in the input u64bit
+* @param out the byte array to write to
+*/
 inline void store_le(u64bit in, byte out[8])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -351,6 +510,12 @@ inline void store_le(u64bit in, byte out[8])
 #endif
    }
 
+/**
+* Store two little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1)
    {
@@ -358,6 +523,12 @@ inline void store_le(byte out[], T x0, T x1)
    store_le(x1, out + (1 * sizeof(T)));
    }
 
+/**
+* Store two big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1)
    {
@@ -365,6 +536,14 @@ inline void store_be(byte out[], T x0, T x1)
    store_be(x1, out + (1 * sizeof(T)));
    }
 
+/**
+* Store four little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1, T x2, T x3)
    {
@@ -374,6 +553,14 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3)
    store_le(x3, out + (3 * sizeof(T)));
    }
 
+/**
+* Store four big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1, T x2, T x3)
    {
@@ -383,6 +570,18 @@ inline void store_be(byte out[], T x0, T x1, T x2, T x3)
    store_be(x3, out + (3 * sizeof(T)));
    }
 
+/**
+* Store eight little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+* @param x4 the fifth word
+* @param x5 the sixth word
+* @param x6 the seventh word
+* @param x7 the eighth word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1, T x2, T x3,
                                  T x4, T x5, T x6, T x7)
@@ -397,6 +596,18 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3,
    store_le(x7, out + (7 * sizeof(T)));
    }
 
+/**
+* Store eight big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+* @param x4 the fifth word
+* @param x5 the sixth word
+* @param x6 the seventh word
+* @param x7 the eighth word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1, T x2, T x3,
                                  T x4, T x5, T x6, T x7)
diff --git a/src/utils/mem_ops.h b/src/utils/mem_ops.h
index 0fcf34ba8..503be90b3 100644
--- a/src/utils/mem_ops.h
+++ b/src/utils/mem_ops.h
@@ -13,18 +13,47 @@
 
 namespace Botan {
 
-/*
-* Memory Manipulation Functions
+/**
+* Copy memory
+* @param out the destination array
+* @param in the source array
+* @param n the number of elements of in/out
 */
 template<typename T> inline void copy_mem(T* out, const T* in, u32bit n)
-   { std::memmove(out, in, sizeof(T)*n); }
+   {
+   std::memmove(out, in, sizeof(T)*n);
+   }
 
+/**
+* Zeroize memory
+* @param ptr a pointer to an array
+* @param n the number of Ts pointed to by ptr
+*/
 template<typename T> inline void clear_mem(T* ptr, u32bit n)
-   { if(n) std::memset(ptr, 0, sizeof(T)*n); }
+   {
+   if(n) // avoid glibc warning if n == 0
+      std::memset(ptr, 0, sizeof(T)*n);
+   }
 
-template<typename T> inline void set_mem(T* ptr, u32bit n, byte val)
-   { std::memset(ptr, val, sizeof(T)*n); }
+/**
+* Set memory to a fixed value
+* @param ptr a pointer to an array
+* @param n the number of Ts pointed to by ptr
+* @param val the value to set each byte to
+*/
+template<typename T>
+inline void set_mem(T* ptr, u32bit n, byte val)
+   {
+   std::memset(ptr, val, sizeof(T)*n);
+   }
 
+/**
+* Memory comparison, input insensitive
+* @param p1 a pointer to an array
+* @param p2 a pointer to another array
+* @param n the number of Ts in p1 and p2
+* @return true iff p1[i] == p2[i] forall i in [0...n)
+*/
 template<typename T> inline bool same_mem(const T* p1, const T* p2, u32bit n)
    {
    bool is_same = true;
diff --git a/src/utils/time.cpp b/src/utils/time.cpp
index 4fea41c52..d5b74828b 100644
--- a/src/utils/time.cpp
+++ b/src/utils/time.cpp
@@ -35,7 +35,7 @@ namespace Botan {
 
 namespace {
 
-/**
+/*
 * Combine a two time values into a single one
 */
 u64bit combine_timers(u32bit seconds, u32bit parts, u32bit parts_hz)
diff --git a/src/utils/time.h b/src/utils/time.h
index c7a7e0e1a..516efba3e 100644
--- a/src/utils/time.h
+++ b/src/utils/time.h
@@ -18,11 +18,24 @@ namespace Botan {
 */
 struct BOTAN_DLL calendar_point
    {
+   /** The year */
    u32bit year;
+
+   /** The month, 1 through 12 for Jan to Dec */
    byte month;
+
+   /** The day of the month, 1 through 31 (or 28 or 30 based on month */
    byte day;
+
+   /** Hour in 24-hour form, 0 to 23 */
    byte hour;
+
+   /** Minutes in the hour, 0 to 60 */
    byte minutes;
+
+   /** Seconds in the minute, 0 to 60, but might be slightly
+       larger to deal with leap seconds on some systems
+   */
    byte seconds;
 
    /**
diff --git a/src/utils/types.h b/src/utils/types.h
index 304628d02..58fdb5ff8 100644
--- a/src/utils/types.h
+++ b/src/utils/types.h
@@ -10,14 +10,34 @@
 
 #include <botan/build.h>
 
+/**
+* The primary namespace for the botan library
+*/
 namespace Botan {
 
+/**
+* Typedef representing an unsigned 8-bit quantity
+*/
 typedef unsigned char byte;
+
+/**
+* Typedef representing an unsigned 16-bit quantity
+*/
 typedef unsigned short u16bit;
+
+/**
+* Typedef representing an unsigned 32-bit quantity
+*/
 typedef unsigned int u32bit;
 
+/**
+* Typedef representing a signed 32-bit quantity
+*/
 typedef signed int s32bit;
 
+/**
+* Typedef representing an unsigned 64-bit quantity
+*/
 #if defined(_MSC_VER) || defined(__BORLANDC__)
    typedef unsigned __int64 u64bit;
 #elif defined(__KCC)
@@ -28,6 +48,9 @@ typedef signed int s32bit;
    typedef unsigned long long u64bit;
 #endif
 
+/**
+* A default buffer size; typically a memory page
+*/
 static const u32bit DEFAULT_BUFFERSIZE = BOTAN_DEFAULT_BUFFER_SIZE;
 
 }