Download the PHP package uma/redis-session-handler without Composer
On this page you can find all versions of the php package uma/redis-session-handler. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download uma/redis-session-handler
More information about uma/redis-session-handler
Files in uma/redis-session-handler
Package redis-session-handler
Short Description An alternative Redis session handler
License MIT
Informations about the package redis-session-handler
RedisSessionHandler
An alternative Redis session handler featuring session locking and session fixation protection.
News
- phpredis v4.1.0 (released on 2018-07-10) added support for session locking, but it is disabled by default. To enable
it you must set the new
redis.session.locking_enabled
INI directive totrue
. This version is the first to pass the test inConcurrentTest
that stresses the locking mechanism.
Installation
RedisSessionHandler requires PHP >=5.6 with the phpredis extension enabled and a Redis >=2.6 endpoint. Add uma/redis-session-handler
to the composer.json
file:
$ composer require uma/redis-session-handler
Overwrite the default session handler with UMA\RedisSessionHandler
before your application calls
any session_
function. If you are using a framework and unsure when or where that happens, a
good rule of thumb is "as early as possible". A safe bet might be the frontend controller in the
public directory of the project or an equivalent initialization script.
Note that calling session_set_save_handler
overwrites any value you might have set in the session.save_handler
option
of the php.ini file, so you don't need to change that. However, RedisSessionHandler still uses session.save_path
to find
the Redis server, just like the vanilla phpredis session handler:
Available query params:
timeout
(float), default0.0
, which means unlimited timeoutprefix
(string), default'PHPREDIS_SESSION:'
auth
(string), defaultnull
database
(int), default0
Currently only a single host definition is supported.
Note than when connecting through a Unix socket the timeout is ignored.
Known Caveats
Using RedisSessionHandler with the max_execution_time
directive set to 0
is not recommended
Whenever it can, the handler uses the max_execution_time
directive as a hard timeout for the session lock. This is a
last resort mechanism to release the session lock even if the PHP process crashes and the handler fails to do it itself.
When max_execution_time
is set to 0
(meaning there is no maximum execution time) this kind of hard timeout cannot be used, as the lock
must be kept for as long as it takes to run the script, which is an unknown amount of time. This means that if for some unexpected reason
the PHP process crashes and the handler fails to release the lock there would be no safety net and you'd end up with a dangling lock
that you'd have to detect and purge by other means.
So when using RedisSessionHandler it is advised not to disable max_execution_time
.
RedisSessionHandler does not support session.use_trans_sid=1
nor session.use_cookies=0
When these directives are set this way PHP switches from using cookies to passing the session ID around as a query param.
RedisSessionHandler cannot work in this mode. This is by design.
RedisSessionHandler ignores the session.use_strict_mode
directive
Because running PHP with strict mode disabled (which is the default!) does not make any sense whatsoever. RedisSessionHandler only works in strict mode. The Session fixation section of this README explains what that means.
Motivation
The Redis session handler bundled with phpredis has had a couple of rather serious bugs for years, namely the lack of per-session locking and the impossibility to protect against session fixation attacks.
This package provides a compatible session handler built on top of the Redis extension that is not affected by these issues.
Session Locking explained
In the context of PHP, "session locking" means that when multiple requests with the same session ID hit the server roughly
at the same time, only one gets to run while the others get stuck waiting inside session_start()
. Only when that first request
finishes or explicitly runs session_write_close()
, one of the others can move on.
When a session handler does not implement session locking concurrency bugs might start to surface under heavy traffic. I'll demonstrate the problem using the default phpredis handler and this simple script:
First, we send a single request that will setup a new session. Then we use the session ID returned in
the Set-Cookie
header to send a burst of 200 concurrent, authenticated requests.
Everything looks fine from the outside, we got the expected two hundred OK responses, but if we peek inside the Redis database we see that the counter is way off. Instead of 201 visits we see a random number that is way lower than that:
Looking at Redis' MONITOR
output we can see that under heavy load, Redis often executes two or more GET
commands
one after the other, thus returning the same number of visits to two or more different requests. When that happens, all
those unlucky requests pass the same number of visits back to Redis, so some of them are ultimately lost. For instance, in this excerpt
of the log you can see how the 130th request is not accounted for.
RedisSessionHandler solves this problem with a "lock" entry for every session that only one thread of execution can create at a time.
Session fixation explained
Session fixation is the ability to choose your own session ID as an HTTP client. When clients are allowed to choose their session IDs, a malicious attacker might be able to trick other clients into using an ID already known to him, then wait for them log in and hijack their session.
Starting from PHP 5.5.2, there's an INI directive called session.use_strict_mode
to protect
PHP applications against such attacks. When "strict mode" is enabled and a unknown session ID is received, PHP should ignore it and generate a new
one, just as if it was not received at all. Unfortunately the phpredis handler ignores that directive and always trust whatever session ID is received from
the HTTP request.
Hence RedisSessionHandler only works in strict mode. It only accepts external session IDs that are already inside the Redis store.
Testing
Running the tests
To do that you'll need Docker >=1.10 and docker-compose >=1.8.
In order to run the integration test suite just type composer test
and it will take care of installing
the dev dependencies, setting up the testing containers and running the tests.
Running the tests against the native phpredis handler
You can easily run the same test suite against the native phpredis handler.
To do so, comment out the line in tests/webroot/visit-counter.php
where RedisSessionHandler is
enabled and the FPM container will automatically choose the phpredis save handler (version 3.1.2 at the time of writing).
Manual testing
The docker-compose.yml
file is configured to expose a random TCP port linked to the nginx container port 80. After running
composer env-up
or composer test
you can see which one was assigned with docker ps
. With that knowledge you can
poke the testing webserver directly from your local machine using either a regular browser, cURL, wrk or similar tools.
Depending on your Docker setup you might need to replace localhost
with the IP of the virtual machine that actually runs the Docker daemon: