More Doxygen comments from InSiTo

5 files changed, 231 insertions, 40 deletions

diff --git a/src/cert/x509/crl_ent.h b/src/cert/x509/crl_ent.h
index 8aa567a2a..40d82a8d7 100644
--- a/src/cert/x509/crl_ent.h
+++ b/src/cert/x509/crl_ent.h
@@ -10,20 +10,43 @@
 
 namespace Botan {
 
-/*************************************************
-* CRL Entry                                      *
-*************************************************/
+/**
+* This class represents CRL entries
+*/
 class BOTAN_DLL CRL_Entry : public ASN1_Object
    {
    public:
       void encode_into(class DER_Encoder&) const;
       void decode_from(class BER_Decoder&);
 
+      /**
+      * Get the serial number of the certificate associated with this entry.
+      * @return the certificate's serial number
+      */
       MemoryVector<byte> serial_number() const { return serial; }
+
+      /**
+      * Get the revocation date of the certificate associated with this entry
+      * @return the certificate's revocation date
+      */
       X509_Time expire_time() const { return time; }
+
+      /**
+      * Get the entries reason code
+      * @return the reason code
+      */
       CRL_Code reason_code() const { return reason; }
 
+      /**
+      * Construct an empty CRL entry.
+      */
       CRL_Entry(bool throw_on_unknown_critical_extension = false);
+
+      /**
+      * Construct an CRL entry.
+      * @param cert the certificate to revoke
+      * @param reason the reason code to set in the entry
+      */
       CRL_Entry(const X509_Certificate&, CRL_Code = UNSPECIFIED);
 
    private:
@@ -33,11 +56,19 @@ class BOTAN_DLL CRL_Entry : public ASN1_Object
       CRL_Code reason;
    };
 
-/*************************************************
-* Comparison Operations                          *
-*************************************************/
+/**
+* Test two CRL entries for equality in all fields.
+*/
 BOTAN_DLL bool operator==(const CRL_Entry&, const CRL_Entry&);
+
+/**
+* Test two CRL entries for inequality in at least one field.
+*/
 BOTAN_DLL bool operator!=(const CRL_Entry&, const CRL_Entry&);
+
+/**
+* Order two entries based on the revocation date.
+*/
 BOTAN_DLL bool operator<(const CRL_Entry&, const CRL_Entry&);
 
 }
diff --git a/src/cert/x509/x509_crl.h b/src/cert/x509/x509_crl.h
index ec73e9fdf..dd1ea372e 100644
--- a/src/cert/x509/x509_crl.h
+++ b/src/cert/x509/x509_crl.h
@@ -12,29 +12,69 @@
 
 namespace Botan {
 
-/*************************************************
-* X.509 CRL                                      *
-*************************************************/
+/**
+* This class represents X.509 Certificate Revocation Lists (CRLs).
+*/
 class BOTAN_DLL X509_CRL : public X509_Object
    {
    public:
+      /**
+      * This class represents CRL related errors.
+      */
       struct X509_CRL_Error : public Exception
          {
          X509_CRL_Error(const std::string& error) :
             Exception("X509_CRL: " + error) {}
          };
 
+      /**
+      * Get the entries of this CRL in the form of a vector.
+      * @return a vector containing the entries of this CRL.
+      */
       std::vector<CRL_Entry> get_revoked() const;
 
+      /**
+      * Get the issuer DN of this CRL.
+      * @return the CRLs issuer DN
+      */
       X509_DN issuer_dn() const;
+
+      /**
+      * Get the AuthorityKeyIdentifier of this CRL.
+      * @return this CRLs AuthorityKeyIdentifier
+      */
       MemoryVector<byte> authority_key_id() const;
 
+      /**
+      * Get the serial number of this CRL.
+      * @return the CRLs serial number
+      */
       u32bit crl_number() const;
+
+      /**
+      * Get the CRL's thisUpdate value.
+      * @return the CRLs thisUpdate
+      */
       X509_Time this_update() const;
+
+      /**
+      * Get the CRL's nextUpdate value.
+      * @return the CRLs nextdUpdate
+      */
       X509_Time next_update() const;
 
+      /**
+      * Construct a CRL from a data source.
+      * @param source the data source providing the DER or PEM encoded CRL.
+      */
       X509_CRL(DataSource&, bool throw_on_unknown_critical = false);
-      X509_CRL(const std::string&, bool throw_on_unknown_critical = false);
+
+      /**
+      * Construct a CRL from a file containing the DER or PEM encoded CRL.
+      * @param filename the name of the CRL file
+      */
+      X509_CRL(const std::string& filename,
+               bool throw_on_unknown_critical = false);
    private:
       void force_decode();
 
diff --git a/src/cert/x509/x509_obj.h b/src/cert/x509/x509_obj.h
index 8808fd686..baaf5a8a4 100644
--- a/src/cert/x509/x509_obj.h
+++ b/src/cert/x509/x509_obj.h
@@ -14,9 +14,10 @@
 
 namespace Botan {
 
-/*************************************************
-* Generic X.509 SIGNED Object                    *
-*************************************************/
+/**
+* This class represents abstract X.509 signed objects as
+* in the X.500 SIGNED macro
+*/
 class BOTAN_DLL X509_Object
    {
    public:
@@ -24,10 +25,18 @@ class BOTAN_DLL X509_Object
       SecureVector<byte> signature() const;
       AlgorithmIdentifier signature_algorithm() const;
 
-      static MemoryVector<byte> make_signed(class PK_Signer*,
-                                            RandomNumberGenerator&,
-                                            const AlgorithmIdentifier&,
-                                            const MemoryRegion<byte>&);
+      /**
+      * Create a signed X509 object.
+      * @param signer the signer used to sign the object
+      * @param rng the random number generator to use
+      * @param alg_id the algorithm identifier of the signature scheme
+      * @param tbs the tbs bits to be signed
+      * @return the signed X509 object
+      */
+      static MemoryVector<byte> make_signed(class PK_Signer* signer,
+                                            RandomNumberGenerator& rng,
+                                            const AlgorithmIdentifier& alg_id,
+                                            const MemoryRegion<byte>& tbs);
 
       bool check_signature(class Public_Key&) const;
 
diff --git a/src/core/libstate/init.h b/src/core/libstate/init.h
index f4296a868..86ef09bac 100644
--- a/src/core/libstate/init.h
+++ b/src/core/libstate/init.h
@@ -12,26 +12,87 @@
 
 namespace Botan {
 
-/*************************************************
-* Options for initializing the library           *
-*************************************************/
+/**
+* This class represents options for initializing the library.
+*/
 class BOTAN_DLL InitializerOptions
    {
    public:
+      /**
+      * Check whether this set of options has thread safety enabled.
+      * @return true if thread safety is enabled
+      */
       bool thread_safe() const;
+
+      /**
+      * Check whether this set of options has the usage of alternative engines
+      * enabled.
+      * @return true if the usage of alternative engines
+      * is enabled
+      */
       bool use_engines() const;
+
+      /**
+      * Check whether this set of options has enabled the seeding of the
+      * global RNG at startup.
+      * @return true if the seeding at startup is enabled
+      */
+      bool seed_rng() const;
+
+      /**
+      * Check whether this set of options has enabled the memory
+      * locking feature. This is implemented for Unix and Win32, but
+      * it only reliably works for Unix. There, all SecureVectors and
+      * SecureBuffers are kept from being ever swapped to disk. On
+      * Win32 plattforms, the corresponding pages are locked into the
+      * working set of the process, reducing the chance of being
+      * swapped to disk, but not strictly preventing it.
+      * @return true if the memory locking feature is enabled
+      */
       bool secure_memory() const;
+
+      /**
+      * Check whether this set of options has the self-test-at-startup
+      * enabled.  Same as self_test().
+      * @param return true if the self-test is enabled
+      */
       bool fips_mode() const;
+
+      /**
+      * Check whether this set of options has the self-test-at-startup enabled.
+      * Same as fips_mode().
+      * @param return true if the self-test is enabled
+      */
       bool self_test() const;
 
-      InitializerOptions(const std::string&);
+      /**
+      * Get the full path of the configuration file to be used.
+      */
+      std::string config_file() const;
+
+      /**
+      * Create an initializer options object. The option are set based on the
+      * input string. The options can be set by building a white space separated
+      * list of elements out of the
+      * following set of strings:
+      * "config=<file name>",
+      * "selftest",
+      * "fips140",
+      * "seed_rng",
+      * "use_engines",
+      * "secure_memory",
+      * "thread_safe"
+      *
+      */
+      InitializerOptions(const std::string& options);
    private:
       std::map<std::string, std::string> args;
    };
 
-/*************************************************
-* Library Initialization/Shutdown Object         *
-*************************************************/
+/**
+* This class represents the Library Initialization/Shutdown Object. It has to 
+* exceed the lifetime of any Botan object used in an application.
+*/
 class BOTAN_DLL LibraryInitializer
    {
    public:
@@ -40,8 +101,21 @@ class BOTAN_DLL LibraryInitializer
       static void initialize(const InitializerOptions&, class Modules&);
       static void deinitialize();
 
+      /**
+      * Construct a library initializer from a string. Does exactly the same
+      * as if an InitializerOptions object created with that string was used as
+      * the argument.
+      * @param args the string determining the desired library configuration
+      */
       LibraryInitializer(const std::string& args = "") { initialize(args); }
+
+      /**
+      * Construct a library initializer.
+      * @param args the initializer option object specifying the desired
+      * library configuration
+      */
       LibraryInitializer(const InitializerOptions& args) { initialize(args); }
+
       ~LibraryInitializer() { deinitialize(); }
    };
 
diff --git a/src/pubkey/pk_lookup/look_pk.h b/src/pubkey/pk_lookup/look_pk.h
index 28a56f2b3..926416a41 100644
--- a/src/pubkey/pk_lookup/look_pk.h
+++ b/src/pubkey/pk_lookup/look_pk.h
@@ -11,28 +11,65 @@
 
 namespace Botan {
 
-/*************************************************
-* Get an PK algorithm object                     *
-*************************************************/
-BOTAN_DLL PK_Encryptor* get_pk_encryptor(const PK_Encrypting_Key&,
-                                         const std::string&);
+/**
+* Public key encryptor factory method.
+* @param key the key that will work inside the encryptor
+* @param pad determines the algorithm and encoding
+* @return the public key encryptor object
+*/
+BOTAN_DLL PK_Encryptor* get_pk_encryptor(const PK_Encrypting_Key& key,
+                                         const std::string& pad);
 
-BOTAN_DLL PK_Decryptor* get_pk_decryptor(const PK_Decrypting_Key&,
-                                         const std::string&);
+/**
+* Public key decryptor factory method.
+* @param key the key that will work inside the decryptor
+* @param pad determines the algorithm and encoding
+* @return the public key decryptor object
+*/
+BOTAN_DLL PK_Decryptor* get_pk_decryptor(const PK_Decrypting_Key& key,
+                                         const std::string& pad);
 
-BOTAN_DLL PK_Signer* get_pk_signer(const PK_Signing_Key&,
-                                   const std::string&,
+/**
+* Public key signer factory method.
+* @param key the key that will work inside the signer
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_format the signature format to be used
+* @return the public key signer object
+*/
+BOTAN_DLL PK_Signer* get_pk_signer(const PK_Signing_Key& key,
+                                   const std::string& pad,
                                    Signature_Format = IEEE_1363);
 
-BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_with_MR_Key&,
-                                       const std::string&,
-                                       Signature_Format = IEEE_1363);
-BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_wo_MR_Key&,
-                                       const std::string&,
+/**
+* Public key verifier factory method.
+* @param key the key that will work inside the verifier
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_format the signature format to be used
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_with_MR_Key& key,
+                                       const std::string& pad,
                                        Signature_Format = IEEE_1363);
 
-BOTAN_DLL PK_Key_Agreement* get_pk_kas(const PK_Key_Agreement_Key&,
-                                       const std::string&);
+/**
+* Public key verifier factory method.
+* @param key the key that will work inside the verifier
+* @param pad determines the algorithm, encoding and hash algorithm
+* @param sig_form the signature format to be used
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Verifier* get_pk_verifier(const PK_Verifying_wo_MR_Key& key,
+                                       const std::string& pad,
+                                       Signature_Format sig_form = IEEE_1363);
+
+/**
+* Public key key agreement factory method.
+* @param key the key that will work inside the key agreement
+* @param pad determines the algorithm, encoding and hash algorithm
+* @return the public key verifier object
+*/
+BOTAN_DLL PK_Key_Agreement* get_pk_kas(const PK_Key_Agreement_Key& key,
+                                       const std::string& pad);
 
 }