From f8cb1a2b40bfb1091652831a4a685ddbe39004fb Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <nmav@redhat.com>
Date: Wed, 17 May 2017 16:29:40 +0200
Subject: [PATCH 6/6] doc: added HKDF and TLS-PRF documentation

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>
---
 nettle.texinfo | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 76 insertions(+), 5 deletions(-)

diff --git a/nettle.texinfo b/nettle.texinfo
index 1d7e4e3..0960e51 100644
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -3366,12 +3366,7 @@ processing a new message.
 @node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference
 @comment  node-name,  next,  previous,  up
 @section Key derivation Functions
-
 @cindex Key Derivation Function
-@cindex Password Based Key Derivation Function
-@cindex PKCS #5
-@cindex KDF
-@cindex PBKDF
 
 A @dfn{key derivation function} (@acronym{KDF}) is a function that from
 a given symmetric key derives other symmetric keys.  A sub-class of KDFs
@@ -3380,7 +3375,83 @@ which take as input a password or passphrase, and its purpose is
 typically to strengthen it and protect against certain pre-computation
 attacks by using salting and expensive computation.
 
+@subsection HKDF: HMAC-based Extract-and-Expand
+@cindex HKDF
+
+The key derivation function used in TLS 1.3 is HKDF, described
+in @cite{RFC 5869}, and is a derivation function based on HMAC.
+
+Nettle's @acronym{HKDF} functions are defined in
+@file{<nettle/hkdf.h>}.  There are two abstract functions for extract
+and expand operations that operate on any HMAC implemented via the @code{nettle_hash_update_func},
+@code{nettle_hash_digest_func} interfaces.
+
+@deftypefun void hkdf_extract (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size,size_t secret_size, const uint8_t *secret,  uint8_t *dst)
+Extract a Pseudorandom Key (PRK) from a secret and a salt according
+to HKDF. The HMAC must have been initialized, with its key being the
+salt for the Extract operation. This function will call the
+@var{update} and @var{digest} functions passing the @var{mac_ctx}
+context parameter as an argument in order to compute digest of size
+@var{digest_size}.  Inputs are the secret @var{secret} of length
+@var{secret_length}. The output length is fixed to @var{digest_size} octets,
+thus the output buffer @var{dst} must have room for at least @var{digest_size} octets.
+@end deftypefun
+
+@deftypefun void hkdf_expand (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size, size_t info_size, const uint8_t *info, size_t length, uint8_t *dst)
+Expand a Pseudorandom Key (PRK) to an arbitrary size according to HKDF.
+The HMAC must have been initialized, with its key being the
+PRK from the Extract operation. This function will call the
+@var{update} and @var{digest} functions passing the @var{mac_ctx}
+context parameter as an argument in order to compute digest of size
+@var{digest_size}.  Inputs are the info @var{info} of length
+@var{info_length}, and the desired derived output length @var{length}.
+The output buffer is @var{dst} which must have room for at least @var{length} octets.
+@end deftypefun
+
+
+@subsection TLS-PRF: TLS Pseudo Random Function
+@cindex PRF
+@cindex TLS-PRF
+
+The key derivation functions used in TLS 1.0 and TLS 1.2, described
+in @cite{RFC 2246}, and @cite{RFC 5246}, and are key derivation functions
+based on HMAC.
+
+Nettle's @acronym{TLS-PRF} functions are defined in
+@file{<nettle/tls1-prf.h>}.  There are two abstract functions for TLS 1.0,
+based on SHA1 and MD5, and TLS 1.2, that operates on any HMAC implemented via
+the @code{nettle_hash_update_func}, @code{nettle_hash_digest_func} interfaces.
+
+@deftypefun void tls10_prf (size_t secret_size, const uint8_t *secret, size_t label_size, const char *label, size_t seed_size, const uint8_t *seed, size_t length, uint8_t *dst)
+Derive a Pseudorandom Key from a secret, label and a seed according
+to TLS 1.0.  Inputs are the secret @var{secret} of length
+@var{secret_length}, the label @var{label} of length
+@var{label_length}, the seed @var{seed} of length
+@var{seed_length} and the desired derived output length @var{length}.
+The output buffer is @var{dst} which must have room for at least @var{length} octets.
+@end deftypefun
+
+@deftypefun void tls12_prf (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size, size_t label_size, const char *label, size_t seed_size, const uint8_t *seed, size_t length, uint8_t *dst)
+Derive a Pseudorandom Key from a secret, label and a seed according
+to TLS 1.2. The HMAC must have been initialized, with its key being the
+secret to be used. This function will call the @var{update} and @var{digest}
+functions passing the @var{mac_ctx} context parameter as an argument in order
+to compute digest of size @var{digest_size}.
+Inputs are the secret @var{secret} of length
+@var{secret_length}, the label @var{label} of length
+@var{label_length}, the seed @var{seed} of length
+@var{seed_length} and the desired derived output length @var{length}.
+The output buffer is @var{dst} which must have room for at least @var{length} octets.
+@end deftypefun
+
+
+
+
 @subsection @acronym{PBKDF2}
+@cindex Password Based Key Derivation Function
+@cindex PKCS #5
+@cindex KDF
+@cindex PBKDF
 The most well known PBKDF is the @code{PKCS #5 PBKDF2} described in
 @cite{RFC 2898} which uses a pseudo-random function such as
 @acronym{HMAC-SHA1}.
-- 
2.9.3

