propagate from branch 'net.randombit.botan' (head 294e2082ce9231d6165276e2f2a4153a0116aca3)

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

36 files changed, 175 insertions, 95 deletions

diff --git a/src/block/aes/aes.cpp b/src/block/aes/aes.cpp
index df2674f34..bf9a4198b 100644
--- a/src/block/aes/aes.cpp
+++ b/src/block/aes/aes.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AES
 * (C) 1999-2009 Jack Lloyd
 *
@@ -409,7 +409,7 @@ const u32bit TD[1024] = {
 
 }
 
-/**
+/*
 * AES Encryption
 */
 void AES::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -503,7 +503,7 @@ void AES::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES Decryption
 */
 void AES::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -583,7 +583,7 @@ void AES::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES Key Schedule
 */
 void AES::key_schedule(const byte key[], u32bit length)
@@ -636,7 +636,7 @@ void AES::key_schedule(const byte key[], u32bit length)
    DK.copy(XDK, length + 24);
    }
 
-/**
+/*
 * AES Byte Substitution
 */
 u32bit AES::S(u32bit input)
@@ -645,7 +645,7 @@ u32bit AES::S(u32bit input)
                       SE[get_byte(2, input)], SE[get_byte(3, input)]);
    }
 
-/**
+/*
 * AES Constructor
 */
 AES::AES(u32bit key_size) : BlockCipher(16, key_size)
@@ -655,7 +655,7 @@ AES::AES(u32bit key_size) : BlockCipher(16, key_size)
    ROUNDS = (key_size / 4) + 6;
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES::clear()
diff --git a/src/block/aes/aes.h b/src/block/aes/aes.h
index 45026f732..8770bdb35 100644
--- a/src/block/aes/aes.h
+++ b/src/block/aes/aes.h
@@ -1,4 +1,4 @@
-/**
+/*
 * AES
 * (C) 1999-2009 Jack Lloyd
 *
@@ -26,7 +26,12 @@ class BOTAN_DLL AES : public BlockCipher
       BlockCipher* clone() const { return new AES; }
 
       AES() : BlockCipher(16, 16, 32, 8) { ROUNDS = 14; }
-      AES(u32bit);
+
+      /**
+      * AES fixed to a particular key_size (16, 24, or 32 bytes)
+      * @param key_size the chosen fixed key size
+      */
+      AES(u32bit key_size);
    private:
       void key_schedule(const byte[], u32bit);
       static u32bit S(u32bit);
diff --git a/src/block/aes_intel/aes_intel.cpp b/src/block/aes_intel/aes_intel.cpp
index 3d3683d7d..211bb3b47 100644
--- a/src/block/aes_intel/aes_intel.cpp
+++ b/src/block/aes_intel/aes_intel.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AES using Intel's AES-NI instructions
 * (C) 2009 Jack Lloyd
 *
@@ -100,7 +100,7 @@ __m128i aes_256_key_expansion(__m128i key, __m128i key2)
       B3 = _mm_aesdeclast_si128(B3, K);         \
       } while(0)
 
-/**
+/*
 * AES-128 Encryption
 */
 void AES_128_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -176,7 +176,7 @@ void AES_128_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-128 Decryption
 */
 void AES_128_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -252,7 +252,7 @@ void AES_128_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-128 Key Schedule
 */
 void AES_128_Intel::key_schedule(const byte key[], u32bit)
@@ -301,7 +301,7 @@ void AES_128_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 10, K0);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_128_Intel::clear()
@@ -310,7 +310,7 @@ void AES_128_Intel::clear()
    DK.clear();
    }
 
-/**
+/*
 * AES-192 Encryption
 */
 void AES_192_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -392,7 +392,7 @@ void AES_192_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-192 Decryption
 */
 void AES_192_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -474,7 +474,7 @@ void AES_192_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-192 Key Schedule
 */
 void AES_192_Intel::key_schedule(const byte key[], u32bit)
@@ -517,7 +517,7 @@ void AES_192_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 12, EK_mm[0]);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_192_Intel::clear()
@@ -526,7 +526,7 @@ void AES_192_Intel::clear()
    DK.clear();
    }
 
-/**
+/*
 * AES-256 Encryption
 */
 void AES_256_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -614,7 +614,7 @@ void AES_256_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-256 Decryption
 */
 void AES_256_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -702,7 +702,7 @@ void AES_256_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-256 Key Schedule
 */
 void AES_256_Intel::key_schedule(const byte key[], u32bit)
@@ -767,7 +767,7 @@ void AES_256_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 14, K0);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_256_Intel::clear()
diff --git a/src/block/aes_intel/aes_intel.h b/src/block/aes_intel/aes_intel.h
index a3ebf153b..592fb7faa 100644
--- a/src/block/aes_intel/aes_intel.h
+++ b/src/block/aes_intel/aes_intel.h
@@ -1,4 +1,4 @@
-/**
+/*
 * AES using Intel's AES-NI instructions
 * (C) 2009 Jack Lloyd
 *
@@ -18,7 +18,7 @@ namespace Botan {
 class BOTAN_DLL AES_128_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
@@ -40,7 +40,7 @@ class BOTAN_DLL AES_128_Intel : public BlockCipher
 class BOTAN_DLL AES_192_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
@@ -62,7 +62,7 @@ class BOTAN_DLL AES_192_Intel : public BlockCipher
 class BOTAN_DLL AES_256_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/aes_intel/info.txt b/src/block/aes_intel/info.txt
index 6e67a6ed9..8bf0f07ee 100644
--- a/src/block/aes_intel/info.txt
+++ b/src/block/aes_intel/info.txt
@@ -2,7 +2,7 @@ define AES_INTEL
 
 load_on auto
 
-need_isa aes_ni
+need_isa aes-ni
 
 <requires>
 aes_isa_eng
diff --git a/src/block/block_cipher.h b/src/block/block_cipher.h
index 2d9198c58..c1b58996e 100644
--- a/src/block/block_cipher.h
+++ b/src/block/block_cipher.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Block Cipher Base Class
 * (C) 1999-2009 Jack Lloyd
 *
@@ -19,14 +19,38 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
    {
    public:
       /**
+      * BlockCipher constructor
+      * @param block_size the size of blocks this cipher processes
+      * @param key_min the minimum key size
+      * @param key_max the maximum key size
+      * @param key_mod the modulo restriction on the key size
+      */
+      BlockCipher(u32bit block_size,
+                  u32bit key_min,
+                  u32bit key_max = 0,
+                  u32bit key_mod = 1) :
+         SymmetricAlgorithm(key_min, key_max, key_mod),
+         BLOCK_SIZE(block_size) {}
+
+      virtual ~BlockCipher() {}
+
+      /**
       * The block size of this algorithm.
       */
       const u32bit BLOCK_SIZE;
 
       /**
-      * @return the preferred parallelism of this cipher
+      * @return native parallelism of this cipher in blocks
       */
-      virtual u32bit parallelism() const { return 4; }
+      virtual u32bit parallelism() const { return 1; }
+
+      /**
+      * @return prefererred parallelism of this cipher in bytes
+      */
+      u32bit parallel_bytes() const
+         {
+         return parallelism() * BLOCK_SIZE * BOTAN_BLOCK_CIPHER_PAR_MULT;
+         }
 
       /**
       * Encrypt a block.
@@ -50,7 +74,7 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
 
       /**
       * Encrypt a block.
-      * @param in The plaintext block to be encrypted as a byte array.
+      * @param block the plaintext block to be encrypted
       * Must be of length BLOCK_SIZE. Will hold the result when the function
       * has finished.
       */
@@ -58,7 +82,7 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
 
       /**
       * Decrypt a block.
-      * @param in The ciphertext block to be decrypted as a byte array.
+      * @param block the ciphertext block to be decrypted
       * Must be of length BLOCK_SIZE. Will hold the result when the function
       * has finished.
       */
@@ -91,15 +115,6 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
       * Zeroize internal state
       */
       virtual void clear() = 0;
-
-      BlockCipher(u32bit block_size,
-                  u32bit key_min,
-                  u32bit key_max = 0,
-                  u32bit key_mod = 1) :
-         SymmetricAlgorithm(key_min, key_max, key_mod),
-         BLOCK_SIZE(block_size) {}
-
-      virtual ~BlockCipher() {}
    };
 
 }
diff --git a/src/block/blowfish/blowfish.h b/src/block/blowfish/blowfish.h
index 2306f0e37..a178ec488 100644
--- a/src/block/blowfish/blowfish.h
+++ b/src/block/blowfish/blowfish.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Blowfish
 */
 class BOTAN_DLL Blowfish : public BlockCipher
diff --git a/src/block/cascade/cascade.h b/src/block/cascade/cascade.h
index 98c64fb3e..abd9b015d 100644
--- a/src/block/cascade/cascade.h
+++ b/src/block/cascade/cascade.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Block Cipher Cascade
 */
 class BOTAN_DLL Cascade_Cipher : public BlockCipher
@@ -25,6 +25,11 @@ class BOTAN_DLL Cascade_Cipher : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
+      /**
+      * Create a cascade of two block ciphers
+      * @param cipher1 the first cipher
+      * @param cipher2 the second cipher
+      */
       Cascade_Cipher(BlockCipher* cipher1, BlockCipher* cipher2);
 
       ~Cascade_Cipher();
diff --git a/src/block/cast/cast128.h b/src/block/cast/cast128.h
index 048d2e43c..967e91938 100644
--- a/src/block/cast/cast128.h
+++ b/src/block/cast/cast128.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CAST-128
 */
 class BOTAN_DLL CAST_128 : public BlockCipher
diff --git a/src/block/cast/cast256.h b/src/block/cast/cast256.h
index 170d94e77..c4a305671 100644
--- a/src/block/cast/cast256.h
+++ b/src/block/cast/cast256.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CAST-256
 */
 class BOTAN_DLL CAST_256 : public BlockCipher
diff --git a/src/block/des/des.h b/src/block/des/des.h
index 32dd3daf6..1ae806850 100644
--- a/src/block/des/des.h
+++ b/src/block/des/des.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DES
 */
 class BOTAN_DLL DES : public BlockCipher
@@ -32,7 +32,7 @@ class BOTAN_DLL DES : public BlockCipher
       SecureVector<u32bit, 32> round_key;
    };
 
-/*
+/**
 * Triple DES
 */
 class BOTAN_DLL TripleDES : public BlockCipher
diff --git a/src/block/des/desx.h b/src/block/des/desx.h
index 440574e9d..45a9d8479 100644
--- a/src/block/des/desx.h
+++ b/src/block/des/desx.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DESX
 */
 class BOTAN_DLL DESX : public BlockCipher
diff --git a/src/block/gost_28147/gost_28147.h b/src/block/gost_28147/gost_28147.h
index 2ccb3214d..ec23466f4 100644
--- a/src/block/gost_28147/gost_28147.h
+++ b/src/block/gost_28147/gost_28147.h
@@ -21,14 +21,24 @@ namespace Botan {
 class BOTAN_DLL GOST_28147_89_Params
    {
    public:
+      /**
+      * @param row the row
+      * @param col the column
+      * @return sbox entry at this row/column
+      */
       byte sbox_entry(u32bit row, u32bit col) const;
 
+      /**
+      * @return name of this parameter set
+      */
       std::string param_name() const { return name; }
 
       /**
       * Default GOST parameters are the ones given in GOST R 34.11 for
       * testing purposes; these sboxes are also used by Crypto++, and,
-      * at least according to Wikipedia, the Central Bank of Russian Federation
+      * at least according to Wikipedia, the Central Bank of Russian
+      * Federation
+      * @param name of the parameter set
       */
       GOST_28147_89_Params(const std::string& name = "R3411_94_TestParam");
    private:
@@ -50,6 +60,9 @@ class BOTAN_DLL GOST_28147_89 : public BlockCipher
       std::string name() const { return "GOST-28147-89"; }
       BlockCipher* clone() const { return new GOST_28147_89(SBOX); }
 
+      /**
+      * @param params the sbox parameters to use
+      */
       GOST_28147_89(const GOST_28147_89_Params& params);
    private:
       GOST_28147_89(const SecureVector<u32bit, 1024>& other_SBOX) :
diff --git a/src/block/idea/idea.h b/src/block/idea/idea.h
index 1a9644d4e..e9ccf366d 100644
--- a/src/block/idea/idea.h
+++ b/src/block/idea/idea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * IDEA
 */
 class BOTAN_DLL IDEA : public BlockCipher
@@ -26,8 +26,10 @@ class BOTAN_DLL IDEA : public BlockCipher
       BlockCipher* clone() const { return new IDEA; }
 
       IDEA() : BlockCipher(8, 16) {}
-   protected:
+   private:
       void key_schedule(const byte[], u32bit);
+
+   protected: // for IDEA_SSE2
       SecureVector<u16bit, 52> EK, DK;
    };
 
diff --git a/src/block/idea_sse2/idea_sse2.h b/src/block/idea_sse2/idea_sse2.h
index 657581d74..b00e0f400 100644
--- a/src/block/idea_sse2/idea_sse2.h
+++ b/src/block/idea_sse2/idea_sse2.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
+/**
 * IDEA in SSE2
 */
 class BOTAN_DLL IDEA_SSE2 : public IDEA
    {
    public:
-      u32bit parallelism() const { return 16; }
+      u32bit parallelism() const { return 8; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/kasumi/kasumi.h b/src/block/kasumi/kasumi.h
index 827989a57..fda348ef3 100644
--- a/src/block/kasumi/kasumi.h
+++ b/src/block/kasumi/kasumi.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* KASUMI
+/**
+* KASUMI, the block cipher used in 3G telephony
 */
 class BOTAN_DLL KASUMI : public BlockCipher
    {
diff --git a/src/block/lion/lion.h b/src/block/lion/lion.h
index f24acdb72..bba4e6f30 100644
--- a/src/block/lion/lion.h
+++ b/src/block/lion/lion.h
@@ -14,8 +14,13 @@
 
 namespace Botan {
 
-/*
-* Lion
+/**
+* Lion is a block cipher construction designed by Ross Anderson and
+* Eli Biham, described in "Two Practical and Provably Secure Block
+* Ciphers: BEAR and LION". It has a variable block size and is
+* designed to encrypt very large blocks (up to a megabyte)
+
+* http://www.cl.cam.ac.uk/~rja14/Papers/bear-lion.pdf
 */
 class BOTAN_DLL Lion : public BlockCipher
    {
@@ -27,7 +32,15 @@ class BOTAN_DLL Lion : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
-      Lion(HashFunction*, StreamCipher*, u32bit);
+      /**
+      * @param hash the hash to use internally
+      * @param cipher the stream cipher to use internally
+      * @param block_size the size of the block to use
+      */
+      Lion(HashFunction* hash,
+           StreamCipher* cipher,
+           u32bit block_size);
+
       ~Lion() { delete hash; delete cipher; }
    private:
       void key_schedule(const byte[], u32bit);
diff --git a/src/block/lubyrack/lubyrack.h b/src/block/lubyrack/lubyrack.h
index 7249cf157..a69d2302f 100644
--- a/src/block/lubyrack/lubyrack.h
+++ b/src/block/lubyrack/lubyrack.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Luby-Rackoff
+/**
+* Luby-Rackoff block cipher construction
 */
 class BOTAN_DLL LubyRackoff : public BlockCipher
    {
@@ -26,6 +26,9 @@ class BOTAN_DLL LubyRackoff : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
+      /**
+      * @param hash function to use to form the block cipher
+      */
       LubyRackoff(HashFunction* hash);
       ~LubyRackoff() { delete hash; }
    private:
diff --git a/src/block/mars/mars.h b/src/block/mars/mars.h
index f2a6d0197..f455ec5ca 100644
--- a/src/block/mars/mars.h
+++ b/src/block/mars/mars.h
@@ -12,6 +12,9 @@
 
 namespace Botan {
 
+/**
+* MARS, IBM's candidate for AES
+*/
 class BOTAN_DLL MARS : public BlockCipher
    {
    public:
diff --git a/src/block/misty1/misty1.h b/src/block/misty1/misty1.h
index 7b4d91def..a9bc12c7b 100644
--- a/src/block/misty1/misty1.h
+++ b/src/block/misty1/misty1.h
@@ -1,4 +1,4 @@
-/**
+/*
 * MISTY1
 * (C) 1999-2008 Jack Lloyd
 *
@@ -25,7 +25,11 @@ class BOTAN_DLL MISTY1 : public BlockCipher
       std::string name() const { return "MISTY1"; }
       BlockCipher* clone() const { return new MISTY1; }
 
-      MISTY1(u32bit = 8);
+      /**
+      * @param rounds the number of rounds. Must be 8 with the current
+      * implementation
+      */
+      MISTY1(u32bit rounds = 8);
    private:
       void key_schedule(const byte[], u32bit);
 
diff --git a/src/block/noekeon/noekeon.h b/src/block/noekeon/noekeon.h
index abeecbc64..018c1d1fd 100644
--- a/src/block/noekeon/noekeon.h
+++ b/src/block/noekeon/noekeon.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Noekeon
 */
 class BOTAN_DLL Noekeon : public BlockCipher
@@ -26,9 +26,13 @@ class BOTAN_DLL Noekeon : public BlockCipher
       BlockCipher* clone() const { return new Noekeon; }
 
       Noekeon() : BlockCipher(16, 16) {}
-   protected:
+   private:
       void key_schedule(const byte[], u32bit);
+   protected: // for access by SIMD subclass
 
+      /**
+      * The Noekeon round constants
+      */
       static const byte RC[17];
 
       SecureVector<u32bit, 4> EK, DK;
diff --git a/src/block/noekeon_simd/noekeon_simd.h b/src/block/noekeon_simd/noekeon_simd.h
index 55fdfbd22..507f17e21 100644
--- a/src/block/noekeon_simd/noekeon_simd.h
+++ b/src/block/noekeon_simd/noekeon_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* Noekeon
+/**
+* Noekeon implementation using SIMD operations
 */
 class BOTAN_DLL Noekeon_SIMD : public Noekeon
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/rc2/rc2.h b/src/block/rc2/rc2.h
index dd0295572..c16680347 100644
--- a/src/block/rc2/rc2.h
+++ b/src/block/rc2/rc2.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RC2
 */
 class BOTAN_DLL RC2 : public BlockCipher
@@ -21,7 +21,12 @@ class BOTAN_DLL RC2 : public BlockCipher
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
 
-      static byte EKB_code(u32bit);
+      /**
+      * Return the code of the effective key bits
+      * @param bits key length
+      * @return EKB code
+      */
+      static byte EKB_code(u32bit bits);
 
       void clear() { K.clear(); }
       std::string name() const { return "RC2"; }
diff --git a/src/block/rc5/rc5.h b/src/block/rc5/rc5.h
index 82931c1d2..385c6b2b1 100644
--- a/src/block/rc5/rc5.h
+++ b/src/block/rc5/rc5.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RC5
 */
 class BOTAN_DLL RC5 : public BlockCipher
@@ -25,7 +25,11 @@ class BOTAN_DLL RC5 : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const { return new RC5(ROUNDS); }
 
-      RC5(u32bit);
+      /**
+      * @param rounds the number of RC5 rounds to run. Must be between
+      * 8 and 32 and a multiple of 4.
+      */
+      RC5(u32bit rounds);
    private:
       void key_schedule(const byte[], u32bit);
       SecureVector<u32bit> S;
diff --git a/src/block/rc6/rc6.h b/src/block/rc6/rc6.h
index cc1534ee2..9b2d587fa 100644
--- a/src/block/rc6/rc6.h
+++ b/src/block/rc6/rc6.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* RC6
+/**
+* RC6, Ron Rivest's AES candidate
 */
 class BOTAN_DLL RC6 : public BlockCipher
    {
diff --git a/src/block/safer/safer_sk.h b/src/block/safer/safer_sk.h
index 80d2dc069..c93797602 100644
--- a/src/block/safer/safer_sk.h
+++ b/src/block/safer/safer_sk.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * SAFER-SK
 */
 class BOTAN_DLL SAFER_SK : public BlockCipher
@@ -25,7 +25,11 @@ class BOTAN_DLL SAFER_SK : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
-      SAFER_SK(u32bit);
+      /**
+      * @param rounds the number of rounds to use - must be between 1
+      * and 13
+      */
+      SAFER_SK(u32bit rounds);
    private:
       void key_schedule(const byte[], u32bit);
 
diff --git a/src/block/seed/seed.h b/src/block/seed/seed.h
index e56b77dbb..0c80199ad 100644
--- a/src/block/seed/seed.h
+++ b/src/block/seed/seed.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SEED
+/**
+* SEED, a Korean block cipher
 */
 class BOTAN_DLL SEED : public BlockCipher
    {
diff --git a/src/block/serpent/serpent.h b/src/block/serpent/serpent.h
index 37ce10c7b..1c13d00f9 100644
--- a/src/block/serpent/serpent.h
+++ b/src/block/serpent/serpent.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent, an AES finalist
 */
 class BOTAN_DLL Serpent : public BlockCipher
    {
@@ -26,7 +26,7 @@ class BOTAN_DLL Serpent : public BlockCipher
       BlockCipher* clone() const { return new Serpent; }
       Serpent() : BlockCipher(16, 16, 32, 8) {}
    protected:
-      void key_schedule(const byte[], u32bit);
+      void key_schedule(const byte key[], u32bit length);
 
       SecureVector<u32bit, 132> round_key;
    };
diff --git a/src/block/serpent_ia32/serp_ia32.h b/src/block/serpent_ia32/serp_ia32.h
index dc6beaf13..229a2042b 100644
--- a/src/block/serpent_ia32/serp_ia32.h
+++ b/src/block/serpent_ia32/serp_ia32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent implementation in x86 assembly
 */
 class BOTAN_DLL Serpent_IA32 : public Serpent
    {
diff --git a/src/block/serpent_simd/serp_simd.h b/src/block/serpent_simd/serp_simd.h
index dc2b08736..f0a11fc93 100644
--- a/src/block/serpent_simd/serp_simd.h
+++ b/src/block/serpent_simd/serp_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent implementation using SIMD
 */
 class BOTAN_DLL Serpent_SIMD : public Serpent
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/skipjack/skipjack.h b/src/block/skipjack/skipjack.h
index d481aee08..29978efc7 100644
--- a/src/block/skipjack/skipjack.h
+++ b/src/block/skipjack/skipjack.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Skipjack
+/**
+* Skipjack, a NSA designed cipher used in Fortezza
 */
 class BOTAN_DLL Skipjack : public BlockCipher
    {
diff --git a/src/block/square/square.h b/src/block/square/square.h
index 8e1f7f815..a17771f11 100644
--- a/src/block/square/square.h
+++ b/src/block/square/square.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Square
 */
 class BOTAN_DLL Square : public BlockCipher
diff --git a/src/block/tea/tea.h b/src/block/tea/tea.h
index 152c9a905..128f42080 100644
--- a/src/block/tea/tea.h
+++ b/src/block/tea/tea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * TEA
 */
 class BOTAN_DLL TEA : public BlockCipher
diff --git a/src/block/twofish/twofish.h b/src/block/twofish/twofish.h
index 7600abca8..3191dc963 100644
--- a/src/block/twofish/twofish.h
+++ b/src/block/twofish/twofish.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Twofish
+/**
+* Twofish, an AES finalist
 */
 class BOTAN_DLL Twofish : public BlockCipher
    {
diff --git a/src/block/xtea/xtea.h b/src/block/xtea/xtea.h
index 940992dfa..b16cdf555 100644
--- a/src/block/xtea/xtea.h
+++ b/src/block/xtea/xtea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * XTEA
 */
 class BOTAN_DLL XTEA : public BlockCipher
diff --git a/src/block/xtea_simd/xtea_simd.h b/src/block/xtea_simd/xtea_simd.h
index 04a4977ae..87eeb433b 100644
--- a/src/block/xtea_simd/xtea_simd.h
+++ b/src/block/xtea_simd/xtea_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* XTEA (SIMD variant)
+/**
+* XTEA implemented using SIMD operations
 */
 class BOTAN_DLL XTEA_SIMD : public XTEA
    {
    public:
-      u32bit parallelism() const { return 16; }
+      u32bit parallelism() const { return 8; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;