66
77This library provides a simple drop-in replacement to PHP's out-of-the-box
88session functionality to provide more robust and secure session handling by
9- enforcing recommend php.ini session settings and providing optional session
9+ enforcing recommended php.ini session settings and providing optional session
1010data encryption, with client-side decryption key storage (in cookie).
1111Encryption is provided via use of the excellent [ defuse/php-encryption] ( https://github.com/defuse/php-encryption ) library.
1212
13- The primary components of the library are:
13+ ** The primary components of the library are:**
1414
1515[ UltimateSessionHandler] ( docs/MikeBrant-UltimateSessions-UltimateSessionHandler.md )
1616
17- A class which extends PHP's ` SessionHandler ` class with added encryption
18- capability. Class instantiation automatically sets php.ini session settings
19- to their preferred values and sets the class as session save handler via
17+ A class which extends PHP's ` SessionHandler ` class with added encryption
18+ capability. Class instantiation automatically sets php.ini session settings
19+ to their preferred values and sets the class as session save handler via
2020` set_session_save_handler() ` .
2121
22- [ AbstractUltimateSessionHandler] ( docs/MikeBrant-UltimateSessions-AbstractUltimateSessionHandler.md )
23-
24- An abstract class made available for those wanting to implement their own
25- session handler that does not extend from SessionHandler. This would be an
26- atypical situation, but it is here if needed.
27-
28- (Planned for future) UltimateSessionManager - A class to provide
29- object-oriented access to
30- typical PHP session handling functions along with timestamp based session
31- security.
22+ [ UltimateSessionManager] ( doc/MikeBrant-UltimateSessions-UltimateSessionManager.md )
23+
24+ This class is an object-oriented wrapper around common PHP session management
25+ functions along with features geared at enhancing security
26+ and proper session management behaviors including:
27+ - timestamp-based management for session data expiry;
28+ - automated session ID regeneration at configurable time- and count-based
29+ intervals;
30+ - client fingerprinting based on request header properties
31+ - logging of data for certain use cases where there are session accesses
32+ against expired data or accesses with mis-matched fingerprints, which may
33+ need further investigation. Only data within session metadata is logged.
34+ An optional PSR-3 compliant logger to be used for logging in lieu of
35+ default logging via ` error_log() ` .
36+
37+ This class allows for setting of callback around session ID change events
38+ (ID regeneration or ID forwarding from expired session). For example, in
39+ recommended library configuration, this callback is used to trigger
40+ encryption key cookie regeneration using
41+ ` UltimateSessionHandler::changeKeyCookieSessionId() ` .
42+
43+ For cases where custom session garbage collection is implemented
44+ (something that should strongly be considered for production-level
45+ applications), this class offers setting of an optional callback that
46+ is passed session ID and data expiry timestamp that can be used to mark
47+ those session ID's as eligible for garbage collection after given
48+ timestamp (by touching files, updating database field, etc.).
49+
50+ [ UltimateSessionLoader] ( doc/ )
51+
52+ A simple static interface provided to allow for one-line instantiation of
53+ the UltimateSession library using recommended settings, with a few minimal
54+ configuration options.
3255
3356Requires:
3457- PHP 5.6+
@@ -53,31 +76,90 @@ This library is developed against PHP 7.1 and tested via Travis CI against:
5376
5477** Usage**
5578
56- Usage is intended to be dead simple. Just instantiate
57- UltimateSessoinConfig passing optional parameters:
58- - ` $useEncryption ` (boolean, default ` false ` )
59- - ` $keyCookiePrefix ` (string, default ` ULTSESS_ ` )
79+ Usage is intended to be dead simple. Using
80+ ` UltimateSessionLoader::initialize() ` you can
81+ set up with few lines of code. The parameters for this method are:
82+
83+ - ` $useEncryption ` (boolean, default ` false ` ) Flag to determine if encryption
84+ is applied to session data.
85+ - ` $logger ` (Psr\Log\LoggerInterface, default null) A PSR-3 compliant logger
86+ can be attached to UltimateSessionManager to allow for logging of
87+ non-standard session access events.
6088
61- Then pass this config to a new UltimateSessionHandler instance
62- and start your session.
89+ Sample code usage:
6390
6491``` php
6592
6693use \MikeBrant\UltimateSessions;
6794
6895try {
69- $sessionConfig = UltimateSessionConfig::getInstance(
70- $useEncryption,
71- $keyCookiePrefix)
72- ;
73- new UltimateSessionHandler($sessionConfig);
96+ $sessionManager = UltimateSessionLoader::initialize(
97+ $useEncryption,
98+ $logger
99+ );
74100} catch (\Exception $e) {
75101 // handle as needed (or don't try-catch at all)
76102}
77- session_start();
103+ // replacement for session_start()
104+ $result = $sessionManager->startSession();
105+
106+ // Make sure to investigate result of startSession()
107+ // as false represents a case where an invalid session was attempted
108+ // to be started
109+ if($result === false) {
110+ // perhaps exit execution
111+ // at a minimum drop all user authentication/state
112+ }
113+
114+ // set session data as normal
115+ $_SESSION['data'] = 'value;
116+
117+ // manually regenerate session Id
118+ // as typically done around authentication or privelege level change
119+ $sessionManager->regenerateId();
120+
121+ // get session ID
122+ $sessionId = $sessionManager->getSessionId();
123+
124+ // close session to write, replacement for session_write_commit()
125+ $sessionManager->commitSession();
126+
127+ // destroy session. Not commonly used, by calling code, but can be
128+ // used as necessary to unset $_SESSION and destroy session as done
129+ // with session_destroy()
130+ $sessionManager->destroySession();
78131```
79132
80- Recommended reading related to PHP session security:
133+ There are more configuration options available beyond this Please look at
134+ full library documentation at link above.
135+
136+ Note that while the ` UltimateSessionHandler ` and ` UltimateSessionManager ` are
137+ designed to work together, each of these classes could be used independently
138+ of each other. The ` UltimateSessionHandler ` class should also be considered
139+ as a class designed to be extended upon should one want to implement custom
140+ session storage (i.e. in database, memory store, etc.) above and beyond
141+ one of the built-in PHP session stores which which this class can work as-is.
142+
143+ ** A note on session garbage collection:**
144+
145+
146+ This library does not perform session garbage collection or override default
147+ ` SassionHandler::gc() ` behavior at all. As such, this class would work with
148+ PHP's built in session stores and not modify their basic behavior at all. If one were to extend ` UltimateSessionHandler ` to implement a custom data
149+ store it is ** highly** recommended that you not rely on PHP's default probability-based garbage collection scheme (and thus not override ` gc() `
150+ method at all). It is preferable to use a schedule-based garbage collection
151+ mechanism as a means to perform final deletion of session stores. To this
152+ end, the ` UltimateSessionManager ` class constructor accepts a callback
153+ which can be used as a hook for you to update your session data store with
154+ a timestamp after which the individual data for the session can be removed.
155+ This hook can actually be used even in cases where you want to override
156+ ` gc() ` in a probability-based deletion scheme (the probability-based
157+ approach triggers ` gc() ` session handler). You would just need your
158+ overridden ` gc() ` method to take advantage of the timestamps that have
159+ been set on the data store to determine eligibility of the session data
160+ for deletion.
161+
162+ ** Recommended reading related to PHP session security:**
81163
82164[ PHP Session Lifecycle] ( https://gist.github.com/mindplay-dk/623bdd50c1b4c0553cd3 )
83165
0 commit comments