diff options
author | Nikos Mavrogiannopoulos <nmav@redhat.com> | 2017-05-17 16:29:40 +0200 |
---|---|---|
committer | Niels Möller <nisse@lysator.liu.se> | 2017-08-30 18:19:43 +0200 |
commit | 8791cbfd6941551cfd27835763ef312eab1ead0f (patch) | |
tree | 46d3535fd73b2b061141269fd90fb62abd9fcafa /nettle.texinfo | |
parent | 8ee43114c80fd76dbe03128883015a0d24e052aa (diff) | |
download | nettle-8791cbfd6941551cfd27835763ef312eab1ead0f.tar.gz |
doc: added HKDF documentation
Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>
Diffstat (limited to 'nettle.texinfo')
-rw-r--r-- | nettle.texinfo | 49 |
1 files 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}. |