Update documentation of KDF::derive_key overloads

randombit · Dec 3, 2024 · 97c0fb4 · 97c0fb4
1 parent 3214042
commit 97c0fb4
Showing 1 changed file with 16 additions and 20 deletions.
diff --git a/doc/api_ref/kdf.rst b/doc/api_ref/kdf.rst
@@ -34,6 +34,15 @@ two contexts.
       Create a new KDF object. Throws an exception if the named key derivation
       function was not available
 
+  .. cpp:function:: void derive_key(std::span<uint8_t> key,
+                                    std::span<const uint8_t> secret,
+                                    std::span<const uint8_t> salt,
+                                    std::span<const uint8_t> label) const
+
+      Performs a key derivation using ``secret`` as secret input, and ``salt``,
+      and ``label`` as deversifiers. The passed ``key`` buffer is fully filled
+      with key material derived from the inputs.
+
   .. cpp:function:: template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>> \
       T derive_key(size_t key_len, \
                    std::span<const uint8_t> secret, \
@@ -44,26 +53,13 @@ two contexts.
       to return a ``std::vector``, a ``secure_vector``, or anything else
       satisfying the ``resizable_byte_buffer`` concept.
 
-  .. cpp:function:: secure_vector<uint8_t> derive_key( \
-                                    const uint8_t secret[], \
-                                    size_t secret_len, \
-                                    const uint8_t salt[], \
-                                    size_t salt_len, \
-                                    const uint8_t label[], \
-                                    size_t label_len) 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 std::vector<uint8_t>& label) 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
+  .. cpp:function:: template<size_t key_len> \
+      std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret, \
+                                              std::span<const uint8_t> salt, \
+                                              std::span<const uint8_t> label) const
+
+      This version returns the key material as a std::array<> of ``key_len``
+      bytes.
 
    All variations on the same theme. Deterministically creates a
    uniform random value from *secret*, *salt*, and *label*, whose