From 344e0ae03bbf3ae3fb4e90eb41c2297f9dc43c6d Mon Sep 17 00:00:00 2001
From: lloyd <lloyd@randombit.net>
Date: Mon, 13 Oct 2008 18:27:40 +0000
Subject: More Doxygen comments from InSiTo

---
 src/cert/cvc/signed_obj.h | 50 ++++++++++++++++++++++++++++++++------
 src/core/s2k.h            | 62 +++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 100 insertions(+), 12 deletions(-)

(limited to 'src')

diff --git a/src/cert/cvc/signed_obj.h b/src/cert/cvc/signed_obj.h
index 2dfc91747..b55a3d7ec 100644
--- a/src/cert/cvc/signed_obj.h
+++ b/src/cert/cvc/signed_obj.h
@@ -15,26 +15,62 @@
 
 namespace Botan {
 
-/*************************************************
-* EAC SIGNED Object                              *
-*************************************************/
+/**
+* This class represents abstract signed EAC object
+*/
 class BOTAN_DLL EAC_Signed_Object
    {
    public:
+      /**
+      * Get the TBS (to-be-signed) data in this object.
+      * @return the DER encoded TBS data of this object
+      */
       virtual SecureVector<byte> tbs_data() const = 0;
-      virtual SecureVector<byte> get_concat_sig() const = 0;  // NOTE: this is here
-      // only because abstract
-      // signature objects have
-      // not yet been introduced
+
+      /**
+      * Get the signature of this object as a concatenation, i.e. if the
+      * signature consists of multiple parts (like in the case of ECDSA)
+      * these will be concatenated.
+      * @return the signature as a concatenation of its parts
+      */
+
+      /*
+       NOTE: this is here only because abstract signature objects have
+       not yet been introduced
+      */
+      virtual SecureVector<byte> get_concat_sig() const = 0;
+
       /**
       * Get the signature algorithm identifier used to sign this object.
       * @result the signature algorithm identifier
       */
       AlgorithmIdentifier signature_algorithm() const;
 
+      /**
+      * Check the signature of this object.
+      * @param key the public key associated with this signed object
+      * @return true if the signature was created by the private key
+      * associated with this public key
+      */
       virtual bool check_signature(class Public_Key&) const = 0;
+
+      /**
+      * Write this object DER encoded into a specified pipe.
+      * @param pipe the pipe to write the encoded object to
+      * @param enc the encoding type to use
+      */
       virtual void encode(Pipe&, X509_Encoding = PEM) const = 0;
+
+      /**
+      * BER encode this object.
+      * @return the result containing the BER representation of this object.
+      */
       SecureVector<byte> BER_encode() const;
+
+      /**
+      * PEM encode this object.
+      * @return the result containing the PEM representation of this object.
+      */
       std::string PEM_encode() const;
 
       EAC_Signed_Object(SharedPtrConverter<DataSource>, const std::string&);
diff --git a/src/core/s2k.h b/src/core/s2k.h
index 031592513..3efcff638 100644
--- a/src/core/s2k.h
+++ b/src/core/s2k.h
@@ -17,18 +17,70 @@ namespace Botan {
 class BOTAN_DLL S2K
    {
    public:
+      /**
+      * Create a copy of this object.
+      * @return an auto_ptr to a copy of this object
+      */
       virtual S2K* clone() const = 0;
+
+      /**
+      * Get the algorithm name.
+      * @return the name of this S2K algorithm
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Clear this objects internal values.
+      */
       virtual void clear() {}
 
-      OctetString derive_key(u32bit, const std::string&) const;
+      /**
+      * Derive a key from a passphrase with this S2K object. It will use
+      * the salt value and number of iterations configured in this object.
+      * @param key_len the desired length of the key to produce
+      * @param passphrase the password to derive the key from
+      */
+      OctetString derive_key(u32bit key_len,
+                             const std::string& passphrase) const;
+
+      /**
+      * Set the number of iterations for the one-way function during
+      * key generation.
+      * @param n the desired number of iterations
+      */
+      void set_iterations(u32bit n);
 
-      void set_iterations(u32bit);
-      void change_salt(const byte[], u32bit);
-      void change_salt(const MemoryRegion<byte>&);
-      void new_random_salt(RandomNumberGenerator& rng, u32bit);
+      /**
+      * Set a new salt value.
+      * @param new_salt a byte array defining the new salt value
+      * @param len the length of the above byte array
+      */
+      void change_salt(const byte new_salt[], u32bit len);
 
+      /**
+      * Set a new salt value.
+      * @param new_salt the new salt value
+      */
+      void change_salt(const MemoryRegion<byte>& new_salt);
+
+      /**
+      * Create a new random salt value using the rng
+      * @param rng the random number generator to use
+      * @param len the desired length of the new salt value
+      */
+      void new_random_salt(RandomNumberGenerator& rng, u32bit len);
+
+      /**
+      * Get the number of iterations for the key derivation currently
+      * configured in this S2K object.
+      * @return the current number of iterations
+      */
       u32bit iterations() const { return iter; }
+
+      /**
+      * Get the currently configured salt value of this S2K object.
+      * @return the current salt value
+      */
       SecureVector<byte> current_salt() const { return salt; }
 
       S2K() { iter = 0; }
-- 
cgit v1.2.3