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
4 changes: 3 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,9 @@ RateLimiter::for('keyring', fn (Request $request) => Limit::perMinute(10)

`GET /login/{factor}/options` uses its own limiter, `keyring-login-options`, which allows 60 requests a minute per IP address. Login pages fetch the options on every load for passkey autofill, and when the limit is hit autofill stops offering passkeys until the next minute. Define the same limiter to change it.

`TooManyAttempts` is what Keyring's own two limiters answer with: Laravel's usual `429`, after dispatching `Keyring\Events\RateLimited`, which the security log records as [`rate_limited`](security-log-and-emails.md#entry-types). Laravel has no event of its own for a refused request, so a limiter you define without that `response()` still limits and writes nothing to the log.
The pages that emailed links open (confirming or undoing an email change, verifying an address, reporting a device) only show a button, so they use a third limiter, `keyring-pages`, at 60 requests a minute per IP address. Pressing the button is held to the `keyring` limit. Opening both ends of an email change, or reloading a page, doesn't use up the attempts the buttons get. Define the same limiter to change it.

`TooManyAttempts` is what Keyring's own three limiters answer with: Laravel's usual `429`, after dispatching `Keyring\Events\RateLimited`, which the security log records as [`rate_limited`](security-log-and-emails.md#entry-types). Laravel has no event of its own for a refused request, so a limiter you define without that `response()` still limits and writes nothing to the log.

## Messages and Translations

Expand Down
2 changes: 1 addition & 1 deletion docs/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ An assessment that ends in `Action::allow()` dispatches nothing. See [Risk](risk
| Event | When | Properties |
|---|---|---|
| `AccessRefused` | A signed-in user asked for an authenticator, device or session that isn't theirs, or that doesn't exist (both get the same 404, so the event doesn't tell them apart), or opened an email verification link made for another account. | `user`, `resource` (`authenticator`, `device`, `session` or `email_verification`), `id` (what was asked for, as it was sent; for a session, its handle) |
| `RateLimited` | The form limiter refused a request to one of Keyring's routes outside the sign-in limits: registration, a reset, a change, an emailed link, or passkey options. | `user` (whoever is signed in, otherwise null), `limiter` (`keyring` or `keyring-login-options`), `route` (its name), `retryAfter` (seconds) |
| `RateLimited` | The form limiter refused a request to one of Keyring's routes outside the sign-in limits: registration, a reset, a change, an emailed link or the page it opens, or passkey options. | `user` (whoever is signed in, otherwise null), `limiter` (`keyring`, `keyring-pages` or `keyring-login-options`), `route` (its name), `retryAfter` (seconds) |
| `EnrollmentRefused` | A sign-in method wasn't added. | `user`, `factor`, `reason`: `invalid` (the factor turned the confirmation down: a wrong code, a key it won't take) or `not_allowed` (the account may not add one yet) |
| `AuthenticatorRemovalRefused` | A sign-in method was kept, because removing it would have left the user unable to sign in the way their policy requires. | `user`, `authenticator` |
| `LinkRefused` | An emailed link was refused: a change that doesn't exist, a wrong or ended token, or a signature that didn't match or had expired. | `link`, `reason` (see [Refused Links](security-log-and-emails.md#refused-links)), `user` (whose email change it was, otherwise null) |
Expand Down
4 changes: 2 additions & 2 deletions docs/extending.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ This page lists them all, with where each is explained. [Recipes](recipes.md) ha
| Validation and status messages | The `keyring-lang` translation files | [Messages and Translations](configuration.md#messages-and-translations) |
| The route prefix, domain and middleware | `prefix`, `domain` and `middleware` | [Routes](configuration.md#routes) |
| The middleware on account changes | `changes_middleware` | [Account Changes and Enrollment](configuration.md#account-changes-and-enrollment) |
| The form rate limits | The `keyring` and `keyring-login-options` rate limiters | [Rate Limits](configuration.md#pending-logins-timebox-and-rate-limits) |
| The form rate limits | The `keyring`, `keyring-pages` and `keyring-login-options` rate limiters | [Rate Limits](configuration.md#pending-logins-timebox-and-rate-limits) |
| Who may sign in at all | `Keyring::allowSignInWhen()` | [Who May Sign In](sign-in-flow.md#who-may-sign-in) |
| Who may add a sign-in method | `Keyring::allowEnrollmentWhen()` | [Who May Enroll](authenticators.md#who-may-enroll) |
| Whether registration says when an address is taken | `registration.reveal_taken` | [Registration](sign-in-flow.md#registration) |
Expand Down Expand Up @@ -72,7 +72,7 @@ Set `routes` to `false` and call `Keyring::routes()` inside your own group to ch

A few things have no switch, because turning them off would quietly remove a protection:

- Plain `EmailCode::class` is refused. `EmailCode::asSecondFactor()` is the switch, and it says what you're accepting.
- Plain `EmailCode::class` is refused. `EmailCode::asExtraStep()` is the switch, and it says what you're accepting.
- A user can't remove their last way to sign in, and removing the last second factor takes the password, typed again and long enough to stand alone.
- An email change is confirmed from the new address, announced to the old one, and can be undone from there.
- Trusting a device takes a real second factor, and a confirm page opened without a step-up behind it never accepts recovery codes.
Expand Down
6 changes: 3 additions & 3 deletions docs/factors.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Removing a factor from the list doesn't delete anyone's authenticators. A user w
|---|---|---|---|---|---|
| `password` | `Password` | knowledge | yes | no | 40 |
| `totp` | `Totp` | possession | no | yes | 60 |
| `email-code` | `EmailCode::asSecondFactor()` | address (not a factor) | no | yes, one | 30 |
| `email-code` | `EmailCode::asExtraStep()` | address (not a factor) | no | yes, one | 30 |
| `recovery` | `RecoveryCodes` | possession | no | yes, one set | 0 |
| `passkey` | `WebAuthn::passkeys()` | possession, plus inherence when the user was verified | yes | yes | 100 |
| `security-key` | `WebAuthn::securityKeys()` | possession, plus inherence when the user was verified | no | yes | 90 |
Expand Down Expand Up @@ -122,13 +122,13 @@ The `otpauth://` URL and the QR code then say `algorithm=SHA256`, and enrolling
An eight digit code sent to the user's current email address. It's opt-in, because NIST SP 800-63B-4 doesn't accept email as an authenticator at any level (Sec. 3.1.3.1): whoever controls the inbox can also reset the password, so for a user with nothing else beside their password, the inbox is the whole account. Registering plain `EmailCode::class` throws an exception that says so. To accept that risk:

```php
Keyring::factors([Password::class, Totp::class, EmailCode::asSecondFactor()]);
Keyring::factors([Password::class, Totp::class, EmailCode::asExtraStep()]);
```

Codes are eight digits, last ten minutes and allow five wrong guesses. To change that:

```php
EmailCode::asSecondFactor(length: 6, expireAfter: '5m', maxGuesses: 3)
EmailCode::asExtraStep(length: 6, expireAfter: '5m', maxGuesses: 3)
```

Six digits is the shortest a code can be and ten minutes the longest it can last, the bounds OWASP ASVS 5.0.0 sets for codes sent out of band (requirements 6.5.4 and 6.5.5). Asking for less or for longer throws a `LogicException` on that line.
Expand Down
2 changes: 1 addition & 1 deletion docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ php artisan keyring:install --factor=totp --factor=passkeys --feature=registrati

`--factor` takes `totp`, `passkeys`, `security-keys` or `email-codes`. `--feature` takes `registration`, `reset-passwords`, `email-verification`, `update-passwords`, `manage-authenticators`, `devices`, `email-changes` or `security-log`, and replaces the defaults (`registration`, `reset-passwords`, `email-verification`, `update-passwords` and `security-log`), so list those too if you want them. An unknown value stops the command before it writes anything, and an unknown feature in `config/keyring.php` stops the app booting, rather than leaving that feature off. `--require-second-factor` and `--optional-second-factor` answer the second question; requiring one without a sign-in method that counts stops the command too. `--emails` and `--no-emails` say whether the provider registers the security notices about changes; the classes are published either way.

Pass `--force` to overwrite files that already exist; without it, existing files are skipped, and with `config/keyring.php` already there it doesn't ask which features to turn on. It's safe to run again: the migrations are only published once, so they're never added twice under new timestamps. Running it again on an older install adds any new actions, but leaves your provider alone, so register them there yourself. Until you do, the routes that need them fail with an exception that says which `Keyring::*Using()` call is missing.
Pass `--force` to overwrite files that already exist; without it, existing files are skipped, and with `config/keyring.php` already there it doesn't ask which features to turn on. It's safe to run again: a migration you already have is never added a second time under a new timestamp, and one a later version brought is added on its own. Running it again on an older install adds any new actions and notifications too, but leaves your provider alone, so register them there yourself. A new action's routes fail until you do, with an exception that says which `Keyring::*Using()` call is missing. A new notification is simply never sent: add its line to `Keyring::notifications()`, using the [list of emails](security-log-and-emails.md#security-emails) for the key.

If you're moving from Fortify, read [Upgrading From Fortify](upgrading-from-fortify.md) before migrating.

Expand Down
8 changes: 4 additions & 4 deletions docs/owasp-asvs.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Everything in Level 1, and:
7. **Write down** your list of words a password must not be made up of and put it in `passwords.context` ([6.1.2, 6.2.11](#v62-password-security)), your session timeouts and why you chose them ([7.1.1](#v71-session-management-documentation)), and how many sessions an account may have (100 unless you change `sessions.max`, the oldest ended first) ([7.1.2](#v71-session-management-documentation)).
8. **Decide who may run `php artisan keyring:sign-out`** ([7.4.5](#v74-session-termination)), and a process for someone who has lost their second factor and their recovery codes ([6.4.4](#v64-authentication-factor-lifecycle-and-recovery)).

Email codes count toward no assurance level: a password and an emailed code is an AAL1 session, in Keyring's levels as in NIST's, and doesn't pass `keyring:aal2` or `keyring.enrolled`. Level 3 rules them out altogether. Leave `EmailCode::asSecondFactor()` out unless you need it.
Email codes count toward no assurance level: a password and an emailed code is an AAL1 session, in Keyring's levels as in NIST's, and doesn't pass `keyring:aal2` or `keyring.enrolled`. Level 3 rules them out altogether. Leave `EmailCode::asExtraStep()` out unless you need it.

## Level 3

Expand Down Expand Up @@ -152,7 +152,7 @@ Everything in Level 2, and:

With `ifEnrolled()` a new user signs in with their password, and `keyring.enrolled:aal3` keeps them on your enrollment page until they've added a key; from then on they need it every time. Drop `ifEnrolled()` if you hand out keys before an account first signs in. See [Requiring Attestation](passkeys.md#requiring-attestation). Without attestation, "hardware" is only what the key says about itself.

2. **No email codes, and no SMS** ([6.3.6](#v63-general-authentication-security), [6.6.1](#v66-out-of-band-authentication-mechanisms)). Don't register `EmailCode::asSecondFactor()` or an SMS factor of your own. Recovery codes can't meet `aal3` either, so a lost key goes to your support process.
2. **No email codes, and no SMS** ([6.3.6](#v63-general-authentication-security), [6.6.1](#v66-out-of-band-authentication-mechanisms)). Don't register `EmailCode::asExtraStep()` or an SMS factor of your own. Recovery codes can't meet `aal3` either, so a lost key goes to your support process.
3. **Tell users about suspicious sign ins** ([6.3.5](#v63-general-authentication-security)). Turn on `Features::devices()`, which brings the `new_device` notice and the `NewDevice` and `InactiveAccount` signals in a new install; in an existing one, uncomment them in your `KeyringServiceProvider`. Keep the security log on. Then have your risk response notify for a sign in after a long quiet period or after several failures, as [Telling the User](risk.md#telling-the-user) shows: by itself each of those only asks for a second factor. For a sign in from an unusual place, bind a [locator](devices-and-sessions.md#locations) and add `NewCountry` or `ImpossibleTravel`.
4. **Keep the default registration** ([6.3.8](#v63-general-authentication-security)): `registration.reveal_taken` stays `false`.
5. **Ask again before your most sensitive operations** ([7.5.3](#v75-defenses-against-session-abuse)): `keyring:aal3` or `keyring.fresh:5m` on those routes. AAL3 lapses after 15 minutes idle or 12 hours.
Expand Down Expand Up @@ -198,7 +198,7 @@ Everything in Level 2, and:
| 6.3.3 Multi-factor authentication is required; a hardware factor at Level 3 | 2 | Needs setup | A default install has no second factor to require. Level 2: a second factor registered and `keyring.enrolled`, which the installer sets up when you pick one and answer yes to requiring it. Level 3: `Requirement::aal3()`, `keyring.enrolled:aal3` and `requireAttestation()`. See [Level 2](#level-2) and [Level 3](#level-3). Until a user enrolls they are signed in, and held at your enrollment page. `keyring.enrolled` checks the account, not the session: see "remember me" in [Level 2](#level-2). |
| 6.3.4 No undocumented pathways, and consistent strength across them | 2 | Met | Every proof runs one pipeline. Three things don't go through it: "remember me", which carries a session on at no level; registration with `registration.reveal_taken`, which signs the new user in on their password without asking the policy; and your own `Auth::login()`, registered at no level. Start a social login with [`Keyring::attempt()`](sign-in-flow.md#starting-a-sign-in-yourself) instead. |
| 6.3.5 Users are notified of suspicious authentication attempts | 3 | Partly | A default install emails `account_locked`, when the password or a passkey is refused until a reset (at the cap on failures in a row, or sooner with `limits.lock_after`; an ordinary lockout that lifts by itself emails nobody), and `suspicious_activity`, when what the risk signals find adds up to a level that notifies. It adds `second_factor_failed` once you pick a sign-in method besides the password, and `new_device` with `Features::devices()`. Left to you: a sign in after a long quiet period or after several failures is found (`InactiveAccount`, `SuccessAfterFailures`) but each alone only asks for a second factor, so have your response notify for them ([Telling the User](risk.md#telling-the-user)); and a sign in from an unusual place needs a [locator](devices-and-sessions.md#locations) and a location signal. See [Level 3](#level-3). Each kind is capped at five an hour per account. |
| 6.3.6 Email isn't an authentication factor | 3 | Met by default | Don't register `EmailCode::asSecondFactor()`. The factor throws without that explicit opt-in, and an emailed code never counts toward a level. |
| 6.3.6 Email isn't an authentication factor | 3 | Met by default | Don't register `EmailCode::asExtraStep()`. The factor throws without that explicit opt-in, and an emailed code never counts toward a level. |
| 6.3.7 Users are notified when authentication details change | 3 | Met by default | A default install mails a changed or reset password, a sign-in method added or removed, new recovery codes, a recovery code used and a changed email address, and an undone email change once `Features::emailChanges()` is on. Renaming a sign-in method or changing the default one sends nothing. An account whose address isn't verified is sent none of these, except the notice of the reset that proves it. A password your own code sets with `Keyring::withoutProtection()` is logged, not announced: dispatch `Keyring\Events\PasswordChanged` yourself if users should hear of it. Installing with `--no-emails`, or without the published provider, sends none, and nothing warns. |
| 6.3.8 Valid users can't be deduced from sign in, registration or forgot password | 3 | Met by default | All three answer the same for every address, in the same time. Keep `registration.reveal_taken` off: with it on, registration says when an address is taken, and the conformance check is skipped, not failed. A username of your own that must be unique will still say when it's taken, and mail that bounces is outside the request. See [Registration](sign-in-flow.md#without-revealing-who-has-an-account). |

Expand Down Expand Up @@ -309,7 +309,7 @@ ASVS's other chapters are about your whole application. These are the requiremen
| | | What it means for your app |
|---|---|---|
| 1.2.2 URLs are built with untrusted data encoded | Met | Server side, links are built from named routes. The browser package encodes every factor key and ID it puts in a path. A route you override with `configureRoutes()` is used as written, so [encode in yours](frontend.md#changing-routes). |
| 2.4.1 Anti-automation controls | Met by default | The [rate limits](security.md#rate-limiting), and the `keyring` and `keyring-login-options` limiters on the other forms. All are options, and you can redefine the limiters: only a password minimum under 8, a sent code under six digits or over ten minutes, a TOTP window over one step and an RSA floor under 2048 bits are refused. |
| 2.4.1 Anti-automation controls | Met by default | The [rate limits](security.md#rate-limiting), and the `keyring`, `keyring-pages` and `keyring-login-options` limiters on the other forms. All are options, and you can redefine the limiters: only a password minimum under 8, a sent code under six digits or over ten minutes, a TOTP window over one step and an RSA floor under 2048 bits are refused. |
| 2.4.2 Flows require realistic human timing (Level 3) | Yours | Keyring has no bot check and no minimum time on a form. Where a CAPTCHA or a challenge goes is in [Bot Checks](security.md#bot-checks). |
| 3.3.1, 3.3.3 `Secure` cookies with a `__Host-` or `__Secure-` prefix | Met by default | Keyring's two cookies, over HTTPS. A name you set yourself (`devices.cookie`, `sessions.remember_cookie`) is used as written, so the prefix is yours to add. Laravel's session cookie is yours to name and secure: see [Secure Cookies](security.md#secure-cookies). |
| 3.4.1 `Strict-Transport-Security` on every response | Yours | Keyring sends none: it would only cover its own routes. See [HTTPS and HSTS](security.md#https-and-hsts). |
Expand Down
2 changes: 1 addition & 1 deletion docs/policies.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Keyring works out an assurance level from what a user has proved in their sessio
| Proved | Level |
|---|---|
| A password | AAL1 |
| A password and an email code, with [`EmailCode::asSecondFactor()`](factors.md#email-codes) | AAL1: NIST doesn't accept email as an authenticator |
| A password and an email code, with [`EmailCode::asExtraStep()`](factors.md#email-codes) | AAL1: NIST doesn't accept email as an authenticator |
| A password and a TOTP or recovery code | AAL2 |
| A passkey that syncs (iCloud Keychain, Google Password Manager...) | AAL2 |
| A passkey or security key that stays on its device, added without attestation, alone or with a password | AAL2 |
Expand Down
Loading
Loading