|
18 | 18 |
|
19 | 19 | # Pwned Passwords
|
20 | 20 |
|
21 |
| -This package provides a validation rule that allows you to prevent or limit the re-use of passwords that are known to be unsafe for ongoing usage. |
22 |
| -The result is a more secure application, as your users will have a much lower risk of having their accounts taken over. |
| 21 | +This package is no longer maintained, as it's features have been absorbed into [laravel/framework](https://github.com/laravel/framework/pull/36960) v8.x. |
23 | 22 |
|
24 |
| -### How it works |
25 |
| - |
26 |
| -Internally, the validation rule uses what is known as a [k-Anonymity model](https://en.wikipedia.org/wiki/K-anonymity) that allows for the password to be looked up without giving up the user's privacy or security: |
27 |
| - |
28 |
| -- First, we hash the password using SHA-1 |
29 |
| -- Next, it looks up the first 5 characters of this hash against TroyHunt's [Pwned Passwords (haveibeenpwned.com)](https://haveibeenpwned.com/Passwords) API. |
30 |
| -- The API then responds with a list _suffixes_ to these first 5 characters that we are looking up. |
31 |
| -- Finally, we search through the list, checking whether the suffix of our hashed password matches any of the entries. |
32 |
| - |
33 |
| -This will then tell us whether a password was breached, and if so, how frequent. |
34 |
| - |
35 |
| -## Installation |
36 |
| - |
37 |
| -You can install the package via composer: |
38 |
| - |
39 |
| -```bash |
40 |
| -composer require ubient/laravel-pwned-passwords |
41 |
| -``` |
42 |
| - |
43 |
| -## Usage |
44 |
| - |
45 |
| -Here's a few short examples of what you can do: |
46 |
| - |
47 |
| -```php |
48 |
| -/** |
49 |
| - * Get a validator for an incoming registration request. |
50 |
| - * |
51 |
| - * @param array $data |
52 |
| - * @return \Illuminate\Contracts\Validation\Validator |
53 |
| - */ |
54 |
| -protected function validator(array $data) |
55 |
| -{ |
56 |
| - return Validator::make($data, [ |
57 |
| - 'name' => 'required|string|max:255', |
58 |
| - 'email' => 'required|string|email|max:255|unique:users', |
59 |
| - 'password' => 'required|string|min:6|confirmed|pwned', |
60 |
| - ]); |
61 |
| -} |
62 |
| -``` |
63 |
| - |
64 |
| -It is also possible to relax the rule, allowing passwords that have been breached multiple times. |
65 |
| -In the following example, passwords that have been pwned between 0 and 4 times are allowed: |
66 |
| - |
67 |
| -```php |
68 |
| -$request->validate([ |
69 |
| - 'password' => 'required|string|min:6|confirmed|pwned:5', |
70 |
| -]); |
71 |
| -``` |
72 |
| - |
73 |
| -Alternatively, you can also achieve the same using a Rule object: |
74 |
| - |
75 |
| -```php |
76 |
| -use Ubient\PwnedPasswords\Rules\Pwned; |
77 |
| - |
78 |
| -$request->validate([ |
79 |
| - 'password' => ['required', 'string', 'min:6', 'confirmed', new Pwned(5)], |
80 |
| -]); |
81 |
| -``` |
82 |
| - |
83 |
| -#### Handling Lookup Errors |
84 |
| -When the [Pwned Passwords](https://haveibeenpwned.com/Passwords) API cannot be queried, the default behavior is to accept the password as non-pwned and to send a warning message to the log. While this by itself doesn't add much value, it does allow you to be aware of when a pwned password was allowed, and to potentially manually act on this. |
85 |
| - |
86 |
| -If you would like to automatically do something else based on this lookup error (such as marking the request as potentially pwned), or want to decline the password instead, |
87 |
| -you may create your own implementation of the [LookupErrorHandler](src/Contracts/LookupErrorHandler.php) and overwrite the default binding in your application: |
88 |
| - |
89 |
| -```php |
90 |
| -use Ubient\PwnedPasswords\Contracts\LookupErrorHandler; |
91 |
| - |
92 |
| -$this->app->bind(LookupErrorHandler::class, MyCustomErrorHandler::class); |
93 |
| -``` |
94 |
| - |
95 |
| -#### Overriding localization |
96 |
| -If following the [Laravel Docs](https://laravel.com/docs/master/localization#overriding-package-language-files) to override the validation message provided by this package you'll need to use the `PwnedPasswords` namespace for the file path. |
97 |
| - |
98 |
| -To override the validation message provided by this package, place your file at `resources/lang/vendor/PwnedPasswords/en/validation.php`. |
99 |
| - |
100 |
| -## Testing |
101 |
| - |
102 |
| -``` bash |
103 |
| -composer test |
104 |
| -``` |
105 |
| - |
106 |
| -## Changelog |
107 |
| - |
108 |
| -Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. |
109 |
| - |
110 |
| -## Contributing |
111 |
| - |
112 |
| -Please see [CONTRIBUTING](CONTRIBUTING.md) for details. |
113 |
| - |
114 |
| -## Security |
115 |
| - |
116 |
| -If you discover any security related issues, please email [email protected] instead of using the issue tracker. |
117 |
| - |
118 |
| -## License |
119 |
| - |
120 |
| -The MIT License (MIT). Please see [License File](LICENSE.md) for more information. |
| 23 | +While this package will remain available for the forseeable future, **this package WILL NOT be receiving any further (security) updates going forward**, making the upgrade to [laravel/framework 8.39.0](https://github.com/laravel/framework/releases/tag/v8.39.0) and usage of that implementation highly recommended. |
0 commit comments