Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969386550 php.internals:98791
Return-Path: <yohgaki@ohgaki.net>
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Delivered-To: mailing list internals@lists.php.net
Received: (qmail 45580 invoked from network); 13 Apr 2017 21:23:20 -0000
Received: from unknown (HELO lists.php.net) (127.0.0.1)
  by localhost with SMTP; 13 Apr 2017 21:23:20 -0000
Authentication-Results: pb1.pair.com smtp.mail=yohgaki@ohgaki.net; spf=pass; sender-id=pass
Authentication-Results: pb1.pair.com header.from=yohgaki@ohgaki.net; sender-id=pass
Received-SPF: pass (pb1.pair.com: domain ohgaki.net designates 180.42.98.130 as permitted sender)
X-PHP-List-Original-Sender: yohgaki@ohgaki.net
X-Host-Fingerprint: 180.42.98.130 ns1.es-i.jp  
Received: from [180.42.98.130] ([180.42.98.130:46678] helo=es-i.jp)
	by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP
	id E3/51-31410-54CEFE85 for <internals@lists.php.net>; Thu, 13 Apr 2017 17:23:19 -0400
Received: (qmail 35176 invoked by uid 89); 13 Apr 2017 21:23:13 -0000
Received: from unknown (HELO mail-qk0-f173.google.com) (yohgaki@ohgaki.net@209.85.220.173)
  by 0 with ESMTPA; 13 Apr 2017 21:23:13 -0000
Received: by mail-qk0-f173.google.com with SMTP id p68so58054305qke.1;
        Thu, 13 Apr 2017 14:23:13 -0700 (PDT)
X-Gm-Message-State: AN3rC/4S3OzPGWQt8DvAuenNe6gS9l+He+zWxby/dbcMz6sEz83Jw+3a
	qsY1h5tcjNMdIQ3majsdHkxibwWCxw==
X-Received: by 10.55.147.131 with SMTP id v125mr4143592qkd.39.1492118586866;
 Thu, 13 Apr 2017 14:23:06 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.140.27.179 with HTTP; Thu, 13 Apr 2017 14:22:26 -0700 (PDT)
In-Reply-To: <1924612862.1298112.1492071094545.JavaMail.zimbra@pieterhordijk.com>
References: <CAGa2bXbUYDgJxmmZfuS5ZbWCLjq0QPpDioM-zkU9j7EHA-D_ag@mail.gmail.com>
 <CAGa2bXZ9_DtktnGpX38DHUvEzU4=9wMc_23fKxudzZWZ49A+Hw@mail.gmail.com>
 <0285A0ED-A39F-46C9-A927-3C786F2B256D@koalephant.com> <CAGa2bXYFw6Uz9cLFM1QT9ULak9uJcM4mr0R59TEa0eYf-tAm+Q@mail.gmail.com>
 <CAGa2bXYnDgvsWi4kCdajnnQ-psCPThpLu3_EK_DprLWsX+UZ2A@mail.gmail.com>
 <CAL=_i_n4KSfx=TGMjTnjjszaNzVqT=V=GPZFyiLYFuzb8RxCgQ@mail.gmail.com>
 <CAGa2bXZ6JMKWsY=Cea-=V=g09jdTQGDOg7TtJrf6_higU0KW3Q@mail.gmail.com> <1924612862.1298112.1492071094545.JavaMail.zimbra@pieterhordijk.com>
Date: Fri, 14 Apr 2017 06:22:26 +0900
X-Gmail-Original-Message-ID: <CAGa2bXYR5ssff9YXUYGcsriTWJfYEf-2OkTXAxnb536HPhBjpA@mail.gmail.com>
Message-ID: <CAGa2bXYR5ssff9YXUYGcsriTWJfYEf-2OkTXAxnb536HPhBjpA@mail.gmail.com>
To: Pieter Hordijk <info@pieterhordijk.com>
Cc: Joe Watkins <pthreads@pthreads.org>, Andrey Andreev <narf@devilix.net>, 
	"internals@lists.php.net" <internals@lists.php.net>, PHP Documentation ML <phpdoc@lists.php.net>
Content-Type: multipart/alternative; boundary=94eb2c08bb92557b77054d12ee36
Subject: Re: [PHP-DEV] [RFC][VOTE] Improve hash_hkdf() parameter
From: yohgaki@ohgaki.net (Yasuo Ohgaki)

--94eb2c08bb92557b77054d12ee36
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hi Pieter and all,

On Thu, Apr 13, 2017 at 5:11 PM, Pieter Hordijk <info@pieterhordijk.com>
wrote:

> Is this really something we need in our official docs instead of for
> example
> on a personal blog?
>

I wrote draft doc patch.
Please verify.

Index: en/reference/hash/functions/hash-hkdf.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- en/reference/hash/functions/hash-hkdf.xml    (=E3=83=AA=E3=83=93=E3=82=
=B8=E3=83=A7=E3=83=B3 342317)
+++ en/reference/hash/functions/hash-hkdf.xml    (=E4=BD=9C=E6=A5=AD=E3=82=
=B3=E3=83=94=E3=83=BC)
@@ -3,7 +3,7 @@
 <refentry xml:id=3D"function.hash-hkdf" xmlns=3D"http://docbook.org/ns/doc=
book"
xmlns:xlink=3D"http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>hash_hkdf</refname>
-  <refpurpose>Generate a HKDF key derivation of a supplied key
input</refpurpose>
+  <refpurpose>Derive secure new key from existing key by using
HKDF</refpurpose>
  </refnamediv>
  <refsect1 role=3D"description">
   &reftitle.description;
@@ -16,6 +16,20 @@
    <methodparam
choice=3D"opt"><type>string</type><parameter>salt</parameter><initializer>'=
'</initializer></methodparam>
   </methodsynopsis>

+  <para>
+   RFC 5869 defines HKDF (HMAC based Key Derivation Function) which
+   is general purpose KDF. HKDF could be useful for many PHP
+   applications that require temporary keys, such CSRF token,
+   pre-signed key for URI, password for password protected
+   URI, and so on.
+  </para>
+  <note>
+    <para>
+      When info and length
+      is not required for your program, more efficient
+      <function>hash_hmac</function> could be used instead.
+    </para>
+  </note>
  </refsect1>
  <refsect1 role=3D"parameters">
   &reftitle.parameters;
@@ -25,7 +39,7 @@
      <term><parameter>algo</parameter></term>
      <listitem>
       <para>
-       Name of selected hashing algorithm (i.e. "sha256", "sha512",
"haval160,4", etc..)
+       Name of selected hashing algorithm (i.e. "sha3-256", "sha3-512",
"sha256", "sha512", "haval160,4", etc..)
        See <function>hash_algos</function> for a list of supported
algorithms.
        <note>
         <para>
@@ -39,7 +53,7 @@
      <term><parameter>ikm</parameter></term>
      <listitem>
       <para>
-       Input keying material (raw binary). Cannot be empty.
+       Input keying material. Cannot be empty.
       </para>
      </listitem>
     </varlistentry>
@@ -60,7 +74,8 @@
      <term><parameter>info</parameter></term>
      <listitem>
       <para>
-       Application/context-specific info string.
+       Application/context-specific info string. Info is intended for
+       public information such as user ID, protocol version, etc.
       </para>
      </listitem>
     </varlistentry>
@@ -71,8 +86,32 @@
        Salt to use during derivation.
       </para>
       <para>
-       While optional, adding random salt significantly improves the
strength of HKDF.
+        While optional, adding random salt significantly improves the
+        strength of HKDF. Salt could be either secret or
+        non-secret. It is used as "Pre Shared Key" in many use cases.
+        Strong value is preferred. e.g. Use
<function>random_bytes</function>.
+        Optimal salt size is size of used hash algorithm.
       </para>
+      <warning>
+        <para>
+         Although salt is the last optional parameter, salt is the
+         most important parameter for key security. Omitted salt is
+         indication of inappropriate design in most cases. Users must
+         set appropriate salt value whenever it is possible. Omit salt
+         only when it cannot be used.
+        </para>
+        <para>
+         Strong salt is mandatory and must be kept secret when input
+         key is weak, otherwise input key security will not be kept.
+         Even when input key is strong, providing strong salt is the
+         best practice for the best possible key security.
+        </para>
+        <para>
+         Salt must not be able to be controlled by users. i.e. User
+         must not be able to set salt value and get derived key. User
+         controlled salt allows input key analysis to attackers.
+        </para>
+      </warning>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -101,6 +140,99 @@
   &reftitle.examples;
   <para>
    <example>
+    <title>URI specific CSRF token that supports expiration by
<function>hash_hkdf</function></title>
+    <programlisting role=3D"php">
+<![CDATA[
+<?php
+define('CSRF_TOKEN_EXPIRE', 180); // CSRF token expiration
+define('CSRF_TOKENS', 5); // Last 5 CSRF tokens are valid
+
+/**************************************
+ * Implementation note
+ *
+ * It uses "counter" for CSRF expiration management.
+ * "counter" is very low entropy, but input key is strong and
+ * CSRF_TOKEN_SEED is short term key. It should be OK.
+ *
+ * This CSRF token implementation has pros and cons
+ *
+ * Pros
+ *  - A CSRF token is valid only for specific URI.
+ *  - No database is required for URI specific CSRF tokens.
+ *  - Only CSRF token is required. i.e. No timestamp parameter.
+ *  - When user is active, a CSRF token is valid upto CSRF_TOKEN_EXPIRE *
CSRF_TOKENS sec.
+ *  - Even when user had long idle time, CSRF token is valid.
+ *  - CSRF token will expire eventually.
+ *  - Invalidating all active CSRF tokens could be done by
unset($_SESSION['CSRF_TOKEN_SEED']).
+ *    It is recommended to reset CSRF tokens by login/logout event at
least.
+ *    It may be good idea to invalidate all of older CSRF tokens when idle
time is long.
+ *
+ * Cons
+ *  - There could be no CSRF expiration time.
+ *
+ * Precise CSRF token expiration is easy. Just add timestamp parameter
+ * as "info" and check it.
+ **************************************/
+
+session_start();
+if (empty($_SESSION['CSRF_TOKEN_SEED'])) {
+    $_SESSION['CSRF_TOKEN_SEED'] =3D random_bytes(32);
+    $_SESSION['CSRF_TOKEN_COUNT'] =3D 1;
+    $_SESSION['CSRF_TOKEN_EXPIRE'] =3D time();
+}
+
+
+function csrf_get_token($uri) {
+    // Check expiration
+    if ($_SESSION['CSRF_TOKEN_EXPIRE'] + CSRF_TOKEN_EXPIRE < time()) {
+        $_SESSION['CSRF_TOKEN_COUNT']++;
+        $_SESSION['CSRF_TOKEN_EXPIRE'] =3D time();
+    }
+    // Equivalent(NOT exactly the same) value by using hash_hmac()
+    // return hash_hmac('sha3-256', hash_hmac('sha3-256',
$_SESSION['CSRF_TOKEN_SEED'], $_SESSION['CSRF_TOKEN_COUNT']), $uri);
+    return hash_hkdf('sha3-256', $_SESSION['CSRF_TOKEN_SEED'], 0, $uri,
$_SESSION['CSRF_TOKEN_COUNT']);
+}
+
+function csrf_validate_token($csrf_token, $uri) {
+    for($i =3D 0; $i < CSRF_TOKENS; $i++) {
+        // Equivalent(NOT exactly the same) value by using hash_hmac()
+        // $token =3D hash_hmac('sha3-256', hash_hmac('sha3-256',
$_SESSION['CSRF_TOKEN_SEED'], $_SESSION['CSRF_TOKEN_COUNT'] - $i), $uri);
+        $token =3D hash_hkdf('sha3-256', $_SESSION['CSRF_TOKEN_SEED'], 0,
$uri, $_SESSION['CSRF_TOKEN_COUNT'] - $i);
+        if (hash_equals($csrf_token, $token)) {
+            return TRUE;
+        }
+    }
+    return FALSE;
+}
+
+
+//// Generating CSRF token ////
+// $uri is target URI that browser POSTs form data
+$uri =3D 'https://example.com/some_form/';
+$csrf_token =3D csrf_get_token($uri);
+// embed $csrf_token to your form
+
+//// Validating CSRF token ////
+$csrf_token =3D $_POST['csrf_token'] ?? '';
+if (!csrf_validate_token($csrf_token, $_SERVER['REQUEST_URI'])) {
+    // Invalid CSRF token
+    throw new Exception('CSRF token validation error');
+}
+// valid request
+?>
+]]>
+    </programlisting>
+    <para>
+     Common CSRF token uses the same token value for a session and all
+     URI. This example CSRF token expires and is specific to a
+     URI. i.e. CSRF token http://example.com/form_A/ is not valid for
+     http://example.com/form_B/ Since token value is computed, no
+     database is required.
+    </para>
+   </example>
+  </para>
+  <para>
+   <example>
     <title><function>hash_hkdf</function> example</title>
     <programlisting role=3D"php">
 <![CDATA[
@@ -124,6 +256,30 @@
     </para>
    </example>
   </para>
+  <para>
+   <example>
+    <title><function>hash_hkdf</function> bad example</title>
+    <para>
+     Users must not simply extend input key material length. HKDF does
+     not add additional entropy automatically.  Therefore, weak key
+     remains weak unless strong salt is supplied. Following is bad
+     example.
+    </para>
+    <programlisting role=3D"php">
+<![CDATA[
+<?php
+$inputKey =3D get_my_aes128_key(); // AES 128 bit key
+
+// Derive AES 256 key from AES 128 key
+$encryptionKey =3D hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption'=
);
+// Users should not do this. $encryptionKey only has 128 bit
+// entropy while it should have 256 bit entropy.
+// To derive strong AES 256 key, strong enough salt is required.
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
  </refsect1>

  <refsect1 role=3D"seealso">
@@ -130,6 +286,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>hash_hmac</function></member>
     <member><function>hash_pbkdf2</function></member>
     <member><link xlink:href=3D"&url.rfc;5869">RFC 5869</link></member>
     <member><link
xlink:href=3D"&url.git.hub;narfbg/hash_hkdf_compat">userland
implementation</link></member>

--
Yasuo Ohgaki
yohgaki@ohgaki.net

--94eb2c08bb92557b77054d12ee36--