Ideal-password NPM

ideal-password

Password entropy test, loosely inspired by xkcd. Key features:

Detects most frequently used passwords and common l33t-ized and mix-case versions of these passwords. For example, password is equivalent to Pa55w0rD.
Detects uppercase, lowercase, special, emoji, and several non-latin character sets and gives credit for the number of character sets represented.
Detects repeated characters and excludes them. For example aaaaaaaaaaa gets the same score as a and passwordpassword and passwordPa55w0rd gets the same score as password.

Usage

To use this in code

npm install ideal-password

In your code, measure entropy with this.

const entropy = require('ideal-password');

entropy('HueyDeweyLouie');
/* Returns
    {
      "sets": [             // see section on token sets below
        "latin-capital",
        "latin-small" ],
      "length": 9,          // note this only counts *unique* tokens
      "entropy": 58.64573768438668,
                            // ranges from zero to infinity. For the purpose
                            // of bar charts, 128 is a good maximum for the
                            // scale
      "acceptable": false,  // standard for "acceptable" and "ideal" can change
      "ideal": false,       // or be configurable in future versions
      "legal": true         // all the tokens are acceptable.
    }
 */

config

In code this can be configured using the entropy.config() method. This takes key and a value, or an object with key/value pairs. Omitting the value (in the (string, value) form) resets that configuration to the default.

entropy.config('minAcceptable', 24);
entropy.config({minAcceptable: 24, minIdeal: 64});
entropy.config('minAcceptable'); // sets to default value

minAcceptable - (default: 64) the lowest entropy score considered acceptable. That is, in the return object, the lowest entropy that have acceptable == true.
minIdeal - (default: 96) the lowest entropy score considered ideal. If minIdeal is set lower that minAcceptable, it will be ignored and ideal will always be true when acceptable is true.
sets - (default: 'all') a string or an array of strings, each being either a token set name or an alias for a preset list of token set names. Currently supported aliases are 'all' and 'western'.

bad passwords

This module detects bad passwords from a list of common passwords. In some situations industry jargon may also emerge as easily guessable passwords. The addCommonPasswords method will automatically check for l33t and mixed case versions of passwords.

// pass new passwords as an array or as a individual parameters.
entropy.addCommonPasswords(['Blinky', 'Pinky', 'Inky', 'Clyde']);
// or
entropy.addCommonPasswords('Blinky', 'Pinky', 'Inky', 'Clyde');

entropy('clYd3');
/* Returns
  {
    sets: [ 'common-passwords' ],
    length: 1,
    entropy: 2.995732273553991,
    max_entropy_scale: 128,
    legal: true,
    acceptable: false,
    ideal: false
  }
 */

On the command line

% npm install -g ideal-password

% entropy HueyDeweyLouie
Entropy score for "HueyDeweyLouie": 58.64573768438668
  Unique characters : 9
  Token sets: latin-capital, latin-small
Password is not acceptable.

Forward Compatitibility Note

Only the interface will be considered in selecting sematic versions. That is, the minor number will be advanced if a method or endpoint is added, and the major number will be advanced if there is a breaking change. Any updates to the formula for calculating entropy, without interface changes, will be treated as a tiny fix.

Formula

This formula estimates the entropy by multiplying the number of characters by a weight for each of the token sets represented. Each unique character is only counted once. That is, 000 counts the same as 0, HueyDeweyLouie counts as HueyDwLoi.

token sets

A "token" is usualy a single character, but in the case of common passwords or complex emoji, a token is composed of multiple characters.

A "token set" is a type of token. These token sets are identified:

common-passwords e.g. Passw0rd. Treats entire common password as a single token, case- and l33t-insensitive, e.g. password and Pa55w0rD are treated as the same.
white-space All white space characters
number Arabic numerals
latin-small Unaccented lowercase Latin alphabet
latin-capital Unaccented uppercase Latin alphabet
latin-extended Includes Latin 1 Supplement, Latin Extended A, B, C, D, and E, IP Extensions, and Latin Extended Additional
special Includes !"#$%&'()*+,-./:;<=>?[\]^_`
greek-capital Unaccented uppercase Greek alphabet
greek-small Unaccented lowercase Greek alphabet
greek-extended Includes letters from Greek Extended. For performance, includes some unassigned code points within the Greek Extended range.
cyrillic-capital Unaccented uppercase Cyrillic alphabet
cyrillic-small Unaccented lowercase Cyrillic alphabet
cyrillic-extended Includes letters from Cyrillic Supplement, Cyrillic Extended A, B, and C, and Cyrillic letters not included in cyrillic-capital or lower-cyrillic
arabic Arabic alphabet
arabic-extended Includes characters from the Arabic Extended A block.
devangari
bengali
tamil
telagu
devangari
kannada
malayalam
thai
hiragana Japanese Hiragana characters
katakana Japanese Katakana characters
bopomofo Mandarin and Taiwanese phonetic symbols, includes characters from Bopomofo and Bopomofo Extended character sets.
hangul Korean Hangul characters
hanzi-common 100 most common Chinese characters, in both Traditional and Simplified Chinese. Note results will never include both common-hanzi and hanzi. If both types of characters exist, only one type will be selected.
hanzi Chinese characters.
emoji Complex emoji are treated as single characters

Each token set has a score that is loosely based on the log of the number possible characters in that set.

As noted earlier, these token sets can be updated in future versions, and updates will not be considered "enhancements" or "breaking changes" for the purpose of semantic versioning.

Examples

In our example HueyDeweyLouie, there are nine unique characters over two token sets. Each of those token sets adds ln(26) to the entropy score, so we come to a score of 58.6.

$ HueyDeweyLouie
Entropy score for "HueyDeweyLouie": 58.64573768438668
  Unique characters : 9
  Token sets: latin-capital, latin-small
Password is not acceptable.

If they were all in lowercase, hueydeweylouie, even though the number of unique characters is still the same (hueydwloi), the entropy is even worse.

$ entropy hueydeweylouie
Entropy score for "hueydeweylouie": 29.32286884219334
  Unique characters : 9
  Token sets: latin-small
Password is not acceptable.

Adding a special character adds a third token set, improving the score to 81.

$ entropy Huey#eweyLouie
Entropy score for "Huey#eweyLouie": 81.00989753247869
  Unique characters : 9
  Token sets: latin-capital, latin-small, special
Password is acceptable but not ideal.

If we change one letter to an emoji, Huey🦆eweyLouie, we up the score even more. This is because emoji have more weight than special characters.

$ entropy Huey🦆eweyLouie
Entropy score for "Huey🦆eweyLouie": 100.09226935827951
  Unique characters : 9
  Token sets: latin-capital, latin-small, emoji
Password is ideal.

Common passwords or passwords that contain common passwords are treated harshly. A password that resembles a common password, hell0hi, got a low score of only 19. Notice the length is 3 because the hello was treated as a single "character" of the set "common-password". Changing the o to a 0 did not help either. The hi at the end was treated as two Latin letters.

$ entropy hell0hi
Entropy score for "hell0hi": 18.761486434726418
  Unique characters : 3
  Token sets: common-passwords, latin-small
Password is not acceptable.

Change history

v2.4.0

Typescript bindings updated.

v2.3.1

npm audit fix to update vulnerable package dependencies

v2.3

Browser and typescript usability

v2.2

Added new configuration features to allow user-supplied common passwords. Added more character sets.

v2.1

The algorithm for detecting character ranges changed to allow for detecting even more character sets and finer-grained classification with little performance loss.

v2.0

Version 2.0 is a breaking change in that some vocabulary will change for semantic accuracy and to more closely match Unicode Consortiums's use of language:

roman becomes latin
upper-roman becomes latin-capital
lower-roman becomes latin-small
extended-roman becomes latin-extended
upper-greek becomes greek-capital
lower-greek becomes greek-small
extended-greek becomes greek-extended
upper-cyrillic becomes cyrillic-capital
lower-cyrillic becomes cyrillic-small
extended-cyrillic becomes cyrillic-extended
common-hanzi becomes hanzi-common

However common-passwords will remain as common-passwords

Also "classes" become "sets" and most "characters" become "tokens". The output object also changed in that now classNames are sets.

v1.3.2

Documentation updates

v1.3.1

Added accented characters sets for Roman, Greek, and Cyrillic
Hanzi classes cancel, so mixing common and less-common Chinese characters will not result in a higher score than using only less-common characters