Reorg documentation layout. Rename manual to handbook.

1 files changed, 106 insertions, 0 deletions

diff --git a/doc/api_ref/kdf.rst b/doc/api_ref/kdf.rst
new file mode 100644
index 000000000..bc126cbab
--- /dev/null
+++ b/doc/api_ref/kdf.rst
@@ -0,0 +1,106 @@
+
+.. _key_derivation_function:
+
+Key Derivation Functions
+========================================
+
+Key derivation functions are used to turn some amount of shared secret
+material into uniform random keys suitable for use with symmetric
+algorithms. An example of an input which is useful for a KDF is a
+shared secret created using Diffie-Hellman key agreement.
+
+.. cpp:class:: KDF
+
+  .. cpp:function:: secure_vector<uint8_t> derive_key( \
+     size_t key_len, const std::vector<uint8_t>& secret, \
+     const std::string& salt = "") const
+
+  .. cpp:function:: secure_vector<uint8_t> derive_key( \
+     size_t key_len, const std::vector<uint8_t>& secret, \
+     const std::vector<uint8_t>& salt) const
+
+  .. cpp:function:: secure_vector<uint8_t> derive_key( \
+     size_t key_len, const std::vector<uint8_t>& secret, \
+     const uint8_t* salt, size_t salt_len) const
+
+  .. cpp:function:: secure_vector<uint8_t> derive_key( \
+     size_t key_len, const uint8_t* secret, size_t secret_len, \
+     const std::string& salt) const
+
+   All variations on the same theme. Deterministically creates a
+   uniform random value from *secret* and *salt*. Typically *salt* is
+   a label or identifier, such as a session id.
+
+You can create a :cpp:class:`KDF` using
+
+.. cpp:function:: KDF* get_kdf(const std::string& algo_spec)
+
+
+Available KDFs
+-------------------
+
+Botan includes many different KDFs simply because different protocols and
+standards have created subtly different approaches to this problem. For new
+code, use HKDF which is conservative, well studied, widely implemented and NIST
+approved.
+
+HKDF
+~~~~~
+
+Defined in RFC 5869, HKDF uses HMAC to process inputs. Also available
+are variants HKDF-Extract and HKDF-Expand. HKDF is the combined
+Extract+Expand operation. Use the combined HKDF unless you need
+compatibility with some other system.
+
+Available if ``BOTAN_HAS_HKDF`` is defined.
+
+KDF2
+~~~~~
+
+KDF2 comes from IEEE 1363. It uses a hash function.
+
+Available if ``BOTAN_HAS_KDF2`` is defined.
+
+KDF1-18033
+~~~~~~~~~~~~
+
+KDF1 from ISO 18033-2. Very similar to (but incompatible with) KDF2.
+
+Available if ``BOTAN_HAS_KDF1_18033`` is defined.
+
+KDF1
+~~~~~~
+
+KDF1 from IEEE 1363. It can only produce an output at most the length
+of the hash function used.
+
+Available if ``BOTAN_HAS_KDF1`` is defined.
+
+X9.42 PRF
+~~~~~~~~~~
+
+A KDF from ANSI X9.42. Sometimes used for Diffie-Hellman.
+
+Available if ``BOTAN_HAS_X942_PRF`` is defined.
+
+SP800-108
+~~~~~~~~~~
+
+KDFs from NIST SP 800-108. Variants include "SP800-108-Counter",
+"SP800-108-Feedback" and "SP800-108-Pipeline".
+
+Available if ``BOTAN_HAS_SP800_108`` is defined.
+
+SP800-56A
+~~~~~~~~~~
+
+KDF from NIST SP 800-56A.
+
+Available if ``BOTAN_HAS_SP800_56A`` is defined.
+
+SP800-56C
+~~~~~~~~~~
+
+KDF from NIST SP 800-56C.
+
+Available if ``BOTAN_HAS_SP800_56C`` is defined.