Class RememberMe

Provide Remember Me functionality to restore a user's login state in a new session

This incorporates ideas from Barry Jaspan's article found here: http://jaspan.com/improved_persistent_login_cookie_best_practice

There are problems with most of the published articles on the subject of persitent authorization cookies, most specifically when dealing with concurrency issues in the modern web. If two or more requests from the same browser instance arrive at the server in a short time (i.e. impatient reload, restored tabs) all presenting the same one use token in the auth cookie, one will work, and the others will fail.

Using this functionality is a security risk. Ideally, this should only be used over ssl, but even then, the possibility of cookie theft still exists. Present that stolen cookie and the thief can become the authorized user. The following details the steps taken to provide a smooth user experience while minimizing the exposure surface of this risk.

Each time a new persistent auth cookie is requested, a new "series" is started. Associated with the series is a one time token, that changes whenever it is used. To "debounce" any concurrent requests: Instead of erasing the old token immediately, a short expire time is set. If a cookie is used with the expiring token, it is updated to the new session. After the expire time elapses, the old token is erased. If a cookie with an invalid series is presented, it is erased and ignored. If a cookie has a valid series, but an unknown token, we treat this as evidence of a stolen cookie or hack attempt and clear all stored series/tokens associated with the user.

Additionally, the surrounding application logic is aware that the persistent auth logic was used. We only supply a saved id, the application must process that id. That "fact" can be saved to require authentication confirmation as appropriate.

Namespace: Xoops\Core\Session
Package: RememberMe
Category: Xoops\Core\Session
Copyright: 2015 XOOPS Project (http://xoops.org)
License: GPL 2 or later (http://www.gnu.org/licenses/gpl-2.0.html)
Author: Richard Griffith richard@geekwright.com
Link: http://xoops.org
Located at oops_lib/Xoops/Core/Session/RememberMe.php

Methods summary
`public`	# `__construct( )` constructor constructor
`public integer\|false`	# `recall( )` Recall a user id from the "remember me" cookie. Recall a user id from the "remember me" cookie. Returns integer\|false user id, or false if non-exisiting or invalid cookie
`public`	# `forget( )` Forget a "remember me" cookie. This should be invoked if a user explicitly logs out of a session. If a cookie is set for this session, this will clear it and remove the associated series tokens. Forget a "remember me" cookie. This should be invoked if a user explicitly logs out of a session. If a cookie is set for this session, this will clear it and remove the associated series tokens.
`public`	# `invalidateAllForUser( integer $userId )` Invalidate all existing "remember me" cookie by deleting all the series/tokens Invalidate all existing "remember me" cookie by deleting all the series/tokens This should be called during a password change. Parameters `$userId` id of user associated with the sessions/tokens to be invalidated
`protected boolean`	# `hasSeries( string $series )` Check if the given series exists Check if the given series exists Parameters `$series` series identifier Returns boolean true if series exists, otherwise false
`protected`	# `unsetSeries( string $series )` Unset an entire series Unset an entire series Parameters `$series` series identifier
`protected boolean`	# `hasSeriesToken( string $series, string $token )` Get the values associated with a given series and token Get the values associated with a given series and token Parameters `$series` series identifier `$token` token to check Returns boolean true if series and token combination exists, otherwise false
`protected array\|false`	# `getSeriesToken( string $series, string $token )` Get the values associated with a given series and token Get the values associated with a given series and token Parameters `$series` series identifier `$token` token to check Returns array\|false
`protected`	# `setSeriesToken( string $series, string $token, array $values )` Get the values associated with a given series and token Get the values associated with a given series and token Parameters `$series` series identifier `$token` token to check `$values` valuestoken to check
`protected`	# `unsetSeriesToken( string $series, string $token )` Get the values associated with a given series and token Get the values associated with a given series and token Parameters `$series` series identifier `$token` token to check
`protected`	# `readUserTokens( integer $userId )` read existing user tokens from persistent storage read existing user tokens from persistent storage Parameters `$userId` id of user to read tokens for
`protected`	# `writeUserTokens( integer $userId )` write the existing user tokens to persistent storage write the existing user tokens to persistent storage Parameters `$userId` id of user to write tokens for
`protected`	# `removeExpiredTokens( )` Remove any expired tokens Remove any expired tokens
`protected`	# `clearUserTokens( )` Clear all tokens for this user Clear all tokens for this user
`protected string`	# `getNewSeries( )` Generate a new series Generate a new series Returns string a new series key
`protected string`	# `getNewToken( )` Generate a new token Generate a new token Returns string a new token
`public`	# `createUserCookie( integer $userId )` Create a new user cookie, usually in response to login with "remember me" selected Create a new user cookie, usually in response to login with "remember me" selected Parameters `$userId` id of user to be remembered
`protected`	# `clearUserCookie( )` Update cookie status for current session Update cookie status for current session
`protected array\|false`	# `readUserCookie( )` Read the user cookie Read the user cookie Returns array\|false the cookie data as array(userid, series, token), or false if cookie does not exist (or not configured)
`protected`	# `writeUserCookie( array\|string $cookieData, integer $expire = 2592000 )` Update cookie status for current session Update cookie status for current session Parameters `$cookieData` usercookie value `$expire` seconds until usercookie expires

Properties summary
`protected array`	`$userTokens`	# `array()`
`protected integer`	`$userId`	# `0`
`protected Xoops`	`$xoops`	# `null`
`protected integer`	`$now`	# `0`

Namespaces

Classes

Interfaces

Class RememberMe

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Returns

Returns

Parameters

Returns

Parameters