aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/kdf
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/kdf')
-rw-r--r--src/lib/kdf/hkdf/hkdf.h8
-rw-r--r--src/lib/kdf/kdf.h35
-rw-r--r--src/lib/kdf/kdf1/kdf1.h3
-rw-r--r--src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h3
-rw-r--r--src/lib/kdf/kdf2/kdf2.h3
-rw-r--r--src/lib/kdf/prf_tls/prf_tls.h3
-rw-r--r--src/lib/kdf/sp800_108/sp800_108.h3
-rw-r--r--src/lib/kdf/sp800_56c/sp800_56c.h4
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);
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 03:11:17 +0000