Data::Password::zxcvbn(3pm)

1Data::Password::zxcvbn(U3s)er Contributed Perl DocumentatDiaotna::Password::zxcvbn(3)
2
3
4

NAME

6       Data::Password::zxcvbn - Dropbox's password estimation logic
7

VERSION

9       version 1.1.2
10

SYNOPSIS

12         use Data::Password::zxcvbn qw(password_strength);
13
14         my $strength = password_strength($my_password);
15         warn $strength->{warning} if $strength->{score} < 3;
16

DESCRIPTION

18       This is a Perl port of Dropbox's password strength estimation library,
19       "zxcvbn" <https://github.com/dropbox/zxcvbn>.
20
21       The code layout has been reworked to be generally nicer (e.g. we use
22       classes instead of dispatch tables, all data structures are immutable)
23       and to pre-compute more (e.g. the dictionaries are completely pre-
24       built, instead of being partially computed at run time).
25
26       The code has been tested against the Python port's
27       <https://github.com/dwolfhub/zxcvbn-python>
28       password_expected_value.json test. When the dictionaries contain
29       exactly the same data (including some words that are loaded wrongly by
30       the Javascript and Python code, due to escaping issues), our results
31       are identical. With the dictionaries as provided in this distribution,
32       the results (estimated number of guesses) are still within 1%.
33

FUNCTIONS

35   "password_strength"
36         my $strength = password_strength($password);
37
38       This is the main entry point for the library, and the only function you
39       usually care about.
40
41       It analyses the given string, finding the easiest way that a password
42       cracking algorithm would guess it, and reports on its findings.
43
44       Return value
45
46       The return value is a hashref, with these keys:
47
48       •   "guesses"
49
50           estimated guesses needed to crack password
51
52       •   "guesses_log10"
53
54           order of magnitude of "guesses"
55
56       •   "crack_times_seconds"
57
58           hashref of back-of-the-envelope crack time estimations, in seconds,
59           based on a few scenarios:
60
61           •   "online_throttling_100_per_hour"
62
63               online attack on a service that rate-limits authentication
64               attempts
65
66           •   "online_no_throttling_10_per_second"
67
68               online attack on a service that doesn't rate-limit, or where an
69               attacker has outsmarted rate-limiting.
70
71           •   "offline_slow_hashing_1e4_per_second"
72
73               offline attack. assumes multiple attackers, proper user-unique
74               salting, and a slow hash function with moderate work factor,
75               such as bcrypt, scrypt, PBKDF2.
76
77           •   "offline_fast_hashing_1e10_per_second"
78
79               offline attack with user-unique salting but a fast hash
80               function like SHA-1, SHA-256 or MD5. A wide range of reasonable
81               numbers anywhere from one billion - one trillion guesses per
82               second, depending on number of cores and machines; ball-parking
83               at 10B/sec.
84
85       •   "crack_times_display"
86
87           same keys as "crack_times_seconds", but more useful for display:
88           the values are arrayrefs "["english string",$value]" that can be
89           passed to I18N libraries like "Locale::Maketext" to get localised
90           versions with proper plurals
91
92       •   "score"
93
94           Integer from 0-4 (useful for implementing a strength bar):
95
96           •   0
97
98               too guessable: risky password. ("guesses < 10e3")
99
100           •   1
101
102               very guessable: protection from throttled online attacks.
103               ("guesses < 10e6")
104
105           •   2
106
107               somewhat guessable: protection from un-throttled online
108               attacks. ("guesses < 10e8")
109
110           •   3
111
112               safely un-guessable: moderate protection from offline slow-hash
113               scenario. ("guesses < 10e10")
114
115           •   4
116
117               very un-guessable: strong protection from offline slow-hash
118               scenario. ("guesses >= 10e10")
119
120       •   "feedback"
121
122           hashref, verbal feedback to help choose better passwords, contains
123           useful information when "score <= 2":
124
125           •   "warning"
126
127               a string (sometimes empty), or an arrayref "[$string,@values]"
128               suitable for localisation. Explains what's wrong, e.g. 'this is
129               a top-10 common password'.
130
131           •   "suggestions"
132
133               a possibly-empty array of suggestions to help choose a less
134               guessable password. e.g. 'Add another word or two'; again,
135               elements can be strings or arrayrefs for localisation.
136
137       •   "matches"
138
139           the list of patterns that zxcvbn based the guess calculation on;
140           this is rarely useful to show to users
141
142       All the objects in the returned value can be serialised to JSON, if you
143       set "convert_blessed" or equivalent in your JSON library.
144
145       Options
146
147         my $strength = password_strength($password,\%options);
148
149       You can pass in several options to customise the behaviour of this
150       function. From most-frequently useful:
151
152       •   "user_input"
153
154           the most useful option: a hashref of field names and values that
155           should be considered "obvious guesses", e.g. account name, user's
156           real name, company name, &c. (see
157           "Data::Password::zxcvbn::Match::UserInput")
158
159       •   "max_score_for_feedback"
160
161           the maximum ""score"" above which no feedback will be provided,
162           defaults to 2; provide a higher value if you want feedback even on
163           strong passwords
164
165       •   "modules"
166
167           arrayref of module names to use instead of the built-in
168           "Data::Password::zxcvbn::Match::*" classes; if you want to add a
169           module, you still have to list all the built-ins in this array;
170           "Data::Password::zxcvbn::Match::BruteForce" is special, and if
171           included here, it will be ignored
172
173       •   "match_list_module"
174
175           module name to use instead of "Data::Password::zxcvbn::MatchList"
176           to run all the computations; the module should really be a subclass
177           of that default one, with maybe some customised messages
178
179       •   "ranked_dictionaries"
180
181       •   "l33t_table"
182
183           dictionaries and transliteration table, see
184           "Data::Password::zxcvbn::Match::Dictionary"
185
186       •   "graphs"
187
188           adjacency graphs for keyboard-related spatial guesses, see
189           "Data::Password::zxcvbn::Match::Spatial"
190
191       •   "regexes"
192
193           which regexes to use, see "Data::Password::zxcvbn::Match::Regex"
194

AUTHOR

202       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
203

COPYRIGHT AND LICENSE

205       This software is copyright (c) 2022 by BroadBean UK, a CareerBuilder
206       Company.
207
208       This is free software; you can redistribute it and/or modify it under
209       the same terms as the Perl 5 programming language system itself.
210
211
212
213perl v5.36.1                      2023-09-13         Data::Password::zxcvbn(3)