Fabiang\SASL\Authentication\SCRAM

Complexity

Total Complexity

29

Size/Duplication

Total Lines	236
Duplicated Lines	0 %

Importance

Changes

0

12 Methods

Rating	Name	Duplication	Size	Complexity
A	getHashAlgo()	0	3	1
A	getAuthMessage()	0	3	1
A	verify()	0	18	4
A	getSaltedPassword()	0	3	1
A	createResponse()	0	16	4
A	formatName()	0	3	1
A	downgradeProtection()	0	8	2
A	getCnonce()	0	3	1
B	generateResponse()	0	49	8
A	generateInitialResponse()	0	10	2
A	__construct()	0	22	2
A	hi()	0	10	2

<?php

declare(strict_types=1);

/**
 * Sasl library.
 *
 * Copyright (c) 2002-2003 Richard Heyes,
 *               2014-2025 Fabian Grutschus
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * o Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * o Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.|
 * o The names of the authors may not be used to endorse or promote
 *   products derived from this software without specific prior written
 *   permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * @author Jehan <jehan.marmottard@gmail.com>
 */

namespace Fabiang\SASL\Authentication;

use Closure;
use Fabiang\SASL\Authentication\AbstractAuthentication;
use Fabiang\SASL\Options;
use Fabiang\SASL\Exception\InvalidArgumentException;

/**
 * Implementation of SCRAM-* SASL mechanisms.
 * SCRAM mechanisms have 3 main steps (initial response, response to the server challenge, then server signature
 * verification) which keep state-awareness. Therefore a single class instanciation must be done
 * and reused for the whole authentication process.
 *
 * @author Jehan <jehan.marmottard@gmail.com>
 */
class SCRAM extends AbstractAuthentication implements ChallengeAuthenticationInterface, VerificationInterface
{
    private string $hashAlgo;
    private Closure $hash;
    private Closure $hmac;
    private ?string $gs2Header = null;
    private ?string $cnonce = null;
    private string $firstMessageBare;
    private string $saltedPassword;
    private string $authMessage;

    /**
     * Construct a SCRAM-H client where 'H' is a cryptographic hash function.
     *
     * @link http://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xml "Hash Function
     * Textual Names" format of core PHP hash function.
     * @param Options $options
     * @param string  $hash The name cryptographic hash function 'H' as registered by IANA in the "Hash Function Textual
     * Names" registry.
     * @throws InvalidArgumentException
     */
    public function __construct(Options $options, string $hash)
    {
        parent::__construct($options);

        // Though I could be strict, I will actually also accept the naming used in the PHP core hash framework.
        // For instance "sha1" is accepted, while the registered hash name should be "SHA-1".
        $normalizedHash = strtolower(preg_replace('#^sha-(\d+)#i', 'sha\1', $hash));

        $hashAlgos = hash_algos();
        if (!in_array($normalizedHash, $hashAlgos)) {
            throw new InvalidArgumentException("Invalid SASL mechanism type '$hash'");
        }

        $this->hash = function ($data) use ($normalizedHash) {
            return hash($normalizedHash, $data, true);
        };

        $this->hmac = function ($key, $str, $raw) use ($normalizedHash) {
            return hash_hmac($normalizedHash, $str, $key, $raw);
        };

        $this->hashAlgo = $normalizedHash;
    }

    /**
     * Provides the (main) client response for SCRAM-H.
     *
     * @param  string $challenge The challenge sent by the server.
     * If the challenge is null or an empty string, the result will be the "initial response".
     * @return string|false      The response (binary, NOT base64 encoded)
     */
    public function createResponse(?string $challenge = null): string|false
    {
        $authcid = $this->formatName($this->options->getAuthcid());

It seems like $this->options->getAuthcid() can also be of type null; however, parameter $username of Fabiang\SASL\Authentication\SCRAM::formatName() does only seem to accept string, maybe add an additional type check?

        if (empty($authcid)) {
            return false;
        }

        $authzid = $this->options->getAuthzid();
        if (!empty($authzid)) {
            $authzid = $this->formatName($authzid);
        }

        if (empty($challenge)) {
            return $this->generateInitialResponse($authcid, $authzid);
        } else {
            return $this->generateResponse($challenge, $this->options->getSecret());

It seems like $this->options->getSecret() can also be of type null; however, parameter $password of Fabiang\SASL\Authentication\SCRAM::generateResponse() does only seem to accept false|string, maybe add an additional type check?

        }
    }

    /**
     * Prepare a name for inclusion in a SCRAM response.
     *
     * @param string $username a name to be prepared.
     * @return string the reformated name.
     */
    private function formatName(string $username): string
    {
        return str_replace(['=', ','], ['=3D', '=2C'], $username);
    }

    /**
     * Generate the initial response which can be either sent directly in the first message or as a response to an empty
     * server challenge.
     *
     * @param string $authcid Prepared authentication identity.
     * @param string $authzid Prepared authorization identity.
     * @return string The SCRAM response to send.
     */
    private function generateInitialResponse(string $authcid, ?string $authzid): string
    {
        $gs2CbindFlag   = 'n,';
        $this->gs2Header = $gs2CbindFlag . (!empty($authzid) ? 'a=' . $authzid : '') . ',';

        // I must generate a client nonce and "save" it for later comparison on second response.
        $this->cnonce = $this->generateCnonce();

        $this->firstMessageBare = 'n=' . $authcid . ',r=' . $this->cnonce;
        return $this->gs2Header . $this->firstMessageBare;
    }

    /**
     * Parses and verifies a non-empty SCRAM challenge.
     *
     * @param  string $challenge The SCRAM challenge
     * @return string|false      The response to send; false in case of wrong challenge or if an initial response has
     * not been generated first.
     */
    private function generateResponse(string $challenge, string|false $password)
    {
        $matches = [];

        $serverMessageRegexp = "#^r=(?<nonce>[\x21-\x2B\x2D-\x7E/]+)"
            . ",s=(?<salt>(?:[A-Za-z0-9/+]{4})*(?:[A-Za-z0-9/+]{3}=|[A-Za-z0-9/+]{2}==)?)"
            . ",i=(?<iteration>[0-9]*)"
            . "(?:,d=(?<downgradeProtection>(?:[A-Za-z0-9/+]{4})*(?:[A-Za-z0-9/+]{3}=|[A-Za-z0-9/+]{2}==)))?"
            . "(,[A-Za-z]=[^,])*$#";

        if (empty($this->cnonce) ||
            empty($this->gs2Header) ||
            !preg_match($serverMessageRegexp, $challenge, $matches)) {
            return false;
        }

        $nonce = $matches['nonce'];
        $salt  = base64_decode($matches['salt']);
        if (!$salt) {
            // Invalid Base64.
            return false;
        }
        $i = intval($matches['iteration']);

        $cnonce = substr($nonce, 0, strlen($this->cnonce));
        if ($cnonce !== $this->cnonce) {
            // Invalid challenge! Are we under attack?
            return false;
        }

        if (!empty($matches['downgradeProtection'])) {
            if (!$this->downgradeProtection($matches['downgradeProtection'])) {
                return false;
            }
        }

        $channelBinding       = 'c=' . base64_encode($this->gs2Header);
        $finalMessage         = $channelBinding . ',r=' . $nonce;
        $saltedPassword       = $this->hi($password, $salt, $i);

It seems like $password can also be of type false; however, parameter $str of Fabiang\SASL\Authentication\SCRAM::hi() does only seem to accept string, maybe add an additional type check?

        $this->saltedPassword = $saltedPassword;
        $clientKey            = call_user_func($this->hmac, $saltedPassword, "Client Key", true);
        $storedKey            = call_user_func($this->hash, $clientKey, true);
        $authMessage          = $this->firstMessageBare . ',' . $challenge . ',' . $finalMessage;
        $this->authMessage    = $authMessage;
        $clientSignature      = call_user_func($this->hmac, $storedKey, $authMessage, true);
        $clientProof          = $clientKey ^ $clientSignature;
        $proof                = ',p=' . base64_encode($clientProof);

        return $finalMessage . $proof;
    }

    private function downgradeProtection(string $expectedDowngradeProtectionHash): bool
    {
        if ($this->options->getDowngradeProtection() === null) {
            return true;
        }

        $actualDgPHash = base64_encode(call_user_func($this->hash, $this->generateDowngradeProtectionVerification()));
        return $expectedDowngradeProtectionHash === $actualDgPHash;
    }

    /**
     * Hi() call, which is essentially PBKDF2 (RFC-2898) with HMAC-H() as the pseudorandom function.
     *
     * @param string $str  The string to hash.
     * @param string $salt The salt value.
     * @param int $i The   iteration count.
     */
    private function hi(string $str, string $salt, int $i): string
    {
        $int1   = "\0\0\0\1";
        $ui     = call_user_func($this->hmac, $str, $salt . $int1, true);
        $result = $ui;
        for ($k = 1; $k < $i; $k++) {
            $ui     = call_user_func($this->hmac, $str, $ui, true);
            $result = $result ^ $ui;
        }
        return $result;
    }

    /**
     * SCRAM has also a server verification step. On a successful outcome, it will send additional data which must
     * absolutely be checked against this function. If this fails, the entity which we are communicating with is
     * probably not the server as it has not access to your ServerKey.
     *
     * @param string $data The additional data sent along a successful outcome.
     * @return bool Whether the server has been authenticated.
     * If false, the client must close the connection and consider to be under a MITM attack.
     */
    public function verify(string $data): bool
    {
        $verifierRegexp = '#^v=(?<verifier>(?:[A-Za-z0-9/+]{4})*(?:[A-Za-z0-9/+]{3}=|[A-Za-z0-9/+]{2}==)?)$#';

        $matches = [];
        if (empty($this->saltedPassword) ||
            empty($this->authMessage) ||
            !preg_match($verifierRegexp, $data, $matches)) {
            // This cannot be an outcome, you never sent the challenge's response.
            return false;
        }

        $verifier                = $matches['verifier'];
        $proposedServerSignature = base64_decode($verifier);
        $serverKey               = call_user_func($this->hmac, $this->saltedPassword, "Server Key", true);
        $serverSignature         = call_user_func($this->hmac, $serverKey, $this->authMessage, true);

        return $proposedServerSignature === $serverSignature;
    }

    public function getCnonce(): ?string
    {
        return $this->cnonce;
    }

    public function getSaltedPassword(): string
    {
        return $this->saltedPassword;
    }

    public function getAuthMessage(): string
    {
        return $this->authMessage;
    }

    public function getHashAlgo(): string
    {
        return $this->hashAlgo;
    }
}