MWCryptHKDF.php

Go to the documentation of this file.

<?php
class MWCryptHKDF {

    protected static $singleton = null;

    protected $cache = null;

    protected $cacheKey = null;

    protected $algorithm = null;

    protected $salt;

    private $prk;

    private $skm;

    protected $lastK;

    protected $context = [];

    public static $hashLength = [
        'md5' => 16,
        'sha1' => 20,
        'sha224' => 28,
        'sha256' => 32,
        'sha384' => 48,
        'sha512' => 64,
        'ripemd128' => 16,
        'ripemd160' => 20,
        'ripemd256' => 32,
        'ripemd320' => 40,
        'whirlpool' => 64,
    ];

    public function __construct( $secretKeyMaterial, $algorithm, $cache, $context ) {
        if ( strlen( $secretKeyMaterial ) < 16 ) {
            throw new MWException( "MWCryptHKDF secret was too short." );
        }
        $this->skm = $secretKeyMaterial;
        $this->algorithm = $algorithm;
        $this->cache = $cache;
        $this->salt = ''; // Initialize a blank salt, see getSaltUsingCache()
        $this->prk = '';
        $this->context = is_array( $context ) ? $context : [ $context ];

        // To prevent every call from hitting the same memcache server, pick
        // from a set of keys to use. mt_rand is only use to pick a random
        // server, and does not affect the security of the process.
        $this->cacheKey = wfMemcKey( 'HKDF', mt_rand( 0, 16 ) );
    }

    function __destruct() {
        if ( $this->lastK ) {
            $this->cache->set( $this->cacheKey, $this->lastK );
        }
    }

    protected function getSaltUsingCache() {
        if ( $this->salt == '' ) {
            $lastSalt = $this->cache->get( $this->cacheKey );
            if ( $lastSalt === false ) {
                // If we don't have a previous value to use as our salt, we use
                // 16 bytes from MWCryptRand, which will use a small amount of
                // entropy from our pool. Note, "XTR may be deterministic or keyed
                // via an optional “salt value”  (i.e., a non-secret random
                // value)..." - http://eprint.iacr.org/2010/264.pdf. However, we
                // use a strongly random value since we can.
                $lastSalt = MWCryptRand::generate( 16 );
            }
            // Get a binary string that is hashLen long
            $this->salt = hash( $this->algorithm, $lastSalt, true );
        }
        return $this->salt;
    }

    protected static function singleton() {
        global $wgHKDFAlgorithm, $wgHKDFSecret, $wgSecretKey, $wgMainCacheType;

        $secret = $wgHKDFSecret ?: $wgSecretKey;
        if ( !$secret ) {
            throw new MWException( "Cannot use MWCryptHKDF without a secret." );
        }

        // In HKDF, the context can be known to the attacker, but this will
        // keep simultaneous runs from producing the same output.
        $context = [];
        $context[] = microtime();
        $context[] = getmypid();
        $context[] = gethostname();

        // Setup salt cache. Use APC, or fallback to the main cache if it isn't setup
        $cache = ObjectCache::getLocalServerInstance( $wgMainCacheType );

        if ( is_null( self::$singleton ) ) {
            self::$singleton = new self( $secret, $wgHKDFAlgorithm, $cache, $context );
        }

        return self::$singleton;
    }

    protected function realGenerate( $bytes, $context = '' ) {

        if ( $this->prk === '' ) {
            $salt = $this->getSaltUsingCache();
            $this->prk = self::HKDFExtract(
                $this->algorithm,
                $salt,
                $this->skm
            );
        }

        $CTXinfo = implode( ':', array_merge( $this->context, [ $context ] ) );

        return self::HKDFExpand(
            $this->algorithm,
            $this->prk,
            $CTXinfo,
            $bytes,
            $this->lastK
        );
    }

    public static function HKDF( $hash, $ikm, $salt, $info, $L ) {
        $prk = self::HKDFExtract( $hash, $salt, $ikm );
        $okm = self::HKDFExpand( $hash, $prk, $info, $L );
        return $okm;
    }

    private static function HKDFExtract( $hash, $salt, $ikm ) {
        return hash_hmac( $hash, $ikm, $salt, true );
    }

    private static function HKDFExpand( $hash, $prk, $info, $bytes, &$lastK = '' ) {
        $hashLen = MWCryptHKDF::$hashLength[$hash];
        $rounds = ceil( $bytes / $hashLen );
        $output = '';

        if ( $bytes > 255 * $hashLen ) {
            throw new MWException( "Too many bytes requested from HDKFExpand" );
        }

        // K(1) = HMAC(PRK, CTXinfo || 1);
        // K(i) = HMAC(PRK, K(i-1) || CTXinfo || i); 1 < i <= t;
        for ( $counter = 1; $counter <= $rounds; ++$counter ) {
            $lastK = hash_hmac(
                $hash,
                $lastK . $info . chr( $counter ),
                $prk,
                true
            );
            $output .= $lastK;
        }

        return substr( $output, 0, $bytes );
    }

    public static function generate( $bytes, $context ) {
        return self::singleton()->realGenerate( $bytes, $context );
    }

    public static function generateHex( $chars, $context = '' ) {
        $bytes = ceil( $chars / 2 );
        $hex = bin2hex( self::singleton()->realGenerate( $bytes, $context ) );
        return substr( $hex, 0, $chars );
    }

}