.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 3pm"
.TH Data::Password::zxcvbn::Match 3pm "2020-07-13" "perl v5.30.3" "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 \- role for match objects
.SH "VERSION"
.IX Header "VERSION"
version 1.0.4
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  package My::Password::Match::Something;
\&  use Moo;
\&  with \*(AqData::Password::zxcvbn::Match\*(Aq;
\&
\&  has some_info => (is=>\*(Aqro\*(Aq);
\&
\&  sub make {
\&    my ($class, $password) = @_;
\&    return [ $class\->new({
\&      token => some_substring_of($password),
\&      i => position_of_first_char($token,$password),
\&      j => position_of_last_char($token,$password),
\&      some_info => whatever_needed(),
\&    }) ];
\&  }
\&
\&  sub estimate_guesses {
\&    my ($self) = @_;
\&    return $self\->some_complexity_estimate();
\&  }
\&
\&  sub feedback_warning { \*(Aqthis is a bad idea\*(Aq }
\&  sub feedback_suggestions { return [ \*(Aqdo something else\*(Aq ] }
\&
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
zxcvbn estimates the strength of a password by guessing which way a
generic password cracker would produce it, and then guessing after how
many tries it would produce it.
.PP
This role provides the basic behaviour and interface for the classes
that implement that guessing.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.ie n .SS """token"""
.el .SS "\f(CWtoken\fP"
.IX Subsection "token"
Required string: the portion of the password that this object
matches. For example, if your class represents \*(L"sequences of digits\*(R",
an instance made from the password \f(CW\*(C`abc1234def\*(C'\fR would have
\&\f(CW\*(C`token => \*(Aq1234\*(Aq\*(C'\fR.
.ie n .SS """i"", ""j"""
.el .SS "\f(CWi\fP, \f(CWj\fP"
.IX Subsection "i, j"
Required integers: the indices of the first and last character of
\&\*(L"token\*(R" in the password. For the example above, we would have \f(CW\*(C`i
=> 3, j => 6\*(C'\fR.
.ie n .SS """guesses"""
.el .SS "\f(CWguesses\fP"
.IX Subsection "guesses"
The estimated number of attempts that a generic password cracker would
need to guess the particular \*(L"token\*(R". The value for this attribute
is generated on demand by calling "\f(CW\*(C`estimate_guesses\*(C'\fR".
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
.ie n .SS """make"""
.el .SS "\f(CWmake\fP"
.IX Subsection "make"
.Vb 4
\&  sub make {
\&    my ($class, $password) = @_;
\&    return [ $class\->new(\e%something), ... ];
\&  }
.Ve
.PP
This factory method should return a \fIsorted\fR arrayref of instances,
one for each substring of the \f(CW$password\fR that could be generated /
guessed with the logic that your class represents.
.ie n .SS """estimate_guesses"""
.el .SS "\f(CWestimate_guesses\fP"
.IX Subsection "estimate_guesses"
.Vb 4
\&  sub estimate_guesses {
\&    my ($self) = @_;
\&    return $self\->some_complexity_estimate();
\&  }
.Ve
.PP
This method should return an integer, representing an estimate of the
number of attempts that a generic password cracker would need to guess
the particular \*(L"token\*(R" \fIwithin the logic that your class
represents\fR. For example, if your class represents \*(L"sequences of
digits\*(R", you could hypothesise that the cracker would go in order from
1, so you'd write:
.PP
.Vb 1
\&  sub estimate_guesses { return 0 + shift\->token }
.Ve
.ie n .SS """feedback_warning"""
.el .SS "\f(CWfeedback_warning\fP"
.IX Subsection "feedback_warning"
This method should return a string (possibly empty), or an arrayref
\&\f(CW\*(C`[$string,@values]\*(C'\fR suitable for localisation. The returned value
should explain what's wrong, e.g. 'this is a top\-10 common password'.
.ie n .SS """feedback_suggestions"""
.el .SS "\f(CWfeedback_suggestions\fP"
.IX Subsection "feedback_suggestions"
This method should return a possibly-empty array of suggestions to
help choose a less guessable password. e.g. 'Add another word or two';
again, elements can be strings or arrayrefs for localisation.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """compare"""
.el .SS "\f(CWcompare\fP"
.IX Subsection "compare"
.Vb 2
\&  $match1 <=> $match2
\&  $match1 cmp $match2
.Ve
.PP
The comparison operators are overloaded to sort by "\f(CW\*(C`i\*(C'\fR" and
"\f(CW\*(C`j\*(C'\fR", so a sorted list of matches will cover the password from
left to right.
.ie n .SS """guesses_log10"""
.el .SS "\f(CWguesses_log10\fP"
.IX Subsection "guesses_log10"
The logarithm in base 10 of "\f(CW\*(C`guesses\*(C'\fR".
.ie n .SS """guesses_for_password"""
.el .SS "\f(CWguesses_for_password\fP"
.IX Subsection "guesses_for_password"
.Vb 1
\&  my $guesses = $match\->guesses_for_password($password);
.Ve
.PP
This method will return the same value as "\f(CW\*(C`guesses\*(C'\fR", or some
minimum number of guesses, whichever is higher.
.PP
This is to make sure that all match have a measurable impact on the
estimation of the total complexity.
.ie n .SS """get_feedback"""
.el .SS "\f(CWget_feedback\fP"
.IX Subsection "get_feedback"
.Vb 1
\&  my %feedback = %{ $match\->get_feedback($is_sole_match) };
.Ve
.PP
Returns a hashref, with verbal feedback to help choose better
passwords. The hash contains:
.IP "\(bu" 4
\&\f(CW\*(C`warning\*(C'\fR
.Sp
string (or arrayref for localisation), produced by calling "\f(CW\*(C`feedback_warning\*(C'\fR"
.IP "\(bu" 4
\&\f(CW\*(C`suggestions\*(C'\fR
.Sp
arrayref of strings (or arrayrefs for localisation), produced by
calling "\f(CW\*(C`feedback_suggestions\*(C'\fR".
.ie n .SS """TO_JSON"""
.el .SS "\f(CWTO_JSON\fP"
.IX Subsection "TO_JSON"
.ie n .SS """fields_for_json"""
.el .SS "\f(CWfields_for_json\fP"
.IX Subsection "fields_for_json"
Matches can be serialised to \s-1JSON.\s0 The serialisation will be a
dictionary with all the fields returned by "\f(CW\*(C`fields_for_json\*(C'\fR". By default, it will contain \f(CW\*(C`token i j guesses guesses_log10\*(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) 2018 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.