From 327c1627923288d3dbbfc34d1c7d8785552f6ad8 Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Tue, 8 Nov 2016 10:25:21 +0000
Subject: [PATCH] Add some documentation for the new HKDF modes

Reviewed-by: Rich Salz <rsalz@openssl.org>
---
 doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod | 58 ++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
index ab6fbf63ee..1115e136c5 100644
--- a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
@@ -3,13 +3,16 @@
 =head1 NAME
 
 EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt,
-EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info -
+EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info,
+EVP_PKEY_CTX_hkdf_mode -
 HMAC-based Extract-and-Expand key derivation algorithm
 
 =head1 SYNOPSIS
 
  #include <openssl/kdf.h>
 
+ int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *pctx, int mode);
+
  int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
 
  int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
@@ -30,6 +33,41 @@ and "extracts" from it a fixed-length pseudorandom key K. The second stage
 "expands" the key K into several additional pseudorandom keys (the output
 of the KDF).
 
+EVP_PKEY_CTX_hkdf_mode() sets the mode for the HKDF operation. There are three
+modes that are currently defined:
+
+=over 4
+
+=item EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND
+
+This is the default mode. Calling L<EVP_PKEY_derive(3)> on an EVP_PKEY_CTX set
+up for HKDF will perform an extract followed by an expand operation in one go.
+The derived key returned will be the result after the expand operation. The
+intermediate fixed-length pseudorandom key K is not returned.
+
+In this mode the digest, key, salt and info values must be set before a key is
+derived or an error occurs.
+
+=item EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY
+
+In this mode calling L<EVP_PKEY_derive(3)> will just perform the extract
+operation. The value returned will be the intermediate fixed-length pseudorandom
+key K.
+
+The digest, key and salt values must be set before a key is derived or an
+error occurs.
+
+=item EVP_PKEY_HKDEF_MODE_EXPAND_ONLY
+
+In this mode calling L<EVP_PKEY_derive(3)> will just perform the expand
+operation. The input key should be set to the intermediate fixed-length
+pseudorandom key K returned from a previous extract operation.
+
+The digest, key and info values must be set before a key is derived or an
+error occurs.
+
+=back
+
 EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF.
 
 EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the
@@ -48,6 +86,8 @@ HKDF also supports string based control operations via
 L<EVP_PKEY_CTX_ctrl_str(3)>.
 The B<type> parameter "md" uses the supplied B<value> as the name of the digest
 algorithm to use.
+The B<type> parameter "mode" uses the values "EXTRACT_AND_EXPAND",
+"EXTRACT_ONLY" and "EXPAND_ONLY" to determine the mode to use.
 The B<type> parameters "salt", "key" and "info" use the supplied B<value>
 parameter as a B<seed>, B<key> or B<info> value.
 The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex
@@ -61,19 +101,17 @@ A context for HKDF can be obtained by calling:
 
  EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL);
 
-The digest, key, salt and info values must be set before a key is derived or
-an error occurs.
-
 The total length of the info buffer cannot exceed 1024 bytes in length: this
 should be more than enough for any normal use of HKDF.
 
-The output length of the KDF is specified via the length parameter to the
-L<EVP_PKEY_derive(3)> function.
+The output length of an HKDF expand operation is specified via the length
+parameter to the L<EVP_PKEY_derive(3)> function.
 Since the HKDF output length is variable, passing a B<NULL> buffer as a means
-to obtain the requisite length is not meaningful with HKDF.
-Instead, the caller must allocate a buffer of the desired length, and pass that
-buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the
-desired length.
+to obtain the requisite length is not meaningful with HKDF in any mode that
+performs an expand operation. Instead, the caller must allocate a buffer of the
+desired length, and pass that buffer to L<EVP_PKEY_derive(3)> along with (a
+pointer initialized to) the desired length. Passing a B<NULL> buffer to obtain
+the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY.
 
 Optimised versions of HKDF can be implemented in an ENGINE.
 
-- 
2.25.1