includes/utils/MWCryptHKDF.php

   1 <?php
   2 /**
   3  * Extract-and-Expand Key Derivation Function (HKDF). A cryptographicly
   4  * secure key expansion function based on RFC 5869.
   5  *
   6  * This relies on the secrecy of $wgSecretKey (by default), or $wgHKDFSecret.
   7  * By default, sha256 is used as the underlying hashing algorithm, but any other
   8  * algorithm can be used. Finding the secret key from the output would require
   9  * an attacker to discover the input key (the PRK) to the hmac that generated
  10  * the output, and discover the particular data, hmac'ed with an evolving key
  11  * (salt), to produce the PRK. Even with md5, no publicly known attacks make
  12  * this currently feasible.
  13  *
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * This program is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License along
  25  * with this program; if not, write to the Free Software Foundation, Inc.,
  26  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  27  * http://www.gnu.org/copyleft/gpl.html
  28  *
  29  * @author Chris Steipp
  30  * @file
  31  */
  32
  33 use MediaWiki\MediaWikiServices;
  34
  35 class MWCryptHKDF {
  36
  37         /**
  38          * Return a singleton instance, based on the global configs.
  39          * @return CryptHKDF
  40          */
  41         protected static function singleton() {
  42                 return MediaWikiServices::getInstance()->getCryptHKDF();
  43         }
  44
  45         /**
  46          * RFC5869 defines HKDF in 2 steps, extraction and expansion.
  47          * From http://eprint.iacr.org/2010/264.pdf:
  48          *
  49          * The scheme HKDF is specifed as:
  50          *      HKDF(XTS, SKM, CTXinfo, L) = K(1) || K(2) || ... || K(t)
  51          * where the values K(i) are defined as follows:
  52          *      PRK = HMAC(XTS, SKM)
  53          *      K(1) = HMAC(PRK, CTXinfo || 0);
  54          *      K(i+1) = HMAC(PRK, K(i) || CTXinfo || i), 1 <= i < t;
  55          * where t = [L/k] and the value K(t) is truncated to its first d = L mod k bits;
  56          * the counter i is non-wrapping and of a given fixed size, e.g., a single byte.
  57          * Note that the length of the HMAC output is the same as its key length and therefore
  58          * the scheme is well defined.
  59          *
  60          * XTS is the "extractor salt"
  61          * SKM is the "secret keying material"
  62          *
  63          * N.B. http://eprint.iacr.org/2010/264.pdf seems to differ from RFC 5869 in that the test
  64          * vectors from RFC 5869 only work if K(0) = '' and K(1) = HMAC(PRK, K(0) || CTXinfo || 1)
  65          *
  66          * @param string $hash The hashing function to use (e.g., sha256)
  67          * @param string $ikm The input keying material
  68          * @param string $salt The salt to add to the ikm, to get the prk
  69          * @param string $info Optional context (change the output without affecting
  70          *      the randomness properties of the output)
  71          * @param int $L Number of bytes to return
  72          * @return string Cryptographically secure pseudorandom binary string
  73          */
  74         public static function HKDF( $hash, $ikm, $salt, $info, $L ) {
  75                 return CryptHKDF::HKDF( $hash, $ikm, $salt, $info, $L );
  76         }
  77
  78         /**
  79          * Generate cryptographically random data and return it in raw binary form.
  80          *
  81          * @param int $bytes The number of bytes of random data to generate
  82          * @param string $context String to mix into HMAC context
  83          * @return string Binary string of length $bytes
  84          */
  85         public static function generate( $bytes, $context ) {
  86                 return self::singleton()->generate( $bytes, $context );
  87         }
  88
  89         /**
  90          * Generate cryptographically random data and return it in hexadecimal string format.
  91          * See MWCryptRand::realGenerateHex for details of the char-to-byte conversion logic.
  92          *
  93          * @param int $chars The number of hex chars of random data to generate
  94          * @param string $context String to mix into HMAC context
  95          * @return string Random hex characters, $chars long
  96          */
  97         public static function generateHex( $chars, $context = '' ) {
  98                 $bytes = ceil( $chars / 2 );
  99                 $hex = bin2hex( self::singleton()->generate( $bytes, $context ) );
 100                 return substr( $hex, 0, $chars );
 101         }
 102
 103 }