Improve kdf doxygen [ci skip]

8 files changed, 54 insertions, 8 deletions

diff --git a/src/lib/kdf/hkdf/hkdf.h b/src/lib/kdf/hkdf/hkdf.h
index 1dba82ee2..a66d68da4 100644
--- a/src/lib/kdf/hkdf/hkdf.h
+++ b/src/lib/kdf/hkdf/hkdf.h
@@ -15,12 +15,16 @@
 namespace Botan {
 
 /**
-* HKDF, see @rfc 5869 for details
-* This is only the expansion portion of HKDF
+* HKDF, see RFC 5869 for details.
+* This is only the expansion portion of HKDF.
+* An appropriate extraction function should be used before.
 */
 class BOTAN_DLL HKDF final : public KDF
    {
    public:
+      /**
+      * @param prf underlying MAC algorithm
+      */
       explicit HKDF(MessageAuthenticationCode* prf) : m_prf(prf) {}
 
       static HKDF* make(const Spec& spec);
diff --git a/src/lib/kdf/kdf.h b/src/lib/kdf/kdf.h
index 3c8a7a013..f9acb9d38 100644
--- a/src/lib/kdf/kdf.h
+++ b/src/lib/kdf/kdf.h
@@ -25,25 +25,41 @@ class BOTAN_DLL KDF
 
       /**
       * Create an instance based on a name
-      * Will return a null pointer if the algo/provider combination cannot
-      * be found. If provider is empty then best available is chosen.
+      * If provider is empty then best available is chosen.
+      * @param algo_spec algorithm name
+      * @param provider provider implementation to choose
+      * @return a null pointer if the algo/provider combination cannot be found
       */
       static std::unique_ptr<KDF> create(const std::string& algo_spec,
                                          const std::string& provider = "");
 
       /**
-      * Returns the list of available providers for this algorithm, empty if not available
+      * @return list of available providers for this algorithm, empty if not available
       */
       static std::vector<std::string> providers(const std::string& algo_spec);
 
+      /**
+      * @return KDF name
+      */
       virtual std::string name() const = 0;
 
+      /**
+      * Derive a key
+      * @param key buffer holding the derived key, must be of length key_len
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param secret_len size of secret in bytes
+      * @param salt a diversifier
+      * @param salt_len size of salt in bytes
+      * @param label purpose for the derived keying material
+      * @param label_len size of label in bytes
+      * @return the derived key
+      */
       virtual size_t kdf(byte key[], size_t key_len,
                          const byte secret[], size_t secret_len,
                          const byte salt[], size_t salt_len,
                          const byte label[], size_t label_len) const = 0;
 
-
       /**
       * Derive a key
       * @param key_len the desired output length in bytes
@@ -53,6 +69,7 @@ class BOTAN_DLL KDF
       * @param salt_len size of salt in bytes
       * @param label purpose for the derived keying material
       * @param label_len size of label in bytes
+      * @return the derived key
       */
       secure_vector<byte> derive_key(size_t key_len,
                                     const byte secret[],
@@ -73,6 +90,7 @@ class BOTAN_DLL KDF
       * @param secret the secret input
       * @param salt a diversifier
       * @param label purpose for the derived keying material
+      * @return the derived key
       */
       secure_vector<byte> derive_key(size_t key_len,
                                     const secure_vector<byte>& secret,
@@ -93,6 +111,7 @@ class BOTAN_DLL KDF
       * @param secret the secret input
       * @param salt a diversifier
       * @param label purpose for the derived keying material
+      * @return the derived key
       */
       template<typename Alloc, typename Alloc2, typename Alloc3>
       secure_vector<byte> derive_key(size_t key_len,
@@ -113,6 +132,7 @@ class BOTAN_DLL KDF
       * @param salt a diversifier
       * @param salt_len size of salt in bytes
       * @param label purpose for the derived keying material
+      * @return the derived key
       */
       secure_vector<byte> derive_key(size_t key_len,
                                     const secure_vector<byte>& secret,
@@ -134,6 +154,7 @@ class BOTAN_DLL KDF
       * @param secret_len size of secret in bytes
       * @param salt a diversifier
       * @param label purpose for the derived keying material
+      * @return the derived key
       */
       secure_vector<byte> derive_key(size_t key_len,
                                     const byte secret[],
@@ -148,10 +169,12 @@ class BOTAN_DLL KDF
                            label.length());
          }
 
+      /**
+      * @return new object representing the same algorithm as *this
+      */
       virtual KDF* clone() const = 0;
 
       typedef SCAN_Name Spec;
-
    };
 
 /**
@@ -159,7 +182,7 @@ class BOTAN_DLL KDF
 * @param algo_spec the name of the KDF to create
 * @return pointer to newly allocated object of that type
 */
-BOTAN_DLL KDF*  get_kdf(const std::string& algo_spec);
+BOTAN_DLL KDF* get_kdf(const std::string& algo_spec);
 
 }
 
diff --git a/src/lib/kdf/kdf1/kdf1.h b/src/lib/kdf/kdf1/kdf1.h
index 59bff4d8d..b42478260 100644
--- a/src/lib/kdf/kdf1/kdf1.h
+++ b/src/lib/kdf/kdf1/kdf1.h
@@ -28,6 +28,9 @@ class BOTAN_DLL KDF1 final : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param h underlying hash function
+      */
       explicit KDF1(HashFunction* h) : m_hash(h) {}
    private:
       std::unique_ptr<HashFunction> m_hash;
diff --git a/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h b/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h
index f61864d1f..3d6047153 100644
--- a/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h
+++ b/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h
@@ -28,6 +28,9 @@ class BOTAN_DLL KDF1_18033 : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param h underlying hash function
+      */
       KDF1_18033(HashFunction* h) : m_hash(h) {}
    private:
       std::unique_ptr<HashFunction> m_hash;
diff --git a/src/lib/kdf/kdf2/kdf2.h b/src/lib/kdf/kdf2/kdf2.h
index 600f7c91c..e76b4574c 100644
--- a/src/lib/kdf/kdf2/kdf2.h
+++ b/src/lib/kdf/kdf2/kdf2.h
@@ -28,6 +28,9 @@ class BOTAN_DLL KDF2 final : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param h underlying hash function
+      */
       explicit KDF2(HashFunction* h) : m_hash(h) {}
    private:
       std::unique_ptr<HashFunction> m_hash;
diff --git a/src/lib/kdf/prf_tls/prf_tls.h b/src/lib/kdf/prf_tls/prf_tls.h
index 37a517125..bf2b9ea66 100644
--- a/src/lib/kdf/prf_tls/prf_tls.h
+++ b/src/lib/kdf/prf_tls/prf_tls.h
@@ -49,6 +49,9 @@ class BOTAN_DLL TLS_12_PRF final : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param mac underlying MAC algorithm
+      */
       explicit TLS_12_PRF(MessageAuthenticationCode* mac) : m_mac(mac) {}
 
       static TLS_12_PRF* make(const Spec& spec);
diff --git a/src/lib/kdf/sp800_108/sp800_108.h b/src/lib/kdf/sp800_108/sp800_108.h
index 71a918c15..3a5b33575 100644
--- a/src/lib/kdf/sp800_108/sp800_108.h
+++ b/src/lib/kdf/sp800_108/sp800_108.h
@@ -45,6 +45,9 @@ class BOTAN_DLL SP800_108_Counter : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param mac underlying MAC algorithm
+      */
       SP800_108_Counter(MessageAuthenticationCode* mac) : m_prf(mac) {}
 
       static SP800_108_Counter* make(const Spec& spec);
diff --git a/src/lib/kdf/sp800_56c/sp800_56c.h b/src/lib/kdf/sp800_56c/sp800_56c.h
index 1281ed314..83f11906a 100644
--- a/src/lib/kdf/sp800_56c/sp800_56c.h
+++ b/src/lib/kdf/sp800_56c/sp800_56c.h
@@ -45,6 +45,10 @@ class BOTAN_DLL SP800_56C : public KDF
                  const byte salt[], size_t salt_len,
                  const byte label[], size_t label_len) const override;
 
+      /**
+      * @param mac MAC algorithm used for randomness extraction
+      * @param exp KDF used for key expansion
+      */
       SP800_56C(MessageAuthenticationCode* mac, KDF* exp) : m_prf(mac), m_exp(exp) {}
 
       static SP800_56C* make(const Spec& spec);