And add yet more InSiTo Doxygen comments (20 .h files to go...)

5 files changed, 323 insertions, 79 deletions

diff --git a/src/core/data_src.h b/src/core/data_src.h
index f7285e8fb..d250addfc 100644
--- a/src/core/data_src.h
+++ b/src/core/data_src.h
@@ -11,20 +11,67 @@
 
 namespace Botan {
 
-/*************************************************
-* Generic DataSource Interface                   *
-*************************************************/
+/**
+* This class represents an abstract data source object.
+*/
 class BOTAN_DLL DataSource
    {
    public:
-      virtual u32bit read(byte[], u32bit) = 0;
-      virtual u32bit peek(byte[], u32bit, u32bit) const = 0;
+      /**
+      * Read from the source. Moves the internal offset so that
+      * every call to read will return a new portion of the source.
+      * @param out the byte array to write the result to
+      * @param length the length of the byte array out
+      * @return the length in bytes that was actually read and put
+      * into out
+      */
+      virtual u32bit read(byte out[], u32bit length) = 0;
+
+      /**
+      * Read from the source but do not modify the internal offset. Consecutive
+      * calls to peek() will return portions of the source starting at the same
+      * position.
+      * @param out the byte array to write the output to
+      * @param length the length of the byte array out
+      * @return the length in bytes that was actually read and put
+      * into out
+      */
+      virtual u32bit peek(byte out[], u32bit length,
+                          u32bit peek_offset) const = 0;
+
+      /**
+      * Test whether the source still has data that can be read.
+      * @return true if there is still data to read, false otherwise
+      */
       virtual bool end_of_data() const = 0;
+      /**
+      * return the id of this data source
+      * @return the std::string representing the id of this data source
+      */
       virtual std::string id() const { return ""; }
 
-      u32bit read_byte(byte&);
-      u32bit peek_byte(byte&) const;
-      u32bit discard_next(u32bit);
+      /**
+      * Read one byte.
+      * @param the byte to read to
+      * @return the length in bytes that was actually read and put
+      * into out
+      */
+      u32bit read_byte(byte& out);
+
+      /**
+      * Peek at one byte.
+      * @param the byte to read to
+      * @return the length in bytes that was actually read and put
+      * into out
+      */
+      u32bit peek_byte(byte& out) const;
+
+      /**
+      * Discard the next N bytes of the data
+      * @param N the number of bytes to discard
+      * @return the number of bytes actually discarded
+      */
+      u32bit discard_next(u32bit N);
 
       DataSource() {}
       virtual ~DataSource() {}
@@ -33,9 +80,9 @@ class BOTAN_DLL DataSource
       DataSource(const DataSource&);
    };
 
-/*************************************************
-* Memory-Based DataSource                        *
-*************************************************/
+/**
+* This class represents a Memory-Based DataSource
+*/
 class BOTAN_DLL DataSource_Memory : public DataSource
    {
    public:
@@ -43,17 +90,32 @@ class BOTAN_DLL DataSource_Memory : public DataSource
       u32bit peek(byte[], u32bit, u32bit) const;
       bool end_of_data() const;
 
-      DataSource_Memory(const std::string&);
-      DataSource_Memory(const byte[], u32bit);
-      DataSource_Memory(const MemoryRegion<byte>&);
+      /**
+      * Construct a memory source that reads from a string
+      * @param in the string to read from
+      */
+      DataSource_Memory(const std::string& in);
+
+      /**
+      * Construct a memory source that reads from a byte array
+      * @param in the byte array to read from
+      * @param length the length of the byte array
+      */
+      DataSource_Memory(const byte in[], u32bit length);
+
+      /**
+      * Construct a memory source that reads from a MemoryRegion
+      * @param in the MemoryRegion to read from
+      */
+      DataSource_Memory(const MemoryRegion<byte>& in);
    private:
       SecureVector<byte> source;
       u32bit offset;
    };
 
-/*************************************************
-* Stream-Based DataSource                        *
-*************************************************/
+/**
+* This class represents a Stream-Based DataSource.
+*/
 class BOTAN_DLL DataSource_Stream : public DataSource
    {
    public:
@@ -63,7 +125,14 @@ class BOTAN_DLL DataSource_Stream : public DataSource
       std::string id() const;
 
       DataSource_Stream(std::istream&, const std::string& id = "");
-      DataSource_Stream(const std::string&, bool = false);
+
+      /**
+      * Construct a Stream-Based DataSource from file
+      * @param file the name of the file
+      * @param use_binary whether to treat the file as binary or not
+      */
+      DataSource_Stream(const std::string& file, bool use_binary = false);
+
       ~DataSource_Stream();
    private:
       const std::string identifier;
diff --git a/src/filters/basefilt.h b/src/filters/basefilt.h
index d6c5b1e0b..975ed5ca0 100644
--- a/src/filters/basefilt.h
+++ b/src/filters/basefilt.h
@@ -10,40 +10,81 @@
 
 namespace Botan {
 
-/*************************************************
-* Chain                                          *
-*************************************************/
+/**
+* This class represents Filter chains. A Filter chain is an ordered
+* concatenation of Filters, the input to a Chain sequentially passes
+* through all the Filters contained in the Chain.
+*/
+
 class BOTAN_DLL Chain : public Fanout_Filter
    {
    public:
       void write(const byte input[], u32bit length) { send(input, length); }
 
+      /**
+      * Construct a chain of up to four filters. The filters are set up in the same order
+      * as the arguments.
+      */
       Chain(Filter* = 0, Filter* = 0, Filter* = 0, Filter* = 0);
-      Chain(Filter*[], u32bit);
+
+      /**
+      * Construct a chain from range of filters
+      * @param filter_arr the list of filters
+      * @param length how many filters
+      */
+      Chain(Filter* filter_arr[], u32bit length);
    };
 
-/*************************************************
-* Fork                                           *
-*************************************************/
+/**
+* This class represents a fork filter, whose purpose is to fork the
+* flow of data. It causes an input message to result in n messages at
+* the end of the filter, where n is the number of forks.
+*/
 class BOTAN_DLL Fork : public Fanout_Filter
    {
    public:
       void write(const byte input[], u32bit length) { send(input, length); }
       void set_port(u32bit n) { Fanout_Filter::set_port(n); }
 
+      /**
+      * Construct a Fork filter with up to four forks.
+      */
       Fork(Filter*, Filter*, Filter* = 0, Filter* = 0);
-      Fork(Filter*[], u32bit);
+
+      /**
+      * Construct a Fork from range of filters
+      * @param filter_arr the list of filters
+      * @param length how many filters
+      */
+      Fork(Filter* filter_arr[], u32bit length);
    };
 
-/*************************************************
-* Keyed Filter                                   *
-*************************************************/
+/**
+* This class represents keyed filters, i.e. filters that have to be
+* fed with a key in order to function.
+*/
 class BOTAN_DLL Keyed_Filter : public Filter
    {
    public:
-      virtual void set_key(const SymmetricKey&);
+
+      /**
+      * Set the key of this filter.
+      * @param key the key to set
+      */
+      virtual void set_key(const SymmetricKey& key);
+
+      /**
+      * Set the initialization vector of this filter.
+      * @param iv the initialization vector to set
+      */
       virtual void set_iv(const InitializationVector&) {}
-      virtual bool valid_keylength(u32bit) const;
+
+      /**
+      * Check whether a key length is valid for this filter.
+      * @param length the key length to be checked for validity
+      * @return true if the key length is valid, false otherwise
+      */
+      virtual bool valid_keylength(u32bit length) const;
 
       Keyed_Filter() { base_ptr = 0; }
    protected:
diff --git a/src/filters/filter.h b/src/filters/filter.h
index c73bda1be..51db50a57 100644
--- a/src/filters/filter.h
+++ b/src/filters/filter.h
@@ -11,18 +11,49 @@
 
 namespace Botan {
 
-/*************************************************
-* Filter Base Class                              *
-*************************************************/
+/**
+* This class represents general abstract filter objects.
+*/
 class BOTAN_DLL Filter
    {
    public:
-      virtual void write(const byte[], u32bit) = 0;
+
+      /**
+      * Write a portion of a message to this filter.
+      * @param input the input as a byte array
+      * @param length the length of the byte array input
+      */
+      virtual void write(const byte input[], u32bit length) = 0;
+
+      /**
+      * Start a new message. Must be closed by end_msg() before another
+      * message can be startet.
+      */
       virtual void start_msg() {}
+
+      /**
+      * Tell the Filter that the current message shall be ended.
+      */
       virtual void end_msg() {}
+
+      /**
+      * Check whether this filter is an attachable filter.
+      * @return true if this filter is attachable, false otherwise
+      */
       virtual bool attachable() { return true; }
+
+      /**
+      * Start a new message in *this and all following filters. Only for
+      * internal use, not intended for use in client applications.
+      */
       void new_msg();
+
+      /**
+      * End a new message in *this and all following filters. Only for
+      * internal use, not intended for use in client applications.
+      */
       void finish_msg();
+
       virtual ~Filter() {}
    protected:
       void send(const byte[], u32bit);
@@ -49,12 +80,12 @@ class BOTAN_DLL Filter
       SecureVector<byte> write_queue;
       std::vector<Filter*> next;
       u32bit port_num, filter_owns;
-      bool owned;
+      bool owned; // true if filter belongs to a pipe --> prohibit filter sharing!
    };
 
-/*************************************************
-* Fanout Filter Base Class                       *
-*************************************************/
+/**
+* This is the abstract Fanout_Filter base class.
+**/
 class BOTAN_DLL Fanout_Filter : public Filter
    {
    protected:
diff --git a/src/filters/filters.h b/src/filters/filters.h
index 926217a5d..43c38ef2d 100644
--- a/src/filters/filters.h
+++ b/src/filters/filters.h
@@ -20,53 +20,106 @@
 
 namespace Botan {
 
-/*************************************************
-* Stream Cipher Filter                           *
-*************************************************/
+/**
+* Stream Cipher Filter.
+*/
 class BOTAN_DLL StreamCipher_Filter : public Keyed_Filter
    {
    public:
+
+      /**
+      * Seek in the stream.
+      * @param position the position to seek ahead
+      */
       void seek(u32bit position) { cipher->seek(position); }
+
+      /**
+      * Find out whether the cipher underlying this filter supports
+      * resyncing.
+      * @return true if the cipher supports resyncing
+      */
       bool supports_resync() const { return (cipher->IV_LENGTH != 0); }
 
-      void set_iv(const InitializationVector&);
+      /**
+      * Set the initialization vector for this filter.
+      * @param iv the initialization vector to set
+      */
+      void set_iv(const InitializationVector& iv);
       void write(const byte[], u32bit);
 
-      StreamCipher_Filter(const std::string&);
-      StreamCipher_Filter(const std::string&, const SymmetricKey&);
+      /**
+      * Construct a stream cipher filter.
+      * @param cipher the name of the desired cipher
+      */
+      StreamCipher_Filter(const std::string& cipher);
+
+      /**
+      * Construct a stream cipher filter.
+      * @param cipher the name of the desired cipher
+      * @param key the key to use inside this filter
+      */
+      StreamCipher_Filter(const std::string& cipher, const SymmetricKey& key);
+
       ~StreamCipher_Filter() { delete cipher; }
    private:
       SecureVector<byte> buffer;
       StreamCipher* cipher;
    };
 
-/*************************************************
-* Hash Filter                                    *
-*************************************************/
+/**
+* Hash Filter.
+*/
 class BOTAN_DLL Hash_Filter : public Filter
    {
    public:
       void write(const byte input[], u32bit len) { hash->update(input, len); }
       void end_msg();
 
-      Hash_Filter(const std::string&, u32bit = 0);
+      /**
+      * Construct a hash filter.
+      * @param hash the name of the hash algorithm to use
+      * @param len the output length of this filter. Leave the default
+      * value 0 if you want to use the full output of the hashfunction
+      * hash. Otherwise, specify a smaller value here so that the
+      * output of the hash algorithm will be cut off.
+      */
+      Hash_Filter(const std::string& hash, u32bit len = 0);
       ~Hash_Filter() { delete hash; }
    private:
       const u32bit OUTPUT_LENGTH;
       HashFunction* hash;
    };
 
-/*************************************************
-* MessageAuthenticationCode Filter               *
-*************************************************/
+/**
+* MessageAuthenticationCode Filter.
+*/
 class BOTAN_DLL MAC_Filter : public Keyed_Filter
    {
    public:
       void write(const byte input[], u32bit len) { mac->update(input, len); }
       void end_msg();
 
-      MAC_Filter(const std::string&, u32bit = 0);
-      MAC_Filter(const std::string&, const SymmetricKey&, u32bit = 0);
+      /**
+      * Construct a MAC filter. The MAC key will be left empty.
+      * @param mac the name of the MAC to use
+      * @param len the output length of this filter. Leave the default
+      * value 0 if you want to use the full output of the
+      * MAC. Otherwise, specify a smaller value here so that the
+      * output of the MAC will be cut off.
+      */
+      MAC_Filter(const std::string& mac, u32bit len = 0);
+
+      /**
+      * Construct a MAC filter.
+      * @param mac the name of the MAC to use
+      * @param key the MAC key to use
+      * @param len the output length of this filter. Leave the default
+      * value 0 if you want to use the full output of the
+      * MAC. Otherwise, specify a smaller value here so that the
+      * output of the MAC will be cut off.
+      */
+      MAC_Filter(const std::string& mac, const SymmetricKey& key, u32bit len = 0);
+
       ~MAC_Filter() { delete mac; }
    private:
       const u32bit OUTPUT_LENGTH;
diff --git a/src/pubkey/pubkey/pk_keys.h b/src/pubkey/pubkey/pk_keys.h
index 16109c634..1aa5e3fa1 100644
--- a/src/pubkey/pubkey/pk_keys.h
+++ b/src/pubkey/pubkey/pk_keys.h
@@ -1,7 +1,7 @@
 /*************************************************
 * PK Key Types Header File                       *
 * (C) 1999-2007 Jack Lloyd                       *
-*************************************************/
+n*************************************************/
 
 #ifndef BOTAN_PK_KEYS_H__
 #define BOTAN_PK_KEYS_H__
@@ -12,23 +12,63 @@
 
 namespace Botan {
 
-/*************************************************
-* Public Key Base Class                          *
-*************************************************/
+/**
+* Public Key Base Class.
+*/
 class BOTAN_DLL Public_Key
    {
    public:
+      /**
+      * Get the name of the underlying public key scheme.
+      * @return the name of the public key scheme
+      */
       virtual std::string algo_name() const = 0;
+
+      /**
+      * Get the OID of the underlying public key scheme.
+      * @return the OID of the public key scheme
+      */
       virtual OID get_oid() const;
 
+      /**
+      * Test the key values for consistency.
+      * @param rng rng to use
+      * @param strong whether to perform strong and lengthy version
+      * of the test
+      * @return true if the test is passed
+      */
       virtual bool check_key(RandomNumberGenerator&, bool) const
          { return true; }
 
+      /**
+      * Find out the number of message parts supported by this scheme.
+      * @return the number of message parts
+      */
       virtual u32bit message_parts() const { return 1; }
+
+      /**
+      * Find out the message part size supported by this scheme/key.
+      * @return the size of the message parts
+      */
       virtual u32bit message_part_size() const { return 0; }
+
+      /**
+      * Get the maximum message size in bits supported by this public key.
+      * @return the maximum message in bits
+      */
       virtual u32bit max_input_bits() const = 0;
 
+      /**
+      * Get an X509 encoder that can be used to encode this key in X509 format.
+      * @return an X509 encoder for this key
+      */
       virtual class X509_Encoder* x509_encoder() const = 0;
+
+      /**
+      * Get an X509 decoder that can be used to set the values of this
+      * key based on an X509 encoded key object.
+      * @return an X509 decoder for this key
+      */
       virtual class X509_Decoder* x509_decoder() = 0;
 
       virtual ~Public_Key() {}
@@ -36,14 +76,24 @@ class BOTAN_DLL Public_Key
       virtual void load_check(RandomNumberGenerator&) const;
    };
 
-/*************************************************
-* Private Key Base Class                         *
-*************************************************/
+/**
+* Private Key Base Class
+*/
 class BOTAN_DLL Private_Key : public virtual Public_Key
    {
    public:
+      /**
+      * Get a PKCS#8 encoder that can be used to encode this key in PKCS#8 format.
+      * @return an PKCS#8 encoder for this key
+      */
       virtual class PKCS8_Encoder* pkcs8_encoder() const
          { return 0; }
+
+      /**
+      * Get an PKCS#8 decoder that can be used to set the values of this key
+      * based on an PKCS#8 encoded key object.
+      * @return an PKCS#8 decoder for this key
+      */
       virtual class PKCS8_Decoder* pkcs8_decoder(RandomNumberGenerator&)
          { return 0; }
    protected:
@@ -51,9 +101,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
       void gen_check(RandomNumberGenerator&) const;
    };
 
-/*************************************************
-* PK Encrypting Key                              *
-*************************************************/
+/**
+* PK Encrypting Key.
+*/
 class BOTAN_DLL PK_Encrypting_Key : public virtual Public_Key
    {
    public:
@@ -62,9 +112,9 @@ class BOTAN_DLL PK_Encrypting_Key : public virtual Public_Key
       virtual ~PK_Encrypting_Key() {}
    };
 
-/*************************************************
-* PK Decrypting Key                              *
-*************************************************/
+/**
+* PK Decrypting Key
+*/
 class BOTAN_DLL PK_Decrypting_Key : public virtual Private_Key
    {
    public:
@@ -72,9 +122,9 @@ class BOTAN_DLL PK_Decrypting_Key : public virtual Private_Key
       virtual ~PK_Decrypting_Key() {}
    };
 
-/*************************************************
-* PK Signing Key                                 *
-*************************************************/
+/**
+* PK Signing Key
+*/
 class BOTAN_DLL PK_Signing_Key : public virtual Private_Key
    {
    public:
@@ -83,9 +133,9 @@ class BOTAN_DLL PK_Signing_Key : public virtual Private_Key
       virtual ~PK_Signing_Key() {}
    };
 
-/*************************************************
-* PK Verifying Key, Message Recovery Version     *
-*************************************************/
+/**
+* PK Verifying Key, Message Recovery Version
+*/
 class BOTAN_DLL PK_Verifying_with_MR_Key : public virtual Public_Key
    {
    public:
@@ -93,9 +143,9 @@ class BOTAN_DLL PK_Verifying_with_MR_Key : public virtual Public_Key
       virtual ~PK_Verifying_with_MR_Key() {}
    };
 
-/*************************************************
-* PK Verifying Key, No Message Recovery Version  *
-*************************************************/
+/**
+* PK Verifying Key, No Message Recovery Version
+*/
 class BOTAN_DLL PK_Verifying_wo_MR_Key : public virtual Public_Key
    {
    public:
@@ -104,9 +154,9 @@ class BOTAN_DLL PK_Verifying_wo_MR_Key : public virtual Public_Key
       virtual ~PK_Verifying_wo_MR_Key() {}
    };
 
-/*************************************************
-* PK Secret Value Derivation Key                 *
-*************************************************/
+/**
+* PK Secret Value Derivation Key
+*/
 class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key
    {
    public: