The token feature is an additional security layer that helps protect your captcha and form from Cross-Site Request Forgery attacks.

CSRF is a type of security vulnerability that can lead to unauthorized actions being performed on behalf of a user without their consent. CSRF attacks typically occur when a malicious website tricks a user's browser into making a request to another website. To prevent such attacks, web applications use CSRF tokens. These tokens are unique, random values generated on the server and associated with a user's session. They must be included in every form or request submitted by the user. When the server receives a request, it checks if the included CSRF token matches the one stored in the user's session. If they match, the request is considered valid, otherwise it's rejected.

The included token class, located at \IconCaptcha\Token\IconCaptchaToken::class, uses server sessions to store CSRF tokens. While rendering a token, the class tries to start a server session on its own using session_start() in case none has been started yet.

The generated token will be rendered as a hidden HTML input element with the name _iconcaptcha-token and a random string value with the length of 32.

To include the token into your form protected by IconCaptcha, simply add the following PHP snippet within the same form where the widget is placed. It's worth noting that if you are unable to execute PHP within your HTML page, this feature will not function and should be disabled.

<?php echo \IconCaptcha\Token\IconCaptchaToken::render(); ?>

This code will generate and render the CSRF token in your form, ensuring it is included in the form data when it's submitted. Additionally, any interaction with the captcha widget that results in a server request, such as requesting a challenge or validating an input, will automatically include this token. If, however, the token is either absent despite being configured or is invalid, the server will reject these requests.

If you don't want to use the token feature, or if your application already has its own CSRF protection, you can easily turn it off. To do so, simply set the token option to null as described on the configuration wiki page.

'token' => null,

It is possible to create your own custom token class for generating and validating CSRF tokens if you wish to do so. Ensure that your custom class extends the \IconCaptcha\Token\AbstractToken class and implements the interface \IconCaptcha\Token\TokenInterface, which contains the function definitions which must be implemented.

To configure IconCaptcha to use your custom class, set the token option to the fully-qualified class name as shown below.

'token' => \Path\To\Your\CustomToken::class,

Custom class example:

use IconCaptcha\Token\AbstractToken;
use IconCaptcha\Token\TokenInterface;

class CustomToken extends AbstractToken implements TokenInterface
{
    public static function render(): string
    {
        // ...
    }

    public function get(): string
    {
        // ...
    }

    public function validate(string $payloadToken, string $headerToken = null): bool
    {
        // ...
    }
}

The following functions must be implemented in your custom token class.