Further Doxygen comments from InSiTo

2 files changed, 298 insertions, 37 deletions

diff --git a/src/core/base.h b/src/core/base.h
index b05feaacb..3c569581f 100644
--- a/src/core/base.h
+++ b/src/core/base.h
@@ -16,39 +16,120 @@ namespace Botan {
 *************************************************/
 static const u32bit DEFAULT_BUFFERSIZE = BOTAN_DEFAULT_BUFFER_SIZE;
 
-/*************************************************
-* Symmetric Algorithm                            *
-*************************************************/
+/**
+* This class represents a symmetric algorithm object.
+*/
 class BOTAN_DLL SymmetricAlgorithm
    {
    public:
-      const u32bit MAXIMUM_KEYLENGTH, MINIMUM_KEYLENGTH, KEYLENGTH_MULTIPLE;
 
+      /**
+      * The maximum allowed key length.
+      */
+      const u32bit MAXIMUM_KEYLENGTH;
+
+      /**
+      * The minimal allowed key length.
+      */
+      const u32bit MINIMUM_KEYLENGTH;
+
+      /**
+      * A valid keylength is a multiple of this value.
+      */
+      const u32bit KEYLENGTH_MULTIPLE;
+
+      /**
+      * The name of the algorithm.
+      * @return the name of the algorithm
+      */
       virtual std::string name() const = 0;
 
-      void set_key(const SymmetricKey&) throw(Invalid_Key_Length);
-      void set_key(const byte[], u32bit) throw(Invalid_Key_Length);
-      bool valid_keylength(u32bit) const;
-      SymmetricAlgorithm(u32bit, u32bit, u32bit);
+      /**
+      * Set the symmetric key of this object.
+      * @param key the SymmetricKey to be set.
+      */
+      void set_key(const SymmetricKey& key) throw(Invalid_Key_Length);
+
+      /**
+      * Set the symmetric key of this object.
+      * @param key the to be set as a byte array.
+      * @param the length of the byte array.
+      */
+      void set_key(const byte key[], u32bit length) throw(Invalid_Key_Length);
+
+      /**
+      * Check whether a given key length is valid for this algorithm.
+      * @param length the key length to be checked.
+      * @return true if the key length is valid.
+      */
+      bool valid_keylength(u32bit length) const;
+
+      /**
+      * Construct a SymmetricAlgorithm.
+      * @param key_min the minimum allowed key length
+      * @param key_max the maximum allowed key length
+      * @param key_mod any valid key length must be a multiple of this value
+      */
+      SymmetricAlgorithm(u32bit key_min, u32bit key_max, u32bit key_mod);
+
       virtual ~SymmetricAlgorithm() {}
    private:
       virtual void key(const byte[], u32bit) = 0;
    };
 
-/*************************************************
-* Block Cipher                                   *
-*************************************************/
+/**
+* This class represents a block cipher object.
+*/
 class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
    {
    public:
+      /**
+      * The block size of this algorithm.
+      */
       const u32bit BLOCK_SIZE;
 
+      /**
+      * Encrypt a block.
+      * @param in The plaintext block to be encrypted as a byte array.
+      * Must be of length BLOCK_SIZE.
+      * @param out The byte array designated to hold the encrypted block.
+      * Must be of length BLOCK_SIZE.
+      */
       void encrypt(const byte in[], byte out[]) const { enc(in, out); }
+
+      /**
+      * Decrypt a block.
+      * @param in The ciphertext block to be decypted as a byte array.
+      * Must be of length BLOCK_SIZE.
+      * @param out The byte array designated to hold the decrypted block.
+      * Must be of length BLOCK_SIZE.
+      */
       void decrypt(const byte in[], byte out[]) const { dec(in, out); }
+
+      /**
+      * Encrypt a block.
+      * @param in The plaintext block to be encrypted as a byte array.
+      * Must be of length BLOCK_SIZE. Will hold the result when the function
+      * has finished.
+      */
       void encrypt(byte block[]) const { enc(block, block); }
+
+      /**
+      * Decrypt a block.
+      * @param in The ciphertext block to be decrypted as a byte array.
+      * Must be of length BLOCK_SIZE. Will hold the result when the function
+      * has finished.
+      */
       void decrypt(byte block[]) const { dec(block, block); }
 
+      /**
+      * Get a new object representing the same algorithm as *this
+      */
       virtual BlockCipher* clone() const = 0;
+
+      /**
+      * Zeroize internal state
+      */
       virtual void clear() throw() = 0;
 
       BlockCipher(u32bit, u32bit, u32bit = 0, u32bit = 1);
@@ -65,15 +146,58 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm
    {
    public:
       const u32bit IV_LENGTH;
+
+      /**
+      * Encrypt a message.
+      * @param i the plaintext
+      * @param o the byte array to hold the output, i.e. the ciphertext
+      * @param len the length of both i and o
+      */
       void encrypt(const byte i[], byte o[], u32bit len) { cipher(i, o, len); }
+
+      /**
+      * Decrypt a message.
+      * @param i the ciphertext to decrypt
+      * @param o the byte array to hold the output, i.e. the plaintext
+      * @param len the length of both i and o
+      */
       void decrypt(const byte i[], byte o[], u32bit len) { cipher(i, o, len); }
+
+      /**
+      * Encrypt a message.
+      * @param in the plaintext as input, after the function has returned it will hold the ciphertext
+      * @param len the length of in
+      */
       void encrypt(byte in[], u32bit len) { cipher(in, in, len); }
+
+      /**
+      * Decrypt a message.
+      * @param in the ciphertext as input, after the function has returned it will hold the plaintext
+      * @param len the length of in
+      */
       void decrypt(byte in[], u32bit len) { cipher(in, in, len); }
 
-      virtual void resync(const byte[], u32bit);
-      virtual void seek(u32bit);
+      /**
+      * Resync the cipher using the IV
+      * @param iv the initialization vector
+      * @param iv_len the length of the IV in bytes
+      */
+      virtual void resync(const byte iv[], u32bit iv_len);
 
+      /**
+      * Seek ahead in the stream.
+      * @param len the length to seek ahead.
+      */
+      virtual void seek(u32bit len);
+
+      /**
+      * Get a new object representing the same algorithm as *this
+      */
       virtual StreamCipher* clone() const = 0;
+
+      /**
+      * Zeroize internal state
+      */
       virtual void clear() throw() = 0;
 
       StreamCipher(u32bit, u32bit = 0, u32bit = 1, u32bit = 0);
@@ -82,22 +206,87 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm
       virtual void cipher(const byte[], byte[], u32bit) = 0;
    };
 
-/*************************************************
-* Buffered Computation                           *
-*************************************************/
+/**
+* This class represents any kind of computation which
+* uses an internal state,
+* such as hash functions.
+*/
 class BOTAN_DLL BufferedComputation
    {
    public:
+
+      /**
+      * The length of the output of this function in bytes.
+      */
       const u32bit OUTPUT_LENGTH;
-      void update(const byte[], u32bit);
-      void update(const MemoryRegion<byte>&);
+
+      /**
+      * Add new input to process.
+      * @param in the input to process as a byte array
+      * @param the length of the byte array
+      */
+      void update(const byte in[], u32bit length);
+
+      /**
+      * Add new input to process.
+      * @param in the input to process as a MemoryRegion
+      */
+      void update(const MemoryRegion<byte>& in);
+
+      /**
+      * Add new input to process.
+      * @param in the input to process as a std::string. Will be interpreted
+      * as a byte array based on
+      * the strings encoding.
+      */
       void update(const std::string&);
-      void update(byte);
+
+      /**
+      * Process a single byte.
+      * @param in the byte to process
+      */
+      void update(byte in);
+
+      /**
+      * Complete the computation and retrieve the
+      * final result.
+      * @param out The byte array to be filled with the result.
+      * Must be of length OUTPUT_LENGTH.
+      */
       void final(byte out[]) { final_result(out); }
+
+      /**
+      * Complete the computation and retrieve the
+      * final result.
+      * @return a SecureVector holding the result
+      */
       SecureVector<byte> final();
-      SecureVector<byte> process(const byte[], u32bit);
-      SecureVector<byte> process(const MemoryRegion<byte>&);
-      SecureVector<byte> process(const std::string&);
+
+      /**
+      * Update and finalize computation. Does the same as calling update()
+      * and final() consecutively.
+      * @param in the input to process as a byte array
+      * @param length the length of the byte array
+      * @result the result of the call to final()
+      */
+      SecureVector<byte> process(const byte in[], u32bit length);
+
+      /**
+      * Update and finalize computation. Does the same as calling update()
+      * and final() consecutively.
+      * @param in the input to process
+      * @result the result of the call to final()
+      */
+      SecureVector<byte> process(const MemoryRegion<byte>& in);
+
+      /**
+      * Update and finalize computation. Does the same as calling update()
+      * and final() consecutively.
+      * @param in the input to process as a string
+      * @result the result of the call to final()
+      */
+      SecureVector<byte> process(const std::string& in);
+
       BufferedComputation(u32bit);
       virtual ~BufferedComputation() {}
    private:
@@ -106,16 +295,31 @@ class BOTAN_DLL BufferedComputation
       virtual void final_result(byte[]) = 0;
    };
 
-/*************************************************
-* Hash Function                                  *
-*************************************************/
+/**
+* This class represents hash function (message digest) objects.
+*/
 class BOTAN_DLL HashFunction : public BufferedComputation
    {
    public:
+      /**
+      * The hash block size as defined for this algorithm.
+      */
       const u32bit HASH_BLOCK_SIZE;
 
+      /**
+      * Get a new object representing the same algorithm as *this
+      */
       virtual HashFunction* clone() const = 0;
+
+      /**
+      * Get the name of this algorithm.
+      * @return the name of this algorithm
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Reset the internal state of this object.
+      */
       virtual void clear() throw() = 0;
 
       HashFunction(u32bit, u32bit = 0);
@@ -124,17 +328,35 @@ class BOTAN_DLL HashFunction : public BufferedComputation
       HashFunction& operator=(const HashFunction&);
    };
 
-/*************************************************
-* Message Authentication Code                    *
-*************************************************/
+/**
+* This class represents Message Authentication Code (MAC) objects.
+*/
 class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation,
                                   public SymmetricAlgorithm
    {
    public:
+      /**
+      * Verify a MAC.
+      * @param in the MAC to verify as a byte array
+      * @param length the length of the byte array
+      * @return true if the MAC is valid, false otherwise
+      */
       virtual bool verify_mac(const byte[], u32bit);
 
+      /**
+      * Get a new object representing the same algorithm as *this
+      */
       virtual MessageAuthenticationCode* clone() const = 0;
+
+      /**
+      * Get the name of this algorithm.
+      * @return the name of this algorithm
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Reset the internal state of this object.
+      */
       virtual void clear() throw() = 0;
 
       MessageAuthenticationCode(u32bit, u32bit, u32bit = 0, u32bit = 1);
diff --git a/src/core/rng.h b/src/core/rng.h
index d313ad028..d6d37a7a0 100644
--- a/src/core/rng.h
+++ b/src/core/rng.h
@@ -21,24 +21,63 @@ class BOTAN_DLL EntropySource
       virtual ~EntropySource() {}
    };
 
-/*************************************************
-* Random Number Generator                        *
-*************************************************/
+/**
+* This class represents a random number (RNG) generator object.
+*/
 class BOTAN_DLL RandomNumberGenerator
    {
    public:
+      /**
+      * Create a seeded and active RNG object for general application use
+      */
       static RandomNumberGenerator* make_rng();
 
-      virtual void randomize(byte[], u32bit) = 0;
-      virtual bool is_seeded() const = 0;
-      virtual void clear() throw() = 0;
-      virtual std::string name() const = 0;
+      /**
+      * Randomize a byte array.
+      * @param output the byte array to hold the random output.
+      * @param length the length of the byte array output.
+      */
+      virtual void randomize(byte output[], u32bit length) = 0;
 
+      /**
+      * Return a random byte
+      * @return random byte
+      */
       byte next_byte();
 
+      /**
+      * Check whether this RNG is seeded.
+      * @return true if this RNG was already seeded, false otherwise.
+      */
+      virtual bool is_seeded() const { return true; }
+
+      /**
+      * Clear all internally held values of this RNG.
+      */
+      virtual void clear() throw() = 0;
+
+      /**
+      * Return the name of this object
+      */
+      virtual std::string name() const = 0;
+
+      /**
+      * Force a reseed of the PRNG
+      */
       virtual void reseed() {}
-      virtual void add_entropy_source(EntropySource*) = 0;
-      virtual void add_entropy(const byte[], u32bit) = 0;
+
+      /**
+      * Add this entropy source to the RNG object
+      * @param source the entropy source which will be retained and used by RNG
+      */
+      virtual void add_entropy_source(EntropySource* source) = 0;
+
+      /**
+      * Add entropy to this RNG.
+      * @param in a byte array containg the entropy to be added
+      * @param length the length of the byte array in
+      */
+      virtual void add_entropy(const byte in[], u32bit length) = 0;
 
       RandomNumberGenerator() {}
       virtual ~RandomNumberGenerator() {}