EVP Key Derivation - Revision history

T8m at 06:42, 14 June 2022

2022-06-14T06:42:52Z

Pauli: Update KDF example code to match current API

2019-09-14T23:40:26Z

Update KDF example code to match current API

Matt: Updated version information for KDFs

2019-07-24T08:31:32Z

Updated version information for KDFs

Jwalton: /* HKDF key derivation */

2019-07-23T20:23:58Z

HKDF key derivation

Jwalton: Add error checking on EVP_KDF_CTX_new_id

2019-07-11T01:35:34Z

Add error checking on EVP_KDF_CTX_new_id

Jwalton: Tweak introduction.

2019-07-11T01:32:28Z

Tweak introduction.

Jwalton: Use 'derived' instead of 'out'

2019-07-11T01:23:59Z

Use 'derived' instead of 'out'

Jwalton: Add bullet points.

2019-07-11T01:21:31Z

Add bullet points.

Jwalton: Add KDF example; stop redirect to Key Agreement page.

2019-07-11T01:17:17Z

Add KDF example; stop redirect to Key Agreement page.

Matt: moved EVP Key Derivation to EVP Key Agreement: OpenSSL uses the "derive" function to perform key agreement. However more generally this process is referred to as key agreement - derivation can mean other things. All a bit confusing. Changing n

2013-04-01T14:49:30Z

moved EVP Key Derivation to EVP Key Agreement: OpenSSL uses the "derive" function to perform key agreement. However more generally this process is referred to as key agreement - derivation can mean other things. All a bit confusing. Changing n

New page

#REDIRECT [[EVP Key Agreement]]

@@ Line 59: / Line 59: @@
      /* Do the derivation */
-     if (EVP_KDF_derive(kctx, derived, sizeof(derived)) <= 0) {
+     if (EVP_KDF_derive(kctx, derived, sizeof(derived), NULL) <= 0) {
          error("EVP_KDF_derive");
+     }

@@ Line 26: / Line 26: @@
 <pre>#include <openssl/evp.h>
 #include <openssl/kdf.h>
 #include <stdio.h>
@@ Line 32: / Line 33: @@
 int main(int argc, char* argv[])
+{
      EVP_KDF_CTX *kctx = NULL;
      unsigned char derived[32];
-     if ((kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF)) == NULL) {
+    /* Find and allocate a context for the HKDF algorithm */
-         error("EVP_KDF_CTX_new_id");
+     if ((kdf = EVP_KDF_fetch(NULL, "hkdf", NULL)) == NULL) {
+     }
-     if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+     kctx = EVP_KDF_CTX_new(kdf);
-         error("EVP_KDF_CTRL_SET_MD");
+    EVP_KDF_free(kdf);    /* The kctx keeps a reference so this is safe */
+     }
-     if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
-        error("EVP_KDF_CTRL_SET_SALT");
+     /* Build up the parameters for the derivation */
+    *p++ = OSSL_PARAM_construct_utf8_string("digest", "sha256", (size_t)7);
-    if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+    *p++ = OSSL_PARAM_construct_octet_string("salt", "salt", (size_t)4);
-        error("EVP_KDF_CTRL_SET_KEY");
+     *p++ = OSSL_PARAM_construct_octet_string("key", "secret", (size_t)6);
+    *p++ = OSSL_PARAM_construct_octet_string("info", "label", (size_t)5);
-     if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
+     *p = OSSL_PARAM_construct_end();
-         error("EVP_KDF_CTRL_ADD_HKDF_INFO");
+     if (EVP_KDF_CTX_set_params(kctx, params) <= 0) {
+     }
      if (EVP_KDF_derive(kctx, derived, sizeof(derived)) <= 0) {
          error("EVP_KDF_derive");
+     }
-−
      /* Use the 32 bytes as a Key and IV */
      const unsigned char *key = derived+0;
      const unsigned char  *iv = derived+16;
-−
      printf("Key: ");
      for (size_t i=0; i<16; ++i)

← Older revision		Revision as of 08:31, 24 July 2019
Line 1:		Line 1:
−	Key derivation is the process of deriving one or more secret keys from a secret value such as a password or a passphrase. Several key derivation algoirthms have been standardized, and they are usually referred to a Key Derivation Functions (KDFs). KDFs include PBKDF2 from RFC 2898, HKDF form RFC 5869 and Scrypt from RFC 7914. OpenSSL provides PBKDF2, Scrypt, HKDF, ANSI X9.42 ~~and~~ ANSI X9.63 by way of <tt>EVP_KDF</tt>.	+	Key derivation is the process of deriving one or more secret keys from a secret value such as a password or a passphrase. Several key derivation algoirthms have been standardized, and they are usually referred to a Key Derivation Functions (KDFs). KDFs include PBKDF2 from RFC 2898, HKDF form RFC 5869 and Scrypt from RFC 7914.
		+
		+	OpenSSL 1.0.2 and above provides PBKDF2 by way of <tt>PKCS5_PBKDF2_HMAC</tt> and <tt>PKCS5_PBKDF2_HMAC_SHA1</tt>.
		+
		+	OpenSSL 1.1.0 and above additionally provides HKDF and TLS1 PRF KDF by way of <tt>EVP_PKEY_derive</tt> and Scrypt by way of <tt>EVP_PBE_scrypt</tt>
		+
		+	OpenSSL 1.1.1 and above additionally provides Scrypt by way of <tt>EVP_PKEY_derive</tt>.
		+
		+	OpenSSL 3.0 additionally provides Single Step KDF, SSH KDF, PBKDF2, Scrypt, HKDF, ANSI X9.42 KDF, ANSI X9.63 KDF and TLS1 PRF KDF by way of <tt>EVP_KDF</tt>.
		+
		+	From OpenSSL 3.0 the recommended way of performing key derivation is to use the EVP_KDF functions. If compatibility with OpenSSL 1.1.1 is required then a limited set of KDFs can be used via EVP_PKEY_derive.

−	Not all key derivation functions are available in all versions of OpenSSL. OpenSSL 1.0.2 and below provide WWW, XXX, YYY and ZZZ. OpenSSL 1.1.0 and above provide WWW, XXX, YYY and ZZZ. TODO: fill in the pieces here and talk about changes.

	== HKDF key derivation ==		== HKDF key derivation ==

@@ Line 5: / Line 5: @@
 == HKDF key derivation ==
-The following example derives a key and initialization vector using HKDF from RFC 5869. HKDF was designed by Krawczyk and Eronen, and it is state of the art in expand-then-extract key derivation algorithms. It is usually a good choice when you need a KDF. The program below was taken from the OpenSSL man pages.
+The following example derives a key and initialization vector using HKDF from RFC 5869 and SHA-256. HKDF was designed by Krawczyk and Eronen, and it is state of the art in expand-then-extract key derivation algorithms. It is usually a good choice when you need a KDF. The program below was taken from the OpenSSL man pages.
 HKDF takes three parameter:

@@ Line 26: / Line 26: @@
      unsigned char derived[32];
-     kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
+     if ((kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF)) == NULL) {
+        error("EVP_KDF_CTX_new_id");
      if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
          error("EVP_KDF_CTRL_SET_MD");

@@ Line 9: / Line 9: @@
 HKDF takes three parameter:
-<tt>secret</tt> - private information to use during derivation, like a password or passphrase. The parameter is set using <tt>EVP_KDF_CTRL_SET_KEY</tt>.
+* <tt>secret</tt> - private information to use during derivation, like a password or passphrase. The parameter is set using <tt>EVP_KDF_CTRL_SET_KEY</tt>.
-<tt>salt</tt> - possibly public information to use during derivation. <tt>salt</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_SET_SALT</tt>.
+* <tt>salt</tt> - possibly public information to use during derivation. <tt>salt</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_SET_SALT</tt>.
-<tt>info</tt> - additional, possibly public information to use during derivation. <tt>info</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_ADD_HKDF_INFO</tt>.
+* <tt>info</tt> - additional, possibly public information to use during derivation. <tt>info</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_ADD_HKDF_INFO</tt>.
 <pre>#include <openssl/evp.h>

← Older revision		Revision as of 01:17, 11 July 2019
Line 1:		Line 1:
−	#~~REDIRECT~~ [[~~EVP~~ Key ~~Agreement~~]]	+	Key derivation is the process of deriving one or more secret keys from a secret value such as a password or a passphrase. Several key derivation algoirthms have been standardized, and they are usually referred to a Key Derivation Functions (KDFs). KDFs include PBKDF2 from RFC 2898, HKDF form RFC 5869 and Scrypt from RFC 7914. OpenSSL provides PBKDF2, Scrypt, HKDF, ANSI X9.42 and ANSI X9.63 by way of <tt>EVP_KDF</tt>.
		+
		+	Not all key derivation functions are available in all versions of OpenSSL. OpenSSL 1.0.2 and below provide WWW, XXX, YYY and ZZZ. OpenSSL 1.1.0 and above provide WWW, XXX, YYY and ZZZ. TODO: fill in the pieces here and talk about changes.
		+
		+	== HKDF key derivation ==
		+
		+	The following program derives a key using HKDF from RFC 5869. HKDF was designed by Krawczyk and Eronen, and it is state of the art in expand-then-extract key derivation algorithms. It is usually a good choice when you need a KDF. The program below was taken from the OpenSSL man pages.
		+
		+	HKDF takes three parameter:
		+
		+	<tt>secret</tt> - private information to use during derivation, like a password or passphrase. The parameter is set using <tt>EVP_KDF_CTRL_SET_KEY</tt>.
		+
		+	<tt>salt</tt> - possibly public information to use during derivation. <tt>salt</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_SET_SALT</tt>.
		+
		+	<tt>info</tt> - additional, possibly public information to use during derivation. <tt>info</tt> is optional. The parameter is set using <tt>EVP_KDF_CTRL_ADD_HKDF_INFO</tt>.
		+
		+	<pre>#include <openssl/evp.h>
		+	#include <openssl/kdf.h>
		+
		+	#include <stdio.h>
		+	#include <stdlib.h>
		+
		+	int main(int argc, char* argv[])
		+	{
		+	EVP_KDF_CTX *kctx = NULL;
		+	unsigned char out[32];
		+
		+	kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
		+
		+	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
		+	error("EVP_KDF_CTRL_SET_MD");
		+	}
		+	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
		+	error("EVP_KDF_CTRL_SET_SALT");
		+	}
		+	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
		+	error("EVP_KDF_CTRL_SET_KEY");
		+	}
		+	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
		+	error("EVP_KDF_CTRL_ADD_HKDF_INFO");
		+	}
		+	if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
		+	error("EVP_KDF_derive");
		+	}
		+
		+	/* Use the 32 bytes as a Key and IV */
		+	const unsigned char *key = out+0;
		+	const unsigned char *iv = out+16;
		+
		+	printf("Key: ");
		+	for (size_t i=0; i<16; ++i)
		+	printf("%02x ", key[i]);
		+	printf("\n");
		+
		+	printf("IV: ");
		+	for (size_t i=0; i<16; ++i)
		+	printf("%02x ", iv[i]);
		+	printf("\n");
		+
		+	EVP_KDF_CTX_free(kctx);
		+
		+	return 0;
		+	}</pre>
		+
		+	You can compile the program using C99 with the following command.
		+
		+	<pre>openssl$ gcc -std=c99 test.c -o test.exe -l:libcrypto.a -pthread -ldl
		+	openssl$</pre>
		+
		+	Running the program results in the following output.
		+
		+	<pre>$ ./test.exe
		+	Key: 2a c4 36 9f 52 59 96 f8 de 13 73 1f 56 22 4f 34
		+	IV: df 0e 4c 96 ca a9 3b fd ec cf 23 7b 50 39 c8 db</pre>