Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ The first release. Nothing is tagged yet.
### Rate Limits and Risk

- Rate limits per account, per typed username and per IP address, with locks that double, a count of their own for browsers the account has signed in from, a cap on failures in a row kept in the database, and `limits.lock_after` to keep an account locked until its password is reset.
- A timebox around every verification, so a refusal takes the same time whatever the reason.
- A timebox around every verification, registration and refused password reset, so a refusal takes the same time whatever the reason.
- Risk signals with an action for each level: a new device, a new country, impossible travel, a session turning up in another browser, repeated failed second factors, a sign in after several failures or after a long quiet period, a recently changed email address and a password found in a breach. A new app starts with the ones its features can feed, and a password found in a breach holds its user until they choose another.

### Logging and Emails
Expand Down
11 changes: 11 additions & 0 deletions UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,14 @@
Keyring has no tagged release yet, so there's nothing to upgrade from. This guide starts with the first release, and will list anything you need to change when updating from one release to the next.

What counts as a change you'd need to act on is in the README's [What's Stable](README.md#whats-stable). A test (`tests/Feature/PublicApiTest.php`) fails when a config default changes, or a route, middleware alias, facade method, contract, event or email type is renamed or removed, so one can't change without an entry here.

## Before the First Release

Changes made since the first installs from `dev-main`, for anyone already running one:

- **`keyring_sessions` has a `user_type` column.** A session record now says which table its user's ID is one of (the connection and table, as `RegisteredSession::typeOf($user)` gives it), so two user models with the same IDs don't share sessions. Add `$table->string('user_type')` and an index on `['user_type', 'user_id']` to your published migration, and empty the table: everyone signs in again. With the `cache` driver there's nothing to change: a record from before has no type, isn't found, and its browser signs in again. A custom `SessionRegistry` has to store the new `userType` field and match on it in `forUser()`, `revokeAll()` and `revokeDevice()`.
- **`timebox` defaults to `500ms`, up from `250ms`.** It has to be longer than one password hash takes, and bcrypt at 12 rounds is close to 250ms on ordinary hardware. Set it in `config/keyring.php` to keep the old value.
- **An address a change replaced is looked up differently while it's reserved**, so that "ß" is found under either spelling a database takes it for. Reservations made before this, for an address with a doubled "s", aren't found until they lapse (a week at most).
- **Rate limits, locks and risk locks are kept under new keys.** Ones in place when this is deployed are left behind: an account locked then is unlocked early, once.
- **Saving the current password as the new one is refused** on `PUT /user/password`, with a validation error on `password`.
- **A mid-session risk step-up signs the session out when `sessions.end_on_lapse` is on**, where it used to carry on with nothing proved.
6 changes: 4 additions & 2 deletions bin/ci
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,11 @@ mysql() {
docker run -d --rm --name "$name" -e MYSQL_DATABASE=keyring -e MYSQL_ROOT_PASSWORD=password \
-p "127.0.0.1:$port:3306" mysql:8.4 >/dev/null || return 1

# It answers a ping before it takes connections, so ask it a question.
# It answers a ping before it takes connections, so ask it a question,
# and over TCP: while it sets itself up it runs a first server that only
# listens on its socket, then stops it and starts the real one.
for _ in $(seq 60); do
docker exec "$name" mysql -ppassword -e 'select 1' keyring >/dev/null 2>&1 && break
docker exec "$name" mysql --protocol=tcp -h127.0.0.1 -ppassword -e 'select 1' keyring >/dev/null 2>&1 && break
sleep 2
done

Expand Down
8 changes: 5 additions & 3 deletions config/keyring.php
Original file line number Diff line number Diff line change
Expand Up @@ -438,12 +438,14 @@
| Timebox
|--------------------------------------------------------------------------
|
| Every failed factor verification takes at least this long, so response
| timing doesn't reveal whether an account exists.
| Every refused sign in, registration and password reset takes at least
| this long, so response timing doesn't reveal whether an account exists.
| It only hides what's shorter than it: keep it comfortably longer than
| one password hash takes on your servers.
|
*/

'timebox' => '250ms',
'timebox' => '500ms',

/*
|--------------------------------------------------------------------------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ public function up(): void
{
Schema::create('keyring_sessions', function (Blueprint $table) {
$table->string('id', 64)->primary();
$table->string('user_id')->index();
$table->string('user_id');
$table->string('user_type');
$table->string('guard');
$table->string('device_id', 26)->nullable()->index();
$table->unsignedTinyInteger('assurance')->default(0);
Expand All @@ -28,6 +29,8 @@ public function up(): void
$table->string('replaced_by', 64)->nullable();
$table->unsignedInteger('replaced_at')->nullable();
$table->boolean('remembered')->default(false);

$table->index(['user_type', 'user_id']);
});
}

Expand Down
8 changes: 5 additions & 3 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ How long a user has to finish adding a sign-in method once they've started. See
|---|---|
| `driver` | `database`, `cache`, or the name of a driver you've added. |
| `connection`, `table` | Used by the `database` driver. |
| `store` | The cache store used by the `cache` driver. `null` is your default store. |
| `store` | The cache store used by the `cache` driver. `null` is your default store. Use one that keeps its keys until they expire: a store that evicts under memory pressure can drop the list of a user's sessions, and a sign-out everywhere then misses the ones it listed. The `database` driver has no such store to depend on. |
| `max` | How many sessions one account can have at once. A sign in beyond that ends the one unused longest. `null` for no limit. See [How Many Sessions](devices-and-sessions.md#how-many-sessions). |
| `idle` | Inactivity allowed before a session ends. `null` leaves it to Laravel's session lifetime. |
| `remember_idle` | The same, for a browser that ticked "remember me": how long it may stay away and still be signed back in, with nothing proved. `null` lets it stay away for the whole `absolute` limit. See [Inactivity and "Remember Me"](devices-and-sessions.md#inactivity-and-remember-me). |
Expand Down Expand Up @@ -335,7 +335,7 @@ The table is `Features::securityLog()`, which is on by default. Without it the s
'keep_for' => '10m',
],

'timebox' => '250ms',
'timebox' => '500ms',

'limits' => [
'per_account' => 5,
Expand All @@ -355,7 +355,9 @@ The table is `Features::securityLog()`, which is on by default. Without it the s

`pending_logins.keep_for` is how long a half-finished login or confirmation stays valid, as a [duration](#durations). It's also the `expiresAt` shown on the challenge page.

`timebox` is the minimum time a refused verification takes, so timing doesn't reveal whether an account exists or whether a password refused for another reason was right. It covers every pipeline step, so a request refused by a rate limit or by validation waits too. Verifications that go through return straight away.
`timebox` is the minimum time a refused verification takes, so timing doesn't reveal whether an account exists or whether a password refused for another reason was right. It covers every pipeline step, so a request refused by a rate limit or by validation waits too, and a registration and a refused password reset are held for it as well. Verifications that go through return straight away.

It only hides what's shorter than it. The slowest thing a refusal does is hash a password, and not every refusal hashes one at the same cost: an account's password is checked at the cost its stored hash was made with, which differs from today's while old hashes are being moved to a new one, and a reset token is only checked for an address with a link outstanding. So keep `timebox` comfortably longer than one password hash takes on your servers. Bcrypt at 12 rounds takes around 200ms on current hardware and more on a small instance. Keyring tells you when it isn't: a refusal that took longer than `timebox` writes a warning to your app's log, at most once an hour, which is the check that sees your real hashing cost on your real servers. The [conformance suite](testing.md#the-conformance-suite) also times a hash where your tests run and fails when it doesn't fit, as an early guide.

`limits` are the default attempts per minute for each factor, per account and per IP address, and `consecutive`, the failures in a row one of an account's authenticators allows before it's refused for that account (`null` for no cap, and 100 is the most NIST SP 800-63B-4 allows, Sec. 3.2.2). Those are counted in the `keyring_failure_counts` table, and nothing brings a refused authenticator back by itself: see [At the Cap](security.md#at-the-cap). `consecutive_elsewhere` is how many of them may come from browsers the account hasn't signed in from, which keeps the rest for the owner's own. It only applies with `Features::devices()` on, and `null` keeps nothing back. `remember_names_for` is how long the cache keeps the failures in a row counted under each typed username, which is what the sign-in form answers from.

Expand Down
7 changes: 4 additions & 3 deletions docs/devices-and-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ An account keeps its 50 most recently seen devices (`devices.limit`). A sign in

Each device records a readable name built from the user agent (the browser and the operating system, as in ":browser on :platform"), the last IP address and location, and when it was first and last seen. The user agent is never a factor. It's only a weak risk signal: `SessionFingerprintChanged` notices when a session's browser or platform changes.

A browser shared by several accounts has one cookie and a device for each account that signed in on it. Keyring only reuses a cookie that another account already has a device for. Anything else the browser sends is ignored and replaced with a new random token. Keyring can't tell which browser holds a cookie, so a value planted from another account's device is reused too, and the device counts as recognised, until a login on it proves a second factor. Every login that reaches AAL2 gives the browser a new cookie, so the previous one stops working.
A browser shared by several accounts has one cookie and a device for each account that signed in on it. An account's device never takes a value the browser sent: Keyring can't tell a cookie two accounts share from one that was placed in the browser holding a value someone else's device has, and taking it would get that someone's own browser recognised as this account's. So an account signing in on a browser for the first time gives it a new cookie, and the accounts already on that browser move to the new one with it. Every login that reaches AAL2 gives the browser a new cookie too, so the previous one stops working.

### Trusted Devices

Expand Down Expand Up @@ -316,7 +316,7 @@ Then set `sessions.driver` to `custom`. Keyring calls `replace()`, `revokeAll()`
|---|---|
| `save($session)` | Stores a new `RegisteredSession`. It must never clear a revocation made in the meantime, or what a record was replaced by. |
| `find($id)` | The session, or `null`. |
| `forUser($user)` | The user's sessions that haven't expired, been revoked or been replaced, most recent first. |
| `forUser($user)` | The user's sessions that haven't expired, been revoked or been replaced, most recent first. A session is a user's by more than the ID: match on the record's `userType` (`RegisteredSession::typeOf($user)`, the connection and table the ID is one of) and its `userId`, here and in `revokeAll()` and `revokeDevice()`, or two user models with the same IDs would share sessions. `$session->belongsTo($user)` checks both. |
| `update($id, $changes)` | Changes only the named fields, such as `['lastActivityAt' => $now]` or `['assurance' => $level, 'expiresAt' => $at]`. Field names are as on `RegisteredSession`; `RegisteredSession::columns($changes)` turns them into snake case columns. Writing only these fields means a request can't write back a stale copy of the rest. |
| `revoke($id)` | Revokes one session. |
| `replace($id, $successor, $revoke = false)` | Moves a session to a new record: stores `$successor` and sets the old record's `replacedBy` and `replacedAt` (and revokes it, with `$revoke`). It only does so for a record that is neither revoked nor replaced, and returns whether it did. Of two calls for the same record at the same moment exactly one may return `true`, and the other's record must not be left behind: "remember me" being single use rests on this. The database driver uses one conditional `UPDATE` in a transaction, the cache driver the store's `add()`. |
Expand Down Expand Up @@ -518,8 +518,9 @@ That isn't enough where the whole app is meant to be AAL2, or where you want NIS
- A session ends on the first request after the level it **signed in at** runs out: after that level's `idle` without a request, or its `absolute` after the factors were proved. The user is signed out as for any other timeout, with the reason `idle` or `expired` on `SessionEnded`.
- Proving every factor for that level again before then (any [step-up](step-up.md) that asks for them all) starts both limits over, as reauthenticating does in NIST.
- A level reached later by a step-up still lapses on its own and takes nothing with it. A session that signed in with a password and stepped up for one page stays an AAL1 session.
- A [risk response](risk.md#responding-to-risk) that asks a signed-in session to step up ends it too: forgetting what the session proved is its level running out. The reason on `SessionEnded` is `risk`.
- "Remember me" brings nothing back. Its cookie proves nothing, so there's no level for the session to carry on at: the browser signs in again. NIST doesn't accept such a cookie in place of authenticating either (Sec. 5.1), so leave the checkbox off your login page.
- Sessions signed in at AAL1 are unaffected: `idle` and `absolute` already end those.
- The timeouts leave sessions signed in at AAL1 as they were: `idle` and `absolute` already end those.

[Recipes](recipes.md#an-app-whose-every-page-needs-aal2) has the full setup for an app whose every page needs AAL2.

Expand Down
5 changes: 5 additions & 0 deletions docs/passkeys.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,11 @@ A key reaches [AAL3](policies.md#assurance-levels) only when its factor uses `re

- Keys added before the factor asked for attestation have nothing in that column and stay at AAL2. Their owners add them again to reach AAL3.
- Take `requireAttestation()` off a factor and its keys stop reaching AAL3, whatever the column says.
- Narrowing [`allowOnly()`](#allowing-only-certain-models), or taking a root out of the list, only stops more of those keys being added. The ones already on accounts keep their level, so changing what you hand out doesn't lock out everyone holding the old model. When a model has to stop counting (it was found to be weak, say), clear the column for its keys, which leaves them as second factors at AAL2, or delete the rows to remove them:

```php
Keyring::authenticatorModel()::query()->where('aaguid', $aaguid)->update(['attestation' => null]);
```
- The attestation is for the key. Its second factor still has to be its own user verification or a password: touching an attested key after signing in with a synced passkey is AAL2.

NIST AAL3 also needs the authenticator validated to FIPS 140 (Sec. 2.3.2). Attestation says which model a key is, not whether that model was validated, so use `allowOnly()` to accept only the models you've checked.
Expand Down
4 changes: 3 additions & 1 deletion docs/protected-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,8 @@ The current address can revert the change while it's pending, and for `email_cha

The user is then redirected to the forgot password page (or the login page, when password resets are off) with `status` set to `email-change-reverted`, since whoever made the change may also know the password. Reverting doesn't change the password itself.

**Who the undo trusts.** The link is for an owner who has lost everything but their old mailbox: someone got into the account, added a passkey of their own and moved the address. So it asks for nothing but the link, and it takes away the sign-in methods that are too new to be surely the owner's. That works both ways. Whoever reads the old mailbox can press it, and when the change was the owner's own, moving away from a mailbox someone else can read, the undo removes a second factor the owner added in that window, and a password reset through the same mailbox then signs in without one. Keyring can't tell the two people apart: each holds exactly the old mailbox. `established_after` is where the line sits. A sign-in method the account has had for longer than that, added before the session that asked signed in, survives an undo, so a second factor set up a week or more before changing address is safe from it. When the change had applied, the new address is told it was undone, so the owner hears of it there. Shorten `revertable_for` and `established_after` if your users are likelier to be leaving a mailbox they've lost than to have their session taken, and lengthen them for the opposite.

### The Old Address Is Reserved

While a change can still be reverted, nobody else can take the address it replaced. Otherwise someone who changed the address could register a new account with the old one, and the owner's revert would have nowhere to put it back. That goes for lookalikes too: an address that differs only in case, accents, letter width or characters that don't show is held back with it, because MySQL's and MariaDB's default collations take those for the same address and their unique index would refuse to give it back. Another account asking to move to it gets the same "address in use" email as for any taken address. [Registration](sign-in-flow.md#registration) counts it as taken too, so it's answered like any address that has an account. Where your own code creates users or gives them a new address (an admin screen, an import), `Keyring\Rules\UnreservedAddress` refuses it with Laravel's "has already been taken" message, so use it next to `Rule::unique()`:
Expand Down Expand Up @@ -231,7 +233,7 @@ While a user is held:

- They can still sign in. Every signed-in request in the `web` group sends them to `password_change_url` with the `change-password` status. JSON requests get a `403` with that status and the URL as `redirect`. Without a `password_change_url`, they get a plain `403`.
- That page is let through, for any method, and so are `PUT /user/password`, the [confirm page](step-up.md#the-confirm-flow) it may send them to, signing out and email verification. Nothing else is, including Keyring's other routes.
- The hold ends when the password changes: through `PUT /user/password`, or a [password reset](#resetting-the-password). If your app saves passwords itself, without `Features::updatePasswords()`, call `Keyring::cancelPasswordChange($user)` once it has saved a new one.
- The hold ends when the password changes: through `PUT /user/password`, or a [password reset](#resetting-the-password). It has to be a different password. `PUT /user/password` refuses the current one as the new one, for every user, and a reset to the same password goes through like any other but leaves the hold in place, so the form doesn't tell whoever holds the link that they guessed it. If your app saves passwords itself, without `Features::updatePasswords()`, call `Keyring::cancelPasswordChange($user)` once it has saved a new one, and check it's a new one first: nothing in that call does.
- Signing out and in again changes nothing. The hold is a row in `keyring_password_holds`, not something in the session or the cache.
- A hold placed by a request reaches that request's session at once. Other sessions that are already signed in hear of it within a minute.

Expand Down
Loading