CSRFProtector.php

<?php

namespace Ling\CSRFTools;


use Ling\ArrayToString\ArrayToStringTool;

/**
 * The CSRFProtector class.
 *
 * This class can be used as a singleton, or as a regular class (it's an hybrid).
 *
 *
 * How this class works
 * ================
 * Before using this class, you should have a basic understanding of how it works.
 *
 * In this class, a token is composed of two things:
 *
 * - a name
 * - a value
 *
 * The value of the token is always generated by this class, it's a random value, like 98f0z0fzegijzgozhu for instance.
 * The name of the token is chosen by you.
 *
 * With this class, you can generate tokens, using the createToken method.
 * This method will not only return the value of the token, but also store it in the php session.
 *
 * You can then check whether a given token has the value you think it has (using the isValid method): this is the
 * heart of the CSRF validation; if you can predict the value of a token, then you must be the one who created it (at least
 * that's the logic behind it).
 *
 * Now what's peculiar to this class is that the tokens are stored in slots.
 * More precisely, there are two possible slots:
 * - new
 * - old
 *
 * By default, the createToken method stores a token in the new slot.
 * But then if you call the createToken method again with the same token name, the "new" slot will be replaced by
 * a new token value (random string generated by this class), but the old token value is transferred to the
 * "old" slot rather than being completely replaced.
 *
 * Why is that so you might ask?
 *
 * This has to do with how forms are implemented in php applications.
 * A form is first displayed, then the user posts the form.
 * In terms of page invocation, this means that the form page is usually invoked at least twice:
 * - the first time to display the form to the user
 * - the second time to test the posted data against some validation mechanism
 *
 *
 * And so the first time we create the token and it goes to the new slot.
 * And the second time, we want to validate the token, but a new token has been regenerated (since we posted the form
 * and the page has been refreshed), and so we want to validate the token against the old slot.
 *
 *
 * Now  which slot you want to validate against really depends on your application and your concrete case.
 *
 * For instance for csrf protected backend services accessed via ajax, we generally want to use the new slot all the time.
 * When the user calls the page, we generate the token, but when he calls the service via ajax, the page generating the token
 * has not been recalled, and so the token is still in the "new slot".
 *
 * That's why the isValid method let you choose which slot you want to validate against.
 *
 *
 *
 *
 * The delete method
 * -------------
 *
 * I would recommend using it wherever you can, because it completely prevents an attacker from guessing the token.
 * However in some cases, the token cannot be deleted otherwise your own users cannot use them.
 * So, you have to assess the situation for yourself, and decide whether you should use the delete method.
 *
 *
 *
 *
 *
 *
 */
class CSRFProtector
{

    /**
     * This property holds its own instance.
     * @var CSRFProtector
     */
    private static $inst = null;


    /**
     * This property holds the sessionName for this instance.
     *
     * It's like a namespace containing all tokens generated by this class.
     *
     * You shouldn't change this, as it's unlikely that you would have a session variable named csrf_tools_token.
     * But if you were, you could extend this class and change that sessionName.
     *
     *
     *
     * @var string
     */
    protected $sessionName;

    /**
     * This property holds the usePage for this instance.
     * See the @page(page security conception notes) for more details.
     * @var bool=true
     */
    protected $usePage;


    /**
     * Gets the singleton instance for this class.
     *
     *
     * @return CSRFProtector
     */
    public static function inst()
    {
        if (null === self::$inst) {
            self::$inst = new static();
        }
        return self::$inst;
    }


    /**
     * Builds the CSRFProtector instance.
     */
    public function __construct()
    {

        $this->sessionName = "csrf_tools_token";
        $this->usePage = true;
        $this->startSession();
    }

    /**
     * Sets the usePage.
     *
     * @param bool $usePage
     */
    public function setUsePage(bool $usePage)
    {
        $this->usePage = $usePage;
    }


    /**
     * Creates the token named $tokenName, stores its value in the "new" slot, and returns the token value.
     * If the token named $tokenName already exists, there is a rotation: the newly created token is stored in the "new" slot,
     * while the old "new" value (found in the "new" slot before it was replaced) is moved to the "old" slot.
     *
     * For more details, please refer to this class description.
     *
     * The following token names are reserved for internal use and must not be used:
     *
     * - __pages__
     *
     *
     * @param string $tokenName
     * @return string
     */
    public function createToken(string $tokenName): string
    {
        if (array_key_exists($tokenName, $_SESSION[$this->sessionName])) {
            $_SESSION[$this->sessionName][$tokenName]['old'] = $_SESSION[$this->sessionName][$tokenName]['new'];
        }

        $token = md5(uniqid());
        $_SESSION[$this->sessionName][$tokenName]['new'] = $token;
        if (true === $this->usePage) {
            $this->addTokenForPage($tokenName);
        }
        return $token;
    }


    /**
     * Returns whether the token identified by the given tokenName is already stored in the session.
     *
     *
     * @param string $tokenName
     * @return bool
     */
    public function hasToken(string $tokenName): bool
    {
        $this->startSession();
        if (array_key_exists($tokenName, $_SESSION[$this->sessionName])) {
            return array_key_exists($tokenName, $_SESSION[$this->sessionName]);
        }
        return false;
    }


    /**
     * Returns whether the given $tokenName exists and has the given $tokenValue.
     *
     *
     * @param string $tokenName
     * @param string $tokenValue
     * @param bool=false $useNewSlot
     * @return bool
     */
    public function isValid(string $tokenName, string $tokenValue, bool $useNewSlot = false): bool
    {
        $this->startSession();
        if (array_key_exists($tokenName, $_SESSION[$this->sessionName])) {
            $tokenValue = trim($tokenValue);
            if (false === $useNewSlot) {
                if (array_key_exists("old", $_SESSION[$this->sessionName][$tokenName])) {
                    $res = ($tokenValue === $_SESSION[$this->sessionName][$tokenName]["old"]);
                } else {
                    $res = false;
                }
            } else {
                $res = ($tokenValue === $_SESSION[$this->sessionName][$tokenName]["new"]);
            }
            return $res;

        }
        return false;
    }


    /**
     * Deletes the given $tokenName.
     *
     * @param string $tokenName
     */
    public function deleteToken(string $tokenName)
    {
        $this->startSession();
        unset($_SESSION[$this->sessionName][$tokenName]);
    }


    /**
     * Deletes the tokens that are not associated with the current page.
     *
     */
    public function deletePageUnusedTokens()
    {
        $this->startSession();
        $pageId = $this->getPageId();
        $pages = $_SESSION[$this->sessionName]['__pages__'];


        /**
         * I had this issue where the system thought it was another page, and so deleted tokens that were on the
         * actual page.
         *
         * To reproduce:
         *
         * - browse /reset.php to clean all session variables
         * - browse /user/profile?d   (create a fake get variable to make the old system think it's another page)
         * - log in, and now browse /user/profile. As you browse /user/profile, the old system was removing the current
         *          tokens, because /user/profile?d is different than /user/profile, but it shouldn't because we
         *          actually use the tokens on the page. Anyway, this is fixed simply by protecting the tokens
         *          on the current page (variable currentTokens below).
         *
         *
         *
         */
        $currentTokens = $pages[$pageId] ?? [];
        unset($pages[$pageId]);
        array_walk_recursive($pages, function ($tokenName) use ($currentTokens) {
            if (false === in_array($tokenName, $currentTokens, true)) {
                unset($_SESSION[$this->sessionName][$tokenName]);
            }
        });
    }


    /**
     * Returns a debug string of the php session content.
     *
     * @return string
     */
    public function dump(): string
    {
        $this->startSession();
        return ArrayToStringTool::toPhpArray($_SESSION[$this->sessionName]);
    }


    /**
     * Cleans the session.
     */
    public function cleanSession()
    {
        $this->startSession();
        unset($_SESSION[$this->sessionName]);
    }


    //--------------------------------------------
    //
    //--------------------------------------------
    /**
     * Ensures that the php session has started.
     */
    protected function startSession()
    {
        if (session_status() == PHP_SESSION_NONE) {
            session_start();
        }
        if (false === array_key_exists($this->sessionName, $_SESSION)) {
            $_SESSION[$this->sessionName] = [
                '__pages__' => [],
            ];
        }
    }


    /**
     * Adds a token to the pages array.
     *
     * @param string $tokenName
     */
    protected function addTokenForPage(string $tokenName)
    {
        $pages = $_SESSION[$this->sessionName]['__pages__'] ?? [];
        $pageId = $this->getPageId();
        if (false === array_key_exists($pageId, $pages)) {
            $pages[$pageId] = [];
        }

        if (false === in_array($tokenName, $pages[$pageId])) {
            $pages[$pageId][] = $tokenName;
            $_SESSION[$this->sessionName]['__pages__'] = $pages;
        }
    }


    /**
     * Returns the current page id.
     * @return string
     */
    protected function getPageId(): string
    {
        return $_SERVER['REQUEST_URI'];
    }
}