Doxygen

8 files changed, 107 insertions, 29 deletions

diff --git a/src/block/serpent_ia32/serp_ia32.cpp b/src/block/serpent_ia32/serp_ia32.cpp
index 70f4b4cf3..ecdfec9b1 100644
--- a/src/block/serpent_ia32/serp_ia32.cpp
+++ b/src/block/serpent_ia32/serp_ia32.cpp
@@ -12,9 +12,32 @@ namespace Botan {
 
 extern "C" {
 
-void botan_serpent_ia32_encrypt(const byte[16], byte[16], const u32bit[132]);
-void botan_serpent_ia32_decrypt(const byte[16], byte[16], const u32bit[132]);
-void botan_serpent_ia32_key_schedule(u32bit[140]);
+/**
+* Entry point for Serpent encryption in x86 asm
+* @param in the input block
+* @param out the output block
+* @param ks the key schedule
+*/
+void botan_serpent_ia32_encrypt(const byte in[16],
+                                byte out[16],
+                                const u32bit ks[132]);
+
+/**
+* Entry point for Serpent decryption in x86 asm
+* @param in the input block
+* @param out the output block
+* @param ks the key schedule
+*/
+void botan_serpent_ia32_decrypt(const byte in[16],
+                                byte out[16],
+                                const u32bit ks[132]);
+
+/**
+* Entry point for Serpent key schedule in x86 asm
+* @param ks holds the initial working key (padded), and is set to the
+            final key schedule
+*/
+void botan_serpent_ia32_key_schedule(u32bit ks[140]);
 
 }
 
diff --git a/src/constructs/aont/package.h b/src/constructs/aont/package.h
index 211623347..34e0f35d5 100644
--- a/src/constructs/aont/package.h
+++ b/src/constructs/aont/package.h
@@ -1,6 +1,5 @@
 /*
 * Rivest's Package Tranform
-*
 * (C) 2009 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
@@ -16,12 +15,12 @@ namespace Botan {
 
 /**
 * Rivest's Package Tranform
-* @arg rng the random number generator to use
-* @arg cipher the block cipher to use
-* @arg input the input data buffer
-* @arg input_len the length of the input data in bytes
-* @arg output the output data buffer (must be at least
-*      input_len + cipher->BLOCK_SIZE bytes long)
+* @param rng the random number generator to use
+* @param cipher the block cipher to use
+* @param input the input data buffer
+* @param input_len the length of the input data in bytes
+* @param output the output data buffer (must be at least
+*        input_len + cipher->BLOCK_SIZE bytes long)
 */
 void BOTAN_DLL aont_package(RandomNumberGenerator& rng,
                             BlockCipher* cipher,
@@ -30,12 +29,11 @@ void BOTAN_DLL aont_package(RandomNumberGenerator& rng,
 
 /**
 * Rivest's Package Tranform (Inversion)
-* @arg rng the random number generator to use
-* @arg cipher the block cipher to use
-* @arg input the input data buffer
-* @arg input_len the length of the input data in bytes
-* @arg output the output data buffer (must be at least
-*      input_len - cipher->BLOCK_SIZE bytes long)
+* @param cipher the block cipher to use
+* @param input the input data buffer
+* @param input_len the length of the input data in bytes
+* @param output the output data buffer (must be at least
+*        input_len - cipher->BLOCK_SIZE bytes long)
 */
 void BOTAN_DLL aont_unpackage(BlockCipher* cipher,
                               const byte input[], u32bit input_len,
diff --git a/src/constructs/fpe/fpe.cpp b/src/constructs/fpe/fpe.cpp
index a0b3274b5..4eaff0eb6 100644
--- a/src/constructs/fpe/fpe.cpp
+++ b/src/constructs/fpe/fpe.cpp
@@ -136,7 +136,7 @@ BigInt FPE_Encryptor::operator()(u32bit round_no, const BigInt& R)
 
 }
 
-/**
+/*
 * Generic Z_n FPE encryption, FE1 scheme
 */
 BigInt fpe_encrypt(const BigInt& n, const BigInt& X0,
@@ -164,7 +164,7 @@ BigInt fpe_encrypt(const BigInt& n, const BigInt& X0,
    return X;
    }
 
-/**
+/*
 * Generic Z_n FPE decryption, FD1 scheme
 */
 BigInt fpe_decrypt(const BigInt& n, const BigInt& X0,
diff --git a/src/constructs/fpe/fpe.h b/src/constructs/fpe/fpe.h
index 75f90247f..7a4a7861a 100644
--- a/src/constructs/fpe/fpe.h
+++ b/src/constructs/fpe/fpe.h
@@ -13,15 +13,23 @@
 
 namespace Botan {
 
-/*
+/**
 * Encrypt X from and onto the group Z_n using key and tweak
+* @param n the modulus
+* @param X the plaintext as a BigInt
+* @param key a random key
+* @param tweak will modify the ciphertext (think of as an IV)
 */
 BigInt BOTAN_DLL fpe_encrypt(const BigInt& n, const BigInt& X,
                              const SymmetricKey& key,
                              const MemoryRegion<byte>& tweak);
 
-/*
+/**
 * Decrypt X from and onto the group Z_n using key and tweak
+* @param n the modulus
+* @param X the ciphertext as a BigInt
+* @param key is the key used for encryption
+* @param tweak the same tweak used for encryption
 */
 BigInt BOTAN_DLL fpe_decrypt(const BigInt& n, const BigInt& X,
                              const SymmetricKey& key,
diff --git a/src/entropy/unix_procs/unix_cmd.h b/src/entropy/unix_procs/unix_cmd.h
index 3abca8f37..2dc55f6d7 100644
--- a/src/entropy/unix_procs/unix_cmd.h
+++ b/src/entropy/unix_procs/unix_cmd.h
@@ -27,8 +27,19 @@ struct Unix_Program
    Unix_Program(const char* n, u32bit p)
       { name_and_args = n; priority = p; working = true; }
 
+   /**
+   * The name and arguments for this command
+   */
    std::string name_and_args;
+
+   /**
+   * Priority: we scan from low to high
+   */
    u32bit priority;
+
+   /**
+   * Does this source seem to be working?
+   */
    bool working;
    };
 
diff --git a/src/libstate/lookup.h b/src/libstate/lookup.h
index 76e06b2de..debcee52b 100644
--- a/src/libstate/lookup.h
+++ b/src/libstate/lookup.h
@@ -19,12 +19,12 @@
 
 namespace Botan {
 
-/*
-* Retrieve an object from the lookup table
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
 */
-// NOTE: these functions return internally stored objects, library
-// retains ownership
-
 inline const BlockCipher*
 retrieve_block_cipher(const std::string& algo_spec)
    {
@@ -32,6 +32,12 @@ retrieve_block_cipher(const std::string& algo_spec)
    return af.prototype_block_cipher(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const StreamCipher*
 retrieve_stream_cipher(const std::string& algo_spec)
    {
@@ -39,6 +45,12 @@ retrieve_stream_cipher(const std::string& algo_spec)
    return af.prototype_stream_cipher(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const HashFunction*
 retrieve_hash(const std::string& algo_spec)
    {
@@ -46,6 +58,12 @@ retrieve_hash(const std::string& algo_spec)
    return af.prototype_hash_function(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const MessageAuthenticationCode*
 retrieve_mac(const std::string& algo_spec)
    {
diff --git a/src/selftest/selftest.h b/src/selftest/selftest.h
index df71e6f8e..091206579 100644
--- a/src/selftest/selftest.h
+++ b/src/selftest/selftest.h
@@ -15,13 +15,28 @@
 
 namespace Botan {
 
-/*
-* Self Tests
+/**
+* Run a set of self tests on some basic algorithms like AES and SHA-1
+* @param af an algorithm factory
+* @throws Self_Test_Error if a failure occured
 */
 BOTAN_DLL void confirm_startup_self_tests(Algorithm_Factory& af);
 
+/**
+* Run a set of self tests on some basic algorithms like AES and SHA-1
+* @param af an algorithm factory
+* @returns false if a failure occured, otherwise true
+*/
 BOTAN_DLL bool passes_self_tests(Algorithm_Factory& af);
 
+/**
+* Run a set of algorithm KATs (known answer tests)
+* @param algo_name the algorithm we are testing
+* @param vars a set of input variables for this test, all
+         hex encoded. Keys used: "input", "output", "key", and "iv"
+* @param af an algorithm factory
+* @returns map from provider name to test result for that provider
+*/
 BOTAN_DLL std::map<std::string, bool>
 algorithm_kat(const SCAN_Name& algo_name,
               const std::map<std::string, std::string>& vars,
diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h
index 450dab306..07b588329 100644
--- a/src/sym_algo/symkey.h
+++ b/src/sym_algo/symkey.h
@@ -140,10 +140,15 @@ BOTAN_DLL OctetString operator+(const OctetString& x,
 BOTAN_DLL OctetString operator^(const OctetString& x,
                                 const OctetString& y);
 
-/*
-* Alternate Names
+
+/**
+* Alternate name for octet string showing intent to use as a key
 */
 typedef OctetString SymmetricKey;
+
+/**
+* Alternate name for octet string showing intent to use as an IV
+*/
 typedef OctetString InitializationVector;
 
 }