Download the PHP package stadly/password-police without Composer

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:

1. When the password is set.
2. 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.