NAME

OpenXPKI::Server::API2::Plugin::Crypto::password_quality

COMMANDS

password_quality

Check if the given password passes certain quality checks.

Returns undef on sucessful validation or an ArrayRef with error messages of failed checks.

Parameters

"password" Str - the password to be validated (required).
"checks" ArrayRef - list of checks to be performed. Default: see below.
Available checks:

Default

"length" - Is it in the range of permitted lengths (default: 8 - 255)?
"common" - Is it not a known hacked password like "password" et similia?
"diffchars" - Does it contain enough different characters?
"sequence" - Is it a sequence like 12345, abcde, or qwertz?
"dict" - Is it not a (reversed or leet speech obfuscated) dictionary word?
"entropy" - Is the password entropy above a certain level?
The entropy score is calculated by first detecting how many different character groups are used (those groups are roughly based on blocks of Unicode's Basic Multilingual Plane).

The entropy is higher:

the more characters the password contains,
the less adjacent characters the password contains (i.e. "fghijkl"),
the more character groups the password contains,
the more characters a group has in total.

Legacy checks

"letters" - Does it contain letters?
"digits" - Does it contain digits?
"specials" - Does it contain non-word characters?
"mixedcase" - Does it contain both small and capital letters?
"groups" - Does it contain a certain number (default: 2) of different character groups?
"partsequence" - Does it not contain usual sequence like 12345, abcde, or qwertz (default sequence length to be checked is 5)?
"partdict" - Does it not contain a dictionary word?

To maintain backwards compatibility some legacy checks are enabled automatically depending on the presence of certain configuration parameters (see comments below).

Parameters - "length" check

"min_len" Int - minimum password length (default: 8)
"max_len" Int - maxmimum password length (default: 255).

Parameters - "dict" check

•: "dictionaries" ArrayRef - list of files where the first existing one is used for dictionary checks (default: /usr/dict/web2, /usr/dict/words, /usr/share/dict/words, /usr/share/dict/linux.words).

Parameters - "diffchars" check

•: "min_diff_chars" Int - minimum required different characters to avoid passwords like "000000000000ciao0000000" (default: 6).

Parameters - "entropy" check

•: "min_entropy" Int - minimum required entropy (default: 60).

Parameters - "groups" check

•: "min_different_char_groups" Int - amount of required different groups (default: 2). If specified also enables the "groups" check for backwards compatibility.
There are four groups: digits, small letters, capital letters, others. So "groups" may be set to a value between 1 and 4.

Parameters - "partsequence" check

•: "sequence_len" Int - length of the sequences that are searched for in the password (default: 5). If specified also enables the "partsequence" check for backwards compatibility.
E.g. a setting of "following: 4" will complain about passwords containing "abcd" or "1234" or "qwer".

Parameters - "partdict" check

•: "min_dict_len" Int - minimum length for dictionary words that are tested to occur in the password. (default: 4). If specified also enables the "partdict" check for backwards compatibility.

Example

    password_quality({
        password => 'abcdef!i_am_safe',
        checks => [ 'entropy', 'length', 'dict' ],
        min_len => 14,
        min_entropy => 80,
        dictionaries => [ '/usr/share/dict/words' ],
    })

Will result in

    [
        'I18N_OPENXPKI_UI_PASSWORD_QUALITY_LENGTH_TOO_SHORT'
        'I18N_OPENXPKI_UI_PASSWORD_QUALITY_INSUFFICIENT_ENTROPY',
    ]