NAME

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

VERSION

       version 1.0.6

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) 2022 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.

perl v5.34.0                                2022-08Data::Password::zxcvbn::Match::Dictionary(3pm)