Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
83.33% covered (warning)
83.33%
5 / 6
75.00% covered (warning)
75.00%
3 / 4
 CRAP
0.00% covered (danger)
0.00%
0 / 1
MWCryptHKDF
83.33% covered (warning)
83.33%
5 / 6
75.00% covered (warning)
75.00%
3 / 4
 4.07
0.00% covered (danger)
0.00%
0 / 1
 singleton
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 HKDF
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 generate
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 generateHex
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 1
1<?php
2/**
3 * Extract-and-Expand Key Derivation Function (HKDF). A cryptographically
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
33use MediaWiki\MediaWikiServices;
34
35class 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 specified 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}