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
11 changes: 6 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ The first release. Nothing is tagged yet.
### Signing In

- Sign in, sign out, registration, password resets and email verification, with your own actions and pages.
- Registration that doesn't reveal who has an account: the same answer for a free and a taken address, with new users signing in once they've verified theirs. `registration.reveal_taken` says when an address is taken instead.
- Registration that doesn't reveal who has an account: the same answer for a free and a taken address, even when your action fails to create the user, with new users signing in once they've verified theirs, from the browser that followed the link, which gets a new session ID for it. `registration.reveal_taken` says when an address is taken instead.
- Factors behind one contract: password, authenticator apps, passkeys, security keys, email codes and recovery codes, plus your own. Many authenticators per user, with a default and "try another way".
- Passkeys and security keys from one WebAuthn driver: ES256 and EdDSA by default, RS256 when you ask for it, a challenge that is answered once and runs out on the server, and sign in with Laravel's `@laravel/passkeys` client. Like Laravel's passkeys package, the options name the relying party by its ID, so there's no name to set.
- `WebAuthn::securityKeys()->requireAttestation()` to only add hardware keys whose attestation chains to root certificates you list, and `allowOnly()` to limit them to certain models by AAGUID.
Expand All @@ -22,7 +22,7 @@ The first release. Nothing is tagged yet.

- Policies built from assurance levels that follow NIST SP 800-63B-4: AAL2 needs a factor the user has, and AAL3 an attested key that can't leave its device. `ifEnrolled()` and `noDowngrade()` say how a policy treats users who can't meet it yet, or who have a passkey.
- `keyring.enrolled` to make everyone set up a second factor, which the installer adds when you pick one.
- Step-up middleware: `keyring:aal2` and `keyring.fresh:15m`, with a shared confirm flow. Changing how an account signs in takes the strongest proof the account can give.
- Step-up middleware: `keyring:aal2` and `keyring.fresh:15m`, with a shared confirm flow. Changing how an account signs in takes the strongest proof the account can give, and a recovery code only counts there beside another factor.

### Sessions and Devices

Expand All @@ -37,8 +37,8 @@ The first release. Nothing is tagged yet.

- Protected `email` and `password` attributes, which only change through Keyring's flows once it handles them.
- Email changes confirmed from both addresses and revertable from the old one, with the old address reserved while they can be undone.
- Password changes that take the current password, and resets that sign nobody in, end every session and leave second factors alone.
- Password rules that follow OWASP ASVS 5.0.0 and NIST SP 800-63B-4: 15 characters alone or 8 with a second factor, no composition rules, a bundled list of the most common passwords, your own context words, a breach check that can refuse what it couldn't check, and Unicode normalised to NFC.
- Password changes that take the current password and are only saved over the one that was checked, and resets that sign nobody in, end every session and leave second factors alone.
- Password rules that follow OWASP ASVS 5.0.0 and NIST SP 800-63B-4: 15 characters alone or 8 with a second factor, no composition rules, a bundled list of the most common passwords, your own context words, a breach check that can refuse what it couldn't check, Unicode normalised to NFC, and, with bcrypt, a password it would cut short or can't hash refused.
- `Keyring::requirePasswordChange()`, and a risk action of the same name, to hold a user until they choose a new password when theirs is known to someone else.
- Emailed links that only act on a button press, with the token or signature posted in the body, built from `APP_URL` and opened on pages that send no referrer.

Expand All @@ -50,7 +50,7 @@ The first release. Nothing is tagged yet.

### Logging and Emails

- A security log with a severity and a request ID on every entry, of sign ins, sessions "remember me" carried on, failures, lockouts, changes and what was refused, capped so a refused request can't fill it. Without the table it goes to your app's log.
- A security log with a severity and a request ID on every entry, of sign ins, sessions "remember me" carried on, failures, lockouts, changes and what was refused, capped so a refused request can't fill it, and written whatever text an entry is about. Without the table it goes to your app's log.
- "Was this you?" alerts at the next sign in.
- Security emails about changes to how an account signs in and about suspicious attempts, sent from the start as far as your features go. Each is a notification you can swap for your own or turn off, and `SecurityNotice::toMailUsing()` writes them all from your own template.
- `support_contact`, so every notice can say who to contact.
Expand All @@ -60,6 +60,7 @@ The first release. Nothing is tagged yet.

- `keyring:install`, which asks which sign-in methods and features you want and publishes a config, a provider and your actions. Its defaults give the password alone, and every other sign-in method is in the provider, commented out, to turn on later. Also `keyring:import fortify`, and `keyring:prune`, scheduled daily.
- Security headers on Keyring's responses: `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Cross-Origin-Opener-Policy: same-origin-allow-popups` and a referrer policy.
- `Keyring::result()`, for a page to read what a form or Inertia response flashed for it, such as new recovery codes, which is kept encrypted in the session.
- Test helpers, a fake, factories, a virtual WebAuthn authenticator and a conformance suite that checks your setup still keeps Keyring's guarantees.
- `@entity/keyring`, a browser package for WebAuthn, enrollment, sessions and the challenge page, with Vue and React bindings.
- Documentation of where Keyring stands on every requirement of OWASP ASVS 5.0.0 and NIST SP 800-63B-4 that bears on it, and of each place it deliberately does something else.
1 change: 1 addition & 0 deletions UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Changes made since the first installs from `dev-main`, for anyone already runnin
- **`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.
- **What a form or Inertia response flashes for the page is encrypted.** Read it with `Keyring::result()` (or `Keyring::result('recoveryCodes')` for one key) instead of `session('keyring.result')`, which now holds ciphertext. In an Inertia middleware, share `'keyringResult' => fn () => Keyring::result()`. JSON responses are unchanged.
- **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.
- **`webauthn.relying_party.name` is gone.** WebAuthn deprecates the relying party name and most browsers don't show it, so the options now carry the relying party ID in its place, as Laravel's passkeys package does. Remove the key and `KEYRING_WEBAUTHN_RP_NAME` from your config, and any call to or override of `Ceremonies::relyingPartyName()`, which is gone too. Keys registered before keep working.
6 changes: 3 additions & 3 deletions docs/authenticators.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Adding is always two steps. Nothing is saved until the second one succeeds.
}
```

Authenticator apps and email codes take an optional `name` when beginning or confirming (the one sent when confirming wins); passkeys and security keys take it when confirming. Names default to "Authenticator app", "Email", "Passkey" or "Security key", and are cut to 64 characters.
Authenticator apps and email codes take an optional `name` when beginning or confirming (the one sent when confirming wins); passkeys and security keys take it when confirming. Names default to "Authenticator app", "Email", "Passkey" or "Security key", and are cut to 64 characters. A name that isn't valid UTF-8, or holds a NUL character, is refused with an error on `name`.

### Confirming

Expand Down Expand Up @@ -148,7 +148,7 @@ It loads the user's authenticators, so keep it lazy as above. A session that jus

| Field | |
|---|---|
| `name` | Optional, up to 64 characters. |
| `name` | Optional, up to 64 characters of valid UTF-8. |
| `default` | Optional boolean. `true` makes this the default and clears the flag on the user's others. Not allowed for recovery codes. |

The default authenticator is offered first when a second factor is needed. Recovery codes are a fallback, so they can't be made the default.
Expand Down Expand Up @@ -191,7 +191,7 @@ Every route answers with a [status response](sign-in-flow.md#status-responses).
| Update | `authenticator-updated` | `authenticator` |
| Remove | `authenticator-removed` | |

Other requests are redirected back with the `status` flashed, and the extra data flashed under `keyring.result` (for example `session('keyring.result.enrollment')`). The [browser package](frontend.md#managing-authenticators) uses the JSON form.
Other requests are redirected back with the `status` flashed, and the extra data flashed, encrypted, for the next request. Read it with `Keyring::result()`, or one key with `Keyring::result('enrollment')`. The [browser package](frontend.md#managing-authenticators) uses the JSON form.

## From JavaScript

Expand Down
4 changes: 2 additions & 2 deletions docs/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -406,7 +406,7 @@ Update any paths your own pages link to directly, such as `/login` or `/register

## Flash Messages and Alerts

Keyring's non-JSON responses flash a `status` slug to the session (JSON responses include it as `status`, with a readable `message`), such as `code-sent`, `password-updated`, `device-revoked` or `email-change-requested`. Extra data, such as new recovery codes, is flashed as `keyring.result`. See [Status Responses](sign-in-flow.md#status-responses).
Keyring's non-JSON responses flash a `status` slug to the session (JSON responses include it as `status`, with a readable `message`), such as `code-sent`, `password-updated`, `device-revoked` or `email-change-requested`. Extra data, such as new recovery codes, is flashed encrypted: read it with `Keyring::result()`, not from the session. See [Status Responses](sign-in-flow.md#status-responses).

Share them through your Inertia middleware alongside the ["was this you?" alerts](security-log-and-emails.md#was-this-you-alerts). `Keyring::statusMessage()` translates a slug from `keyring::status.*`, and gives `null` for anything else:

Expand All @@ -419,7 +419,7 @@ public function share(Request $request): array
...parent::share($request),
'status' => fn () => $request->session()->get('status'),
'statusMessage' => fn () => Keyring::statusMessage($request->session()->get('status')),
'keyringResult' => fn () => $request->session()->get('keyring.result'),
'keyringResult' => fn () => Keyring::result(),
'keyringAlerts' => fn () => $request->session()->get('keyring.alerts', []),
];
}
Expand Down
8 changes: 4 additions & 4 deletions docs/protected-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ A `MustVerifyEmail` user whose address isn't verified yet is refused with `keyri

### Confirming

The new address must always confirm. The current address must confirm too, unless this session proved a possession factor the account has had for `email_changes.established_after` (7 days by default), and since before this session signed in. A newer factor doesn't count, so whoever got in can't add one, use it and skip the check, in the same session or by signing in again with it. Neither does another account's factor, so an impersonated or switched session can't skip it with the admin's.
The new address must always confirm. The current address must confirm too, unless this session proved a possession factor other than a recovery code that the account has had for `email_changes.established_after` (7 days by default), and since before this session signed in. A newer factor doesn't count, so whoever got in can't add one, use it and skip the check, in the same session or by signing in again with it. Neither does another account's factor, so an impersonated or switched session can't skip it with the admin's.

The change applies once every required confirmation is in. When it applies, Keyring checks the address is still the one the change was requested from, and that no one else has taken the new one in the meantime. If either has changed, the pending change is cancelled. Applying also sets `email_verified_at`, when the model has that attribute loaded, and stops trusting the user's devices.

Expand Down Expand Up @@ -147,7 +147,7 @@ The current address can revert the change while it's pending, and for `email_cha

- puts the old address back, even when it was a later change that moved it,
- cancels any later email changes, so links from them can't move the address away again,
- deletes every authenticator that wasn't established when the change was asked for (added within `email_changes.established_after` before it, or since the session that asked signed in), one at a time, dispatching `AuthenticatorRemoved` for each. That can include one the owner added that week, which they can add again,
- deletes every authenticator that wasn't established when the change was asked for (added within `email_changes.established_after` before it, or since the session that asked signed in), one at a time, dispatching `AuthenticatorRemoved` for each. That can include one the owner added that week, which they can add again. When none of what's left is a factor for recovery codes to recover, the codes go too, as they do when the user removes their last second factor, with an `AuthenticatorRemoved` of their own,
- signs out every session, and changes the "remember me" token.

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.
Expand Down Expand Up @@ -207,7 +207,7 @@ Your action doesn't need to check `current_password` again. One that still does,

A user without a password (for example, one who only uses passkeys) can set one with just the fresh verification.

Keyring runs your action as one of its own flows, so it may change the protected `password` attribute, and only that: changing `email` there still throws. The action must save a new password or throw a `ValidationException`; returning without saving throws a `LogicException`, since everything that follows assumes the password changed. Afterwards Keyring regenerates the session ID, destroying the old one, cancels any pending email change, ends any reset links still outstanding, stops trusting the user's devices, including this one, and starts the account's sign-in limits over as a reset does, so a password that too many wrong guesses had got refused works again. With `sign_out_others` on, it also revokes every other session and changes the "remember me" token. The response is the `password-updated` [status response](sign-in-flow.md#status-responses).
Keyring runs your action as one of its own flows, so it may change the protected `password` attribute, and only that: changing `email` there still throws. The action must save a new password or throw a `ValidationException`; returning without saving throws a `LogicException`, since everything that follows assumes the password changed. It runs holding the user's row, and the save only goes ahead while the session is still signed in and the stored password is still the one `current_password` was checked against: a change that a reset, or a change from another session, overtook is refused, with the reset's password left in place. Your action's validation and hashing run in that transaction, while the row is held, so anything else it does (an event, a queued email) happens before the save commits, and on PostgreSQL a query error it catches leaves the save undone. A sign in that rehashes the same password at that moment makes the change fail as a wrong current password, and sending it again works. If your own code calls `PasswordChanges::change()`, don't call it inside a transaction of yours: the lock would then be held through what comes after the save, which takes other rows. Afterwards Keyring regenerates the session ID, destroying the old one, cancels any pending email change, ends any reset links still outstanding, stops trusting the user's devices, including this one, and starts the account's sign-in limits over as a reset does, so a password that too many wrong guesses had got refused works again. With `sign_out_others` on, it also revokes every other session and changes the "remember me" token. The response is the `password-updated` [status response](sign-in-flow.md#status-responses).

## Requiring a Password Change

Expand Down Expand Up @@ -251,7 +251,7 @@ The check runs in `Keyring\Http\Middleware\RequirePasswordChange`, which Keyring
- breached passwords rejected, in production by default. Laravel's check lets a password through when Have I Been Pwned can't be reached; set [`passwords.refuse_unchecked`](configuration.md#passwords) to refuse it instead,
- the most common passwords rejected always, whatever their case and with or without spaces around them, from a list bundled with Keyring: the 10,000 most common of 8 characters or more and the 3,000 most common of 15 or more, 13,052 in all, taken from SecLists (MIT licensed). `resources/passwords/README.md` in the package records the exact source,
- no passwords made up of [context-specific words](#context-specific-words): the site's name, the words you list, and the user's name, email username and email domain,
- with bcrypt, Laravel's default, passwords over 72 bytes are rejected, because bcrypt silently ignores the rest. That's 72 plain characters but as few as 18 emoji, so 64 characters don't always fit. Set `HASH_DRIVER=argon2id` to accept every password up to `max`, which is what OWASP ASVS 5.0.0 (6.2.9) needs (see [Passwords](configuration.md#passwords)),
- with bcrypt, Laravel's default, passwords over 72 bytes are rejected, because bcrypt silently ignores the rest, and so are passwords with a NUL byte, which bcrypt can't hash at all. That's 72 plain characters but as few as 18 emoji, so 64 characters don't always fit. Set `HASH_DRIVER=argon2id` to accept every password up to `max`, which is what OWASP ASVS 5.0.0 (6.2.9) needs (see [Passwords](configuration.md#passwords)),
- and `confirmed`, so the request needs `password_confirmation`.

Passwords may hold any Unicode characters, and Keyring puts each one in Unicode's NFC form before it's measured, hashed or checked, as NIST SP 800-63B-4 recommends (Sec. 3.1.1.2). The same "é" is one code point from some keyboards and two from others, and without this a password set on one device could fail on another. The rules above count what will be hashed: a character is one code point of the NFC form. Keyring's routes do this for the input they hand your actions (`password`, `password_confirmation` and `current_password`) and for every password they check. If your own code sets a password some other way, such as a seeder, an admin tool or a route of your own, pass it through `PasswordRules::normalize()` first:
Expand Down
Loading