Download the PHP package stadly/password-police without Composer
On this page you can find all versions of the php package stadly/password-police. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download stadly/password-police
More information about stadly/password-police
Files in stadly/password-police
Package password-police
Short Description Password policy enforcement made easy.
License MIT
Homepage https://github.com/Stadly/PasswordPolice
Informations about the package password-police
PasswordPolice
Password policy enforcement made easy.
Install
Via Composer
Usage
Rules
Password policy rules specify the password requirements, and are used to determine whether a password is in compliance with the policy or not.
Length
The length rule sets lower and upper limits to the password length.
Lower case letters
The lower case rule sets lower and upper limits to the number of lower case letters.
Upper case letters
The upper case rule sets lower and upper limits to the number of upper case letters.
Digits
The digit rule sets lower and upper limits to the number of digits.
Symbols
The symbol rule sets lower and upper limits to the number of symbols. The characters considered symbols are specified when creating the rule. Note that this rule counts the number of symbols, and not the number of distinct symbols. That Hello!!!
contains one symbol three times, while Hello!?&
contains three different symbols makes no difference—they both contain three symbols.
Have I Been Pwned
The Have I Been Pwned rule sets lower and upper limits to the number of times the password has been exposed in data breaches. This rule uses the Have I Been Pwned service. Passwords are never sent to the service. Instead k-Anonymity is used to make the solution secure.
Dictionary
The dictionary rule enforces that the password is not contained in a word list.
split the password into multiple words, so that the password SomeCombinedWords
would match a word list containing the word Combined
.
Word lists
The dictionary rule requires a word list. Currently, Pspell is the only available word list. Support for other word lists can easily be implemented.
Pspell
The pspell word list uses Pspell, which can be built into php.
lower case converter, the password PaSsWoRd
would match a word list containing the word password
.
Guessable data
The guessable data rule enforces that the password doesn’t contain data that can easily be guessed. Easily guessable data is specified when creating the rule. It is possible to specify additional easily guessable data for each password. This way the guessable data rule can both prevent general easily guessable data like the service name from being used in any password, and also prevent users from using personal easily guessable data like their own name or birthday in their password.
To specify easily guessable data for a password, the password must be a Password
object instead of a string
.
dictionary rule.
Date formatters
To check if a password contains an easily guessable date, the guessable data rule must know the different formats that a date can have. This is the job of the date formatters. Custom date formatters can easily be implemented. A default date formatter is used when no date formatter is sepcified for the guessable data rule.
No reuse
The no reuse rule prevents previously used passwords from being used again.
For the rule to know the previously used passwords, former passwords must be specified. To specify former passwords, the password must be a Password
object instead of a string.
Hash functions
Passwords should always be stored as secure hashes, making it impossible to determine the raw password from its stored representation. In order to check if a password matches a previously used password, the php password hashing algorithms. Support for other hash functions can easily be implemented.
Password hasher
The password hasher uses Password Hashing Functions, which is built into php. If you use password_hash
to store hashes of passwords, this is the right choice for the no reuse rule.
Change with interval
The change with interval rule sets lower and upper limits to how often a password can be changed. A lower limit on the time from one password change to the next prevents passwords from being changed too often. This may be useful combined with the no reuse rule enforcing that for example the 5 most recent passwords cannot be reused, since it prevents the user from just changing the password 5 times and then back to the original password. An upper limit on the time from one password change to the next enforces that passwords are changed on a regular basis.
For the rule to know when the password has been changed, former passwords must be specified. To specify former passwords, the password must be a Password
object instead of a string.
Not set in interval
The not set in interval rule enforces that the password was not set during the specified time period. This may be useful for example in the case of a data breach, after which all passwords should be changed, or for other security incidents, when only passwords set during the period of the security incident must be changed.
For the rule to know when the password was set, the current password must be specified as a former password. To specify former passwords, the password must be a Password
object instead of a string.
Conditional rule
The conditional rule is used to only conditionally apply another rule. The rule to apply conditionally, along with a condition function must be specified. The condition function should take a password (either string
or Password
object) as the only argument, and return true
or false
. If the condition function returns false, this rule does nothing. Otherwise, the specified rule is applied. This is useful for example to only apply the Have I Been Pwned rule periodically. For example, to check at most once a month whether a password has been included in a data breach, instead of checking it every time the password is used.
Formatters
Formatters are used to manipulate strings, and may be used in combination with the combined, so that the results of multiple formatters are combined into one (the formatters are run in parallel).
Converters
Converter formatters can convert characters in a string into other characters.
Capitalizer
The capitalizer converts the first character to upper case, and the rest to lower case.
Leetspeak decoder
The leetspeak decoder decodes character sequences that can be interpreted as leetspeak. All decoding combinations are included in the result, so formatting the string 1337
results in the strings 1337
, L337
, 1E37
, 13E7
, 133T
, LE37
, L3E7
, L33T
, 1EE7
, 1E3T
, 13ET
, LEE7
, LE3T
, L3ET
, 1EET
, LEET
.
Lower case converter
The lower case converter converts all characters to lower case.
Mixed case converter
The mixed case converter converts all characters to both lower case and upper case. All combinations are included in the result, so formatting the string fOo
results in the strings foo
, Foo
, fOo
, foO
, FOo
, FoO
, fOO
, FOO
.
Upper case converter
The upper case converter converts all characters to upper case.
Splitters
Splitter formatters can extract parts of a string.
Substring generator
The substring generator generates all substrings. A minimum and maximum length for the substrings can be specified. Substring shorter than the minimum or longer than the maximum are not included in the result. The result only includes unique strings.
Truncator
The truncator truncates strings to a maximum length.
Filters
Filter formatters can filter out certain strings.
Length filter
The length filter filters out strings that are shorter or longer than the limits.
Combiner
The formatter combiner combines the results from multiple formatters into one (the formatters are run in parallel). Unformatted strings are also included in the result by default, but can be excluded. The result only includes unique strings.
Chaining
Formatters can be chained so that the result of one formatter is fed into another formatter (the formatters are run in series).
Rule weights
All rules have an associated weight. The default weight is 1. By using weights, it is possible to differenciate between hard rules that cannot be circumvented, and rules that are merely intended as advice and may be ignored.
Rule weights when testing a rule or policy
When testing a rule or policy, an optional weight can be specified. Rules with lower weights than the testing weight are ignored.
Rule weights when validating a rule or policy
When validating a rule or policy, all rules are validated, regardless of their weight. Each validation error contains the weight of the broken rule, which can be used to ignore validation errors of low weight.
Constraints
In addition to specifying different weights to different rules, most rules can contain multiple constraints with different weights. This makes it possible to create rules with strict constraints having low weights and looser constrains with higher weights.
Constraint weights when testing a rule or policy
When testing a rule or policy, an optional weight can be specified. Rule constraints with lower weights than the testing weight are ignored.
Constraint weights when validating a rule or policy
When validating a rule or policy, all rule constraints are validated, regardless of their weight. Each validation error contains the weight of the unsatisfied rule constraint, which can be used to ignore validation errors of low weight.
Example usage of weight
With version 2 of the Have I Been Pwned service, the number of times a password appears in data breaches was introduced. When writing about the new release, Troy Hunt gave an example of how this number could be utilized:
Having visibility to the prevalence means, for example, you might outright block every password that’s appeared 100 times or more and force the user to choose another one (there are 1,858,690 of those in the data set), strongly recommend they choose a different password where it’s appeared between 20 and 99 times (there’s a further 9,985,150 of those), and merely flag the record if it’s in the source data less than 20 times.
Such a password policy can be implemented by creating 3 rule constraints with different weights:
When validating a password, the weight of the validation error can be used to determine which action to take:
Best practices for password policies
General guidelines for good password policies:
- Require passwords to be at least 8 characters long.
- Do not allow passwords that have been exposed in data breaches.
- Do not allow passwords that can be found in a dictionary.
- Do not allow passwords to include words that are easy to guess, such as the service name or the user’s name.
- Do not allow passwords with repetitive or sequential characters (e.g. “aaaaaa”, “1234”, “abcd”, or “qwerty”).
- Do not require combinations of symbols.
- Do not require passwords to be changed periodically.
You can read more about password policy recommendations in NIST SP 800-63B, section 5.1.1 and Appendix A.
When to validate passwords
There are two events in which a password can be validated agains a password policy:
- When the password is set.
- When the password is used.
Passwords should always be stored as secure hashes, making it impossible to determine the raw password from its stored representation. Therefore, the raw password is only available when it is being set or used, and hence the password can be validated only then. The only exception is password policy rules that do not need the password, such as the not set in interval rule.
It is recommended to validate passwords both when they are set and when they are used, but the rules to apply are usually different in the two cases.
Validating passwords that are being set
When the password is being set is the right time to validate the password format, such as change with interval with lower limit.
Validating passwords that are being used
When the password is being used, there is no need to validate the format of the password. Assuming that the password policy has not changed, the password will pass validation when it is used if it passed validation when it was set. When the password is used, the password only needs to be validated agains rules whose validation outcome can change without the password being changed. Such rules are for example not set in interval.
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
Contributing
Please see CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
- Magnar Ovedal Myrtveit
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of password-police with dependencies
http-interop/http-factory-discovery Version ^1.4
nesbot/carbon Version ^2.9
psr/http-client Version ^1.0
psr/http-factory Version ^1.0
stadly/php-date Version ^1.0
symfony/translation Version ^4.3.3
vanderlee/php-stable-sort-functions Version ^2.0.4