.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Password::zxcvbn::Match::Dictionary 3pm"
.TH Data::Password::zxcvbn::Match::Dictionary 3pm "2023-04-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Password::zxcvbn::Match::Dictionary \- match class for words in passwords
.SH "VERSION"
.IX Header "VERSION"
version 1.1.2
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents the guess that a certain substring of a password
can be guessed by going through a dictionary.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.ie n .SS """reversed"""
.el .SS "\f(CWreversed\fP"
.IX Subsection "reversed"
Boolean, true if the token appears to be a dictionary word that's been
reversed (i.e. last letter first)
.ie n .SS """substitutions"""
.el .SS "\f(CWsubstitutions\fP"
.IX Subsection "substitutions"
Hashref representing the characters that need to be substituted to
make the token match a dictionary work (e.g. if the token is
\&\f(CW\*(C`s!mpl3\*(C'\fR, this hash would be \f(CW\*(C`{ \*(Aq!\*(Aq => \*(Aqi\*(Aq, \*(Aq3\*(Aq => \*(Aqe\*(Aq }\*(C'\fR).
.ie n .SS """rank"""
.el .SS "\f(CWrank\fP"
.IX Subsection "rank"
Number, indicating how common the dictionary word is. 1 means \*(L"most
common\*(R".
.ie n .SS """dictionary_name"""
.el .SS "\f(CWdictionary_name\fP"
.IX Subsection "dictionary_name"
String, the name of the dictionary that the word was found in. Usually one of:
.IP "\(bu" 4
\&\f(CW\*(C`english_wikipedia\*(C'\fR
.Sp
words extracted from a dump of the English edition of Wikipedia
.IP "\(bu" 4
\&\f(CW\*(C`male_names\*(C'\fR, \f(CW\*(C`female_names\*(C'\fR, \f(CW\*(C`surnames\*(C'\fR
.Sp
common names from the 1990 \s-1US\s0 census
.IP "\(bu" 4
\&\f(CW\*(C`passwords\*(C'\fR
.Sp
most common passwords, extracted from the \*(L"xato\*(R" password dump
.IP "\(bu" 4
\&\f(CW\*(C`us_tv_and_film\*(C'\fR
.Sp
words from a 2006 Wiktionary word frequency study over American
television and movies
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """l33t"""
.el .SS "\f(CWl33t\fP"
.IX Subsection "l33t"
Returns true if the token had any \*(L"substitutions\*(R" (i.e. it was
written in \*(L"l33t\-speak\*(R")
.ie n .SS """make"""
.el .SS "\f(CWmake\fP"
.IX Subsection "make"
.Vb 7
\&  my @matches = @{ Data::Password::zxcvbn::Match::Dictionary\->make(
\&    $password,
\&    { # these are the defaults
\&      ranked_dictionaries => \e%Data::Password::zxcvbn::RankedDictionaries::ranked_dictionaries,
\&      l33t_table => \e%Data::Password::zxcvbn::Match::Dictionary::l33t_table,
\&    },
\&  ) };
.Ve
.PP
Scans the \f(CW$password\fR for substrings that match words in the
\&\f(CW\*(C`ranked_dictionaries\*(C'\fR, possibly reversed, possibly with substitutions
from the \f(CW\*(C`l33t_table\*(C'\fR.
.PP
The \f(CW\*(C`ranked_dictionaries\*(C'\fR should look like:
.PP
.Vb 2
\&  { some_dictionary_name => { \*(Aqword\*(Aq => 156, \*(Aqanother\*(Aq => 13, ... },
\&    ... }
.Ve
.PP
(i.e. a hash of dictionaries, each mapping words to their frequency
rank) and the \f(CW\*(C`l33t_table\*(C'\fR should look like:
.PP
.Vb 1
\&  { a => [ \*(Aq4\*(Aq, \*(Aq@\*(Aq ], ... }
.Ve
.PP
(i.e. a hash mapping characters to arrays of other characters)
.ie n .SS """estimate_guesses"""
.el .SS "\f(CWestimate_guesses\fP"
.IX Subsection "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.
.ie n .SS """does_word_start_upper"""
.el .SS "\f(CWdoes_word_start_upper\fP"
.IX Subsection "does_word_start_upper"
.ie n .SS """does_word_end_upper"""
.el .SS "\f(CWdoes_word_end_upper\fP"
.IX Subsection "does_word_end_upper"
.ie n .SS """is_word_all_not_upper"""
.el .SS "\f(CWis_word_all_not_upper\fP"
.IX Subsection "is_word_all_not_upper"
.ie n .SS """is_word_all_not_lower"""
.el .SS "\f(CWis_word_all_not_lower\fP"
.IX Subsection "is_word_all_not_lower"
.ie n .SS """is_word_all_upper"""
.el .SS "\f(CWis_word_all_upper\fP"
.IX Subsection "is_word_all_upper"
.Vb 1
\&  if ($self\->does_word_start_upper($word)) { ... }
.Ve
.PP
These are mainly for sub-classes, to use in "\f(CW\*(C`feedback_warning\*(C'\fR" and "\f(CW\*(C`feedback_suggestions\*(C'\fR".
.ie n .SS """feedback_warning"""
.el .SS "\f(CWfeedback_warning\fP"
.IX Subsection "feedback_warning"
.ie n .SS """feedback_suggestions"""
.el .SS "\f(CWfeedback_suggestions\fP"
.IX Subsection "feedback_suggestions"
This class suggests not using common words or passwords, especially on
their own. It also suggests that capitalisation, \*(L"special characters\*(R"
substitutions, and writing things backwards are not very useful.
.ie n .SS """fields_for_json"""
.el .SS "\f(CWfields_for_json\fP"
.IX Subsection "fields_for_json"
The \s-1JSON\s0 serialisation for matches of this class will contain \f(CW\*(C`token
i j guesses guesses_log10 dictionary_name reversed rank
substitutions\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2022 by BroadBean \s-1UK,\s0 a CareerBuilder Company.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.