configuration.md

Configuring PSR7Session

In most HTTPS-based setups, PSR7Session can be initialized with some sane defaults.

Symmetric key

You can set up symmetric key based signatures via the PSR7Sessions::fromSymmetricKeyDefaults named constructor:

use PSR7Sessions\Storageless\Http\SessionMiddleware;

$sessionMiddleware = SessionMiddleware::fromSymmetricKeyDefaults(
    'OpcMuKmoxkhzW0Y1iESpjWwL/D3UBdDauJOe742BJ5Q=', // replace this with a key of your own (see below)
    1200                                            // session lifetime, in seconds
);

Please use a fairly long symmetric key: it is suggested to use a cryptographically secure pseudo-random number generator (CSPRNG), such as the CryptoKey tool, for this purpose.

Asymmetric key

You can set up symmetric key based signatures via the PSR7Sessions::fromAsymmetricKeyDefaults named constructor:

use PSR7Sessions\Storageless\Http\SessionMiddleware;

$sessionMiddleware = SessionMiddleware::fromAsymmetricKeyDefaults(
    file_get_contents('/path/to/private_key.pem'),
    file_get_contents('/path/to/public_key.pem'),
    1200 // session lifetime, in seconds
);

You can generate a private and a public key with GPG, via:

gpg --gen-key

Beware that asymmetric key signatures are more resource-greedy, and therefore you may have higher CPU usage.

PSR7Session will only parse and regenerate the sessions lazily, when strictly needed, therefore performance shouldn't be a problem for most setups.

Fine-tuning

Since PSR7Session depends on lcobucci/jwt, lcobucci/clock, and dflydev/fig-cookies, you need to require them as well, since with this sort of setup you are explicitly using those components:

composer require "lcobucci/jwt:~3.1"
composer require "lcobucci/clock:^1.1.0"
composer require "dflydev/fig-cookies:^1.0.1"

If you want to fine-tune more settings of PSR7Session, then simply use the PSR7Sessions\Storageless\Http\SessionMiddleware constructor.

use PSR7Sessions\Storageless\Http\SessionMiddleware;

// a blueprint of the cookie that `PSR7Session` should use to generate
// and read cookies, be careful to secure it, see defaults below:
$cookieBlueprint   = \Dflydev\FigCookies\SetCookie::create('cookie-name');
$sessionMiddleware = new SessionMiddleware(
    $signer, // an \Lcobucci\JWT\Signer
    'signature key contents',
    'verification key contents',
    $cookieBlueprint,
    new \Lcobucci\JWT\Parser(),
    1200, // session lifetime, in seconds
    new \Lcobucci\Clock\SystemClock(new DateTimeZone(date_default_timezone_get()),
    60    // session automatic refresh time, in seconds
);

It is recommended not to use this setup.

Defaults

By default, sessions generated via the SessionMiddleware factory methods use following parameters:

• "__Secure-slsession" is the name of the cookie where the session is stored, __Secure- prefix is intentional
• "__Secure-slsession" cookie is configured as Secure
• "__Secure-slsession" cookie is configured as HttpOnly
• "__Secure-slsession" cookie is configured as SameSite=Lax
• "__Secure-slsession" cookie is configured as path=/
• The "__Secure-slsession" cookie will contain a JWT token
• The JWT token in the "__Secure-slsession" is signed, but unencrypted
• The JWT token in the "__Secure-slsession" has an iat claim
• The session is re-generated only after 60 seconds, and not at every user-agent interaction

Local development

When running applications locally on http://localhost, some settings must be changed to work without HTTPS support.

The example below is completely insecure. It should only be used for local development.

$key = '<random key>';
return new SessionMiddleware(
    new Sha256,
    $key,
    $key,
    // Override the default `__Secure-slsession` which only works on HTTPS
    SetCookie::create('slsession')
        // Disable mandatory HTTPS
        ->withSecure(false)
        ->withHttpOnly(true)
        ->withPath('/'),
    new Parser,
    1200, // session lifetime, in seconds
    SystemClock::fromUTC(),
);