NAME

Data::Password::zxcvbn::Match::Dictionary - match class for words in passwords

VERSION

version 1.0.3

DESCRIPTION

This class represents the guess that a certain substring of a password can be guessed by going through a dictionary.

ATTRIBUTES

reversed

Boolean, true if the token appears to be a dictionary word that's been reversed (i.e. last letter first)

substitutions

Hashref representing the characters that need to be substituted to make the token match a dictionary work (e.g. if the token is s!mpl3, this hash would be { '!' => 'i', '3' => 'e' }).

rank

Number, indicating how common the dictionary word is. 1 means "most common".

dictionary_name

String, the name of the dictionary that the word was found in. Usually one of:

  • english_wikipedia

    words extracted from a dump of the English edition of Wikipedia

  • male_names, female_names, surnames

    common names from the 1990 US census

  • passwords

    most common passwords, extracted from the "xato" password dump

  • us_tv_and_film

    words from a 2006 Wiktionary word frequency study over American television and movies

METHODS

l33t

Returns true if the token had any "substitutions" (i.e. it was written in "l33t-speak")

make

  my @matches = @{ Data::Password::zxcvbn::Match::Dictionary->make(
    $password,
    { # these are the defaults
      ranked_dictionaries => \%Data::Password::zxcvbn::RankedDictionaries::ranked_dictionaries,
      l33t_table => \%Data::Password::zxcvbn::Match::Dictionary::l33t_table,
    },
  ) };

Scans the $password for substrings that match words in the ranked_dictionaries, possibly reversed, possibly with substitutions from the l33t_table.

The ranked_dictionaries should look like:

  { some_dictionary_name => { 'word' => 156, 'another' => 13, ... },
    ... }

(i.e. a hash of dictionaries, each mapping words to their frequency rank) and the l33t_table should look like:

  { a => [ '4', '@' ], ... }

(i.e. a hash mapping characters to arrays of other characters)

estimate_guesses

The number of guesses is the product of the rank of the word, how many case combinations match it, how many substitutions were used, doubled if the token is reversed.

does_word_start_upper

does_word_end_upper

is_word_all_not_upper

is_word_all_not_lower

is_word_all_upper

  if ($self->does_word_start_upper($word)) { ... }

These are mainly for sub-classes, to use in "feedback_warning" and "feedback_suggestions".

feedback_warning

feedback_suggestions

This class suggests not using common words or passwords, especially on their own. It also suggests that capitalisation, "special characters" substitutions, and writing things backwards are not very useful.

fields_for_json

The JSON serialisation for matches of this class will contain token i j guesses guesses_log10 dictionary_name reversed rank substitutions.

AUTHOR

Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by BroadBean UK, a CareerBuilder Company.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.