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

v1.3

• Added configuratability for character sets and acceptable/ideal thresholds

v1.2.1

• Added a Hangul (Korean) character class

v1.2

• "common passwords" -- treats common passwords as an entropy class, reducing the entropy of password that contains one of the common ones

v1.1

• test automation
• bug fixes working with utf16 high/low surrogates. This affects emoji processing.