.\" 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 3pm"
.TH Data::Password::zxcvbn 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 \- Dropbox's password estimation logic
.SH "VERSION"
.IX Header "VERSION"
version 1.0.4
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::Password::zxcvbn qw(password_strength);
\&
\&  my $strength = password_strength($my_password);
\&  warn $strength\->{warning} if $strength\->{score} < 3;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a Perl port of Dropbox's password strength estimation library,
\&\f(CW\*(C`zxcvbn\*(C'\fR <https://github.com/dropbox/zxcvbn>.
.PP
The code layout has been reworked to be generally nicer (e.g. we use
classes instead of dispatch tables, all data structures are immutable)
and to pre-compute more (e.g. the dictionaries are completely
pre-built, instead of being partially computed at run time).
.PP
The code has been tested against the Python
port's <https://github.com/dwolfhub/zxcvbn-python>
\&\fIpassword_expected_value.json\fR test. When the dictionaries contain
exactly the same data (including some words that are loaded wrongly by
the Javascript and Python code, due to escaping issues), our results
are identical. With the dictionaries as provided in this distribution,
the results (estimated number of guesses) are still within 1%.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS """password_strength"""
.el .SS "\f(CWpassword_strength\fP"
.IX Subsection "password_strength"
.Vb 1
\&  my $strength = password_strength($password);
.Ve
.PP
This is the main entry point for the library, and the only function
you usually care about.
.PP
It analyses the given string, finding the easiest way that a password
cracking algorithm would guess it, and reports on its findings.
.PP
\fIReturn value\fR
.IX Subsection "Return value"
.PP
The return value is a hashref, with these keys:
.IP "\(bu" 4
\&\f(CW\*(C`guesses\*(C'\fR
.Sp
estimated guesses needed to crack password
.IP "\(bu" 4
\&\f(CW\*(C`guesses_log10\*(C'\fR
.Sp
order of magnitude of \f(CW\*(C`guesses\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`crack_times_seconds\*(C'\fR
.Sp
hashref of back-of-the-envelope crack time estimations, in seconds,
based on a few scenarios:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`online_throttling_100_per_hour\*(C'\fR
.Sp
online attack on a service that rate-limits authentication attempts
.IP "\(bu" 4
\&\f(CW\*(C`online_no_throttling_10_per_second\*(C'\fR
.Sp
online attack on a service that doesn't rate-limit, or where an
attacker has outsmarted rate-limiting.
.IP "\(bu" 4
\&\f(CW\*(C`offline_slow_hashing_1e4_per_second\*(C'\fR
.Sp
offline attack. assumes multiple attackers, proper user-unique
salting, and a slow hash function with moderate work factor, such as
bcrypt, scrypt, \s-1PBKDF2.\s0
.IP "\(bu" 4
\&\f(CW\*(C`offline_fast_hashing_1e10_per_second\*(C'\fR
.Sp
offline attack with user-unique salting but a fast hash function like
\&\s-1SHA\-1, SHA\-256\s0 or \s-1MD5. A\s0 wide range of reasonable numbers anywhere
from one billion \- one trillion guesses per second, depending on
number of cores and machines; ball-parking at 10B/sec.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`crack_times_display\*(C'\fR
.Sp
same keys as \f(CW\*(C`crack_times_seconds\*(C'\fR, but more useful for display: the
values are arrayrefs \f(CW\*(C`["english string",$value]\*(C'\fR that can be passed
to I18N libraries like \f(CW\*(C`Locale::Maketext\*(C'\fR to get localised
versions with proper plurals
.IP "\(bu" 4
\&\f(CW\*(C`score\*(C'\fR
.Sp
Integer from 0\-4 (useful for implementing a strength bar):
.RS 4
.IP "\(bu" 4
\&\f(CW0\fR
.Sp
too guessable: risky password. (\f(CW\*(C`guesses < 10e3\*(C'\fR)
.IP "\(bu" 4
\&\f(CW1\fR
.Sp
very guessable: protection from throttled online attacks. (\f(CW\*(C`guesses
< 10e6\*(C'\fR)
.IP "\(bu" 4
\&\f(CW2\fR
.Sp
somewhat guessable: protection from un-throttled online attacks. (\f(CW\*(C`guesses < 10e8\*(C'\fR)
.IP "\(bu" 4
\&\f(CW3\fR
.Sp
safely un-guessable: moderate protection from offline slow-hash
scenario. (\f(CW\*(C`guesses < 10e10\*(C'\fR)
.IP "\(bu" 4
\&\f(CW4\fR
.Sp
very un-guessable: strong protection from offline slow-hash
scenario. (\f(CW\*(C`guesses >= 10e10\*(C'\fR)
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`feedback\*(C'\fR
.Sp
hashref, verbal feedback to help choose better passwords, contains
useful information when \f(CW\*(C`score <= 2\*(C'\fR:
.RS 4
.IP "\(bu" 4
\&\f(CW\*(C`warning\*(C'\fR
.Sp
a string (sometimes empty), or an arrayref \f(CW\*(C`[$string,@values]\*(C'\fR
suitable for localisation. Explains what's wrong, e.g. 'this is a
top\-10 common password'.
.IP "\(bu" 4
\&\f(CW\*(C`suggestions\*(C'\fR
.Sp
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.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW\*(C`matches\*(C'\fR
.Sp
the list of patterns that zxcvbn based the guess calculation on; this
is rarely useful to show to users
.PP
All the objects in the returned value can be serialised to \s-1JSON,\s0 if
you set \f(CW\*(C`convert_blessed\*(C'\fR or equivalent in your \s-1JSON\s0 library.
.PP
\fIOptions\fR
.IX Subsection "Options"
.PP
.Vb 1
\&  my $strength = password_strength($password,\e%options);
.Ve
.PP
You can pass in several options to customise the behaviour of this
function. From most-frequently useful:
.IP "\(bu" 4
\&\f(CW\*(C`user_input\*(C'\fR
.Sp
the most useful option: a hashref of field names and values that
should be considered \*(L"obvious guesses\*(R", e.g. account name, user's real
name, company name, &c. (see \f(CW\*(C`Data::Password::zxcvbn::Match::UserInput\*(C'\fR)
.IP "\(bu" 4
\&\f(CW\*(C`max_score_for_feedback\*(C'\fR
.Sp
the maximum "\f(CW\*(C`score\*(C'\fR" above which no feedback will be provided,
defaults to 2; provide a higher value if you want feedback even on
strong passwords
.IP "\(bu" 4
\&\f(CW\*(C`modules\*(C'\fR
.Sp
arrayref of module names to use instead of the built-in
\&\f(CW\*(C`Data::Password::zxcvbn::Match::*\*(C'\fR classes; if you want to \fIadd\fR a
module, you still have to list all the built-ins in this array; \f(CW\*(C`Data::Password::zxcvbn::Match::BruteForce\*(C'\fR is special, and if
included here, it will be ignored
.IP "\(bu" 4
\&\f(CW\*(C`match_list_module\*(C'\fR
.Sp
module name to use instead of \f(CW\*(C`Data::Password::zxcvbn::MatchList\*(C'\fR to run all the computations; the module should really be a subclass
of that default one, with maybe some customised messages
.IP "\(bu" 4
\&\f(CW\*(C`ranked_dictionaries\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`l33t_table\*(C'\fR
.Sp
dictionaries and transliteration table, see \f(CW\*(C`Data::Password::zxcvbn::Match::Dictionary\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`graphs\*(C'\fR
.Sp
adjacency graphs for keyboard-related spatial guesses, see \f(CW\*(C`Data::Password::zxcvbn::Match::Spatial\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`regexes\*(C'\fR
.Sp
which regexes to use, see \f(CW\*(C`Data::Password::zxcvbn::Match::Regex\*(C'\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
the original implementation by Dropbox <https://github.com/dropbox/zxcvbn>
.IP "\(bu" 4
the Python port <https://github.com/dwolfhub/zxcvbn-python>
.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.