You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 23, 2021. It is now read-only.
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.
8
23
9
-
This package provides a Laravel validation rule that can be used to check a password
10
-
against TroyHunt's [Pwned Passwords (haveibeenpwned.com)](https://haveibeenpwned.com/Passwords),
11
-
a database containing 517,238,891 real world passwords previously exposed in data breaches.
24
+
### How it works
12
25
13
-
By using this validation rule, you can prevent re-use of passwords that are unsuitable for ongoing usage,
14
-
resulting in a more secure application, as your users will have a much lower risk of having their accounts taken over.
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:
15
27
16
-
##### How it works
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.
17
32
18
-
In order to protect the value of the source password being searched for, Pwned Passwords implements a [k-Anonymity model](https://en.wikipedia.org/wiki/K-anonymity) that allows a password to be searched for by partial hash.
19
-
This works by hashing the source password with SHA-1, and only sending the first 5 characters of that hash to the API.
20
-
By checking whether the rest of the SHA-1 hash occurs within the output, we can verify both whether the password was pwned previously, and how frequently.
33
+
This will then tell us whether a password was breached, and if so, how frequent.
21
34
22
35
## Installation
23
36
@@ -48,16 +61,16 @@ protected function validator(array $data)
48
61
}
49
62
```
50
63
51
-
You can also relax the rule, allowing passwords that have been pwned multiple times.
52
-
In the example below, passwords that have been pwned between 0 and 4 times are allowed:
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:
Of course, you can also use a Rule object instead:
73
+
Alternatively, you can also achieve the same using a Rule object:
61
74
62
75
```php
63
76
use Ubient\PwnedPasswords\Rules\Pwned;
@@ -68,8 +81,7 @@ $request->validate([
68
81
```
69
82
70
83
#### Handling Lookup Errors
71
-
When the Pwned 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.
72
-
While this 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.
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.
73
85
74
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,
75
87
you may create your own implementation of the [LookupErrorHandler](src/Contracts/LookupErrorHandler.php) and overwrite the default binding in your application:
0 commit comments