Commit 90320ba2 authored by Simon Josefsson's avatar Simon Josefsson Committed by Niels Möller

Implement concrete PBKDF2 functions.

parent d5a173c7
2012-09-20 Simon Josefsson <simon@josefsson.org>
* pbkdf2-hmac-sha1.c, pbkdf2-hmac-sha256.c: New files.
* pbkdf2.h (pbkdf2_hmac_sha1, pbkdf2_hmac_sha256): New prototypes.
* Makefile.in (nettle_SOURCES): Add pbkdf2-hmac-sha1.c and
pbkdf2-hmac-sha256.c.
* nettle.texinfo (Key derivation functions): Improve.
* testsuite/pbkdf2-test.c (test_main): Test new functions.
2012-09-20 Niels Möller <nisse@lysator.liu.se>
* pbkdf2.c (pbkdf2): Reordered arguments, for consistency.
......
......@@ -77,7 +77,7 @@ nettle_SOURCES = aes-decrypt-internal.c aes-decrypt.c \
des3.c des-compat.c \
hmac.c hmac-md5.c hmac-ripemd160.c hmac-sha1.c \
hmac-sha224.c hmac-sha256.c hmac-sha384.c hmac-sha512.c \
pbkdf2.c \
pbkdf2.c pbkdf2-hmac-sha1.c pbkdf2-hmac-sha256.c \
knuth-lfib.c \
md2.c md2-meta.c md4.c md4-meta.c \
md5.c md5-compress.c md5-compat.c md5-meta.c \
......
......@@ -2123,12 +2123,19 @@ a given symmetric key derives other symmetric keys. A sub-class of KDFs
is the @dfn{password-based key derivation functions} (@acronym{PBKDFs}),
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. The most well known
PBKDF is the @code{PKCS #5 PBKDF2} described in @cite{RFC 2898} which
uses a pseudorandom function such as @acronym{HMAC-SHA1}.
attacks by using salting and expensive computation.
Nettle's @acronym{PBKDF2} function is defined in @file{<nettle/pbkdf2.h>}.
It contains a function:
@subsection @acronym{PBKDF2}
The most well known PBKDF is the @code{PKCS #5 PBKDF2} described in
@cite{RFC 2898} which uses a pseudorandom function such as
@acronym{HMAC-SHA1}.
Nettle's @acronym{PBKDF2} functions are defined in
@file{<nettle/pbkdf2.h>}. There is an abstract function that operate on
any PRF implemented via the @code{nettle_hash_update_func},
@code{nettle_hash_digest_func} interfaces. There is also helper macros
and concrete functions PBKDF2-HMAC-SHA1 and PBKDF2-HMAC-SHA256. First,
the abstract function:
@deftypefun void pbkdf2 (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, unsigned digest_size, unsigned iterations, unsigned salt_length, const uint8_t *salt, unsigned length, uint8_t *dst)
Derive symmetric key from a password according to PKCS #5 PBKDF2. The
......@@ -2141,6 +2148,44 @@ desired derived output length @var{length}. The output buffer is
@var{dst} which must have room for at least @var{length} octets.
@end deftypefun
Like for CBC and HMAC, there is a macros to help use the functions
correctly.
@deffn Macro PBKDF2 (@var{ctx}, @var{update}, @var{digest}, @var{digest_size}, @var{iterations}, @var{salt_length}, @var{salt}, @var{length}, @var{dst})
@var{ctx} is a pointer to a context struct passed to the @var{update}
and @var{digest} functions (of the types @code{nettle_hash_update_func}
and @code{nettle_hash_digest_func} respectively) to implement the
underlying PRF with digest size of @var{digest_size}. Inputs are the
salt @var{salt} of length @var{salt_length}, the iteration counter
@var{iterations} (> 0), 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 deffn
@subsection Concrete @acronym{PBKDF2} functions
Now we come to the specialized @acronym{PBKDF2} functions, which are
easier to use than the general @acronym{PBKDF2} function.
@subsubsection @acronym{PBKDF2-HMAC-SHA1}
@deftypefun void pbkdf2_hmac_sha1 (unsigned @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, unsigned @var{salt_length}, const uint8_t *@var{salt}, unsigned @var{length}, uint8_t *@var{dst})
PBKDF2 with HMAC-SHA1. Derive @var{length} bytes of key into buffer
@var{dst} using the password @var{key} of length @var{key_length} and
salt @var{salt} of length @var{salt_length}, with iteration counter
@var{iterations} (> 0). The output buffer is @var{dst} which must have
room for at least @var{length} octets.
@end deftypefun
@subsubsection @acronym{PBKDF2-HMAC-SHA256}
@deftypefun void pbkdf2_hmac_sha256 (unsigned @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, unsigned @var{salt_length}, const uint8_t *@var{salt}, unsigned @var{length}, uint8_t *@var{dst})
PBKDF2 with HMAC-SHA256. Derive @var{length} bytes of key into buffer
@var{dst} using the password @var{key} of length @var{key_length} and
salt @var{salt} of length @var{salt_length}, with iteration counter
@var{iterations} (> 0). The output buffer is @var{dst} which must have
room for at least @var{length} octets.
@end deftypefun
@node Public-key algorithms, Randomness, Key derivation functions, Reference
@comment node-name, next, previous, up
@section Public-key algorithms
......
/* pbkdf2-hmac-sha1.c
*
* PKCS #5 PBKDF2 used with HMAC-SHA1, see RFC 2898.
*/
/* nettle, low-level cryptographics library
*
* Copyright (C) 2012 Simon Josefsson
*
* The nettle library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or (at your
* option) any later version.
*
* The nettle library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
* License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with the nettle library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02111-1301, USA.
*/
#if HAVE_CONFIG_H
# include "config.h"
#endif
#include "pbkdf2.h"
#include "hmac.h"
void
pbkdf2_hmac_sha1 (unsigned key_length, const uint8_t *key,
unsigned iterations,
unsigned salt_length, const uint8_t *salt,
unsigned length, uint8_t *dst)
{
struct hmac_sha1_ctx sha1ctx;
hmac_sha1_set_key (&sha1ctx, key_length, key);
PBKDF2 (&sha1ctx, hmac_sha1_update, hmac_sha1_digest,
SHA1_DIGEST_SIZE, iterations, salt_length, salt, length, dst);
}
/* pbkdf2-hmac-sha256.c
*
* PKCS #5 PBKDF2 used with HMAC-SHA256, see RFC 2898.
*/
/* nettle, low-level cryptographics library
*
* Copyright (C) 2012 Simon Josefsson
*
* The nettle library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or (at your
* option) any later version.
*
* The nettle library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
* License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with the nettle library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02111-1301, USA.
*/
#if HAVE_CONFIG_H
# include "config.h"
#endif
#include "pbkdf2.h"
#include "hmac.h"
void
pbkdf2_hmac_sha256 (unsigned key_length, const uint8_t *key,
unsigned iterations,
unsigned salt_length, const uint8_t *salt,
unsigned length, uint8_t *dst)
{
struct hmac_sha256_ctx sha256ctx;
hmac_sha256_set_key (&sha256ctx, key_length, key);
PBKDF2 (&sha256ctx, hmac_sha256_update, hmac_sha256_digest,
SHA256_DIGEST_SIZE, iterations, salt_length, salt, length, dst);
}
......@@ -35,6 +35,8 @@ extern "C"
/* Namespace mangling */
#define pbkdf2 nettle_pbkdf2
#define pbkdf2_hmac_sha1 nettle_pbkdf2_hmac_sha1
#define pbkdf2_hmac_sha256 nettle_pbkdf2_hmac_sha256
void
pbkdf2 (void *mac_ctx,
......@@ -54,6 +56,20 @@ pbkdf2 (void *mac_ctx,
(digest_size), (iterations), \
(salt_length), (salt), (length), (dst)))
/* PBKDF2 with specific PRFs. */
void
pbkdf2_hmac_sha1 (unsigned key_length, const uint8_t *key,
unsigned iterations,
unsigned salt_length, const uint8_t *salt,
unsigned length, uint8_t *dst);
void
pbkdf2_hmac_sha256 (unsigned key_length, const uint8_t *key,
unsigned iterations,
unsigned salt_length, const uint8_t *salt,
unsigned length, uint8_t *dst);
#ifdef __cplusplus
}
#endif
......
......@@ -12,6 +12,14 @@
ASSERT(dk[expect->length] == 17); \
} while (0)
#define PBKDF2_HMAC_TEST(f, key, c, salt, expect) \
do { \
dk[expect->length] = 17; \
f (key, c, salt, expect->length, dk); \
ASSERT(MEMEQ (expect->length, dk, expect->data)); \
ASSERT(dk[expect->length] == 17); \
} while (0)
#define MAX_DKLEN 25
void
......@@ -69,4 +77,13 @@ test_main (void)
PBKDF2_TEST (&sha256ctx, hmac_sha256_update, hmac_sha256_digest,
SHA256_DIGEST_SIZE, 80000, LDATA("NaCl"),
SHEX("4ddcd8f60b98be21830cee5ef22701f9"));
/* Test convenience functions. */
PBKDF2_HMAC_TEST(pbkdf2_hmac_sha1, LDATA("password"), 1, LDATA("salt"),
SHEX("0c60c80f961f0e71f3a9b524af6012062fe037a6"));
PBKDF2_HMAC_TEST(pbkdf2_hmac_sha256, LDATA("passwd"), 1, LDATA("salt"),
SHEX("55ac046e56e3089fec1691c22544b605"));
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment