On Fri, Jul 7, 2017 at 9:24 PM, Niels Möller <ni...@lysator.liu.se> wrote:
> Nikos Mavrogiannopoulos <n.mavrogiannopou...@gmail.com> writes:
>
>> On Mon, 2017-05-22 at 19:09 +0200, Niels Möller wrote:
>>
>>> Is it required that hkdf_extract is used in some way to produce the
>>> key
>>> for hkdf_expand? Then I think the relation between _extract and
>>> _expand
>>> needs to be clarified. Would you always have the same number of calls
>>> to
>>> _extract and _expand, or could do _extract once and _expand multiple
>>> times (with different info string)?
>>
>> I'm not sure what you mean. The relation is defined in HKDF document,
>> though upper protocols like tls 1.3 may utilize these in arbitrary
>> ways. Nettle provides the implementation of the primitives.
>
> Sorry this got a bit stalled. I would like the Nettle docs to be
> reasonably self-contained, and explain what the primitive does, what
> problem it is intended to solve, and the typical way to use it. And in
> case terminology in the relevant RFC or other literature differs from
> what's used elsewhere in the Nettle manual, point of how they relate. In
> particuler, I found the "salt"/"key"/"secret" arguments a bit confusing,
> as well as the purpose of the _extract function.
If the changes below are not sufficient, please provide some concrete
suggestions for the terminology to use. I've tried to keep the
terminology consistent with the only other key derivation algorithm
(PBKDF2) but I may have failed on that.
> With your current patch to the docs, I'll have to read the HKDF spec
> carefully myself to be able to review the code and the docs, and I
> haven't yet gotten the time to do that. Clear and more self-contained
> documentation would make this easier.
I have modified the text to be more self-contained and clarify the
role of the variables, which may address terminology as well. Let me
know if that's ok.
regards,
Nikos
From b19d91a089eca5cd72887a488ad8103fd5a22381 Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <n...@redhat.com>
Date: Wed, 17 May 2017 16:29:40 +0200
Subject: [PATCH] doc: added HKDF documentation
Signed-off-by: Nikos Mavrogiannopoulos <n...@redhat.com>
---
nettle.texinfo | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 44 insertions(+), 5 deletions(-)
diff --git a/nettle.texinfo b/nettle.texinfo
index 1d7e4e3e..6eada3db 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,51 @@ 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
+
+HKDF is a key derivation function used as a building block of
+higher-level protocols like TLS 1.3. It is a derivation function
+based on HMAC described in @cite{RFC 5869},
+and is split into two logical modules, called 'extract' and 'expand'.
+The extract module takes an initial secret and a random
+salt to "extract" a fixed-length pseudorandom key (PRK). The second stage
+takes as input the previous PRK and some informational data (e.g.,
+text) and expands them into multiple keys.
+
+Nettle's @acronym{HKDF} functions are defined in
+@file{<nettle/hkdf.h>}. There are two abstract functions for the extract
+and expand operations that operate on any HMAC implemented via the @code{nettle_hash_update_func},
+and @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 @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.13.0
_______________________________________________
nettle-bugs mailing list
nettle-bugs@lists.lysator.liu.se
http://lists.lysator.liu.se/mailman/listinfo/nettle-bugs
