Implement concrete PBKDF2 functions.

diff --git a/ChangeLog b/ChangeLog
index 049c3ddc52582faaf367d208849f266d0fddff30..efb578e0437146b344ed5fbf11ae42e45cb03eba 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+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.

diff --git a/Makefile.in b/Makefile.in
index 7c6cf337e6fa09e7d6032d79aa53509306234e41..9904be5db70d824c98a896a402ea9dd84be8009e 100644 (file)
--- a/Makefile.in
+++ b/Makefile.in
@@ -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 \

diff --git a/nettle.texinfo b/nettle.texinfo
index a333779a6541d88a2439ae8c9c3fb62503550855..c73861bf24b97c452c3df6bfaa5e8f218c509fa0 100644 (file)
--- a/nettle.texinfo
+++ b/nettle.texinfo
@@ -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

diff --git a/pbkdf2-hmac-sha1.c b/pbkdf2-hmac-sha1.c
new file mode 100644 (file)
index 0000000..9185503
--- /dev/null
+++ b/pbkdf2-hmac-sha1.c
@@ -0,0 +1,45 @@
+/* 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);
+}

diff --git a/pbkdf2-hmac-sha256.c b/pbkdf2-hmac-sha256.c
new file mode 100644 (file)
index 0000000..448f676
--- /dev/null
+++ b/pbkdf2-hmac-sha256.c
@@ -0,0 +1,45 @@
+/* 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);
+}

diff --git a/pbkdf2.h b/pbkdf2.h
index aa615676555f2218b6b3c443ee122d9faa5c59c8..bf152544f1a0d932c080bbf0b1d3fe9d6255458a 100644 (file)
--- a/pbkdf2.h
+++ b/pbkdf2.h
@@ -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

diff --git a/testsuite/pbkdf2-test.c b/testsuite/pbkdf2-test.c
index 6ef58328b3708fe61604326f7ac92ae6e43909bb..c0d2eaec44cccd87318b295972681899cdf8d743 100644 (file)
--- a/testsuite/pbkdf2-test.c
+++ b/testsuite/pbkdf2-test.c
@@ -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"));
+
 }