Provided by: libdata-password-zxcvbn-perl_1.0.6-1_all bug

NAME

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

VERSION

       version 1.0.6

SYNOPSIS

         use Data::Password::zxcvbn qw(password_strength);

         my $strength = password_strength($my_password);
         warn $strength->{warning} if $strength->{score} < 3;

DESCRIPTION

       This is a Perl port of Dropbox's password strength estimation library, "zxcvbn"
       <https://github.com/dropbox/zxcvbn>.

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

       The code has been tested against the Python port's <https://github.com/dwolfhub/zxcvbn-
       python> password_expected_value.json 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%.

FUNCTIONS

   "password_strength"
         my $strength = password_strength($password);

       This is the main entry point for the library, and the only function you usually care
       about.

       It analyses the given string, finding the easiest way that a password cracking algorithm
       would guess it, and reports on its findings.

       Return value

       The return value is a hashref, with these keys:

       •   "guesses"

           estimated guesses needed to crack password

       •   "guesses_log10"

           order of magnitude of "guesses"

       •   "crack_times_seconds"

           hashref of back-of-the-envelope crack time estimations, in seconds, based on a few
           scenarios:

           •   "online_throttling_100_per_hour"

               online attack on a service that rate-limits authentication attempts

           •   "online_no_throttling_10_per_second"

               online attack on a service that doesn't rate-limit, or where an attacker has
               outsmarted rate-limiting.

           •   "offline_slow_hashing_1e4_per_second"

               offline attack. assumes multiple attackers, proper user-unique salting, and a slow
               hash function with moderate work factor, such as bcrypt, scrypt, PBKDF2.

           •   "offline_fast_hashing_1e10_per_second"

               offline attack with user-unique salting but a fast hash function like SHA-1,
               SHA-256 or MD5. A 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.

       •   "crack_times_display"

           same keys as "crack_times_seconds", but more useful for display: the values are
           arrayrefs "["english string",$value]" that can be passed to I18N libraries like
           "Locale::Maketext" to get localised versions with proper plurals

       •   "score"

           Integer from 0-4 (useful for implementing a strength bar):

           •   0

               too guessable: risky password. ("guesses < 10e3")

           •   1

               very guessable: protection from throttled online attacks. ("guesses < 10e6")

           •   2

               somewhat guessable: protection from un-throttled online attacks. ("guesses <
               10e8")

           •   3

               safely un-guessable: moderate protection from offline slow-hash scenario.
               ("guesses < 10e10")

           •   4

               very un-guessable: strong protection from offline slow-hash scenario. ("guesses >=
               10e10")

       •   "feedback"

           hashref, verbal feedback to help choose better passwords, contains useful information
           when "score <= 2":

           •   "warning"

               a string (sometimes empty), or an arrayref "[$string,@values]" suitable for
               localisation. Explains what's wrong, e.g. 'this is a top-10 common password'.

           •   "suggestions"

               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.

       •   "matches"

           the list of patterns that zxcvbn based the guess calculation on; this is rarely useful
           to show to users

       All the objects in the returned value can be serialised to JSON, if you set
       "convert_blessed" or equivalent in your JSON library.

       Options

         my $strength = password_strength($password,\%options);

       You can pass in several options to customise the behaviour of this function. From most-
       frequently useful:

       •   "user_input"

           the most useful option: a hashref of field names and values that should be considered
           "obvious guesses", e.g. account name, user's real name, company name, &c. (see
           "Data::Password::zxcvbn::Match::UserInput")

       •   "max_score_for_feedback"

           the maximum ""score"" above which no feedback will be provided, defaults to 2; provide
           a higher value if you want feedback even on strong passwords

       •   "modules"

           arrayref of module names to use instead of the built-in
           "Data::Password::zxcvbn::Match::*" classes; if you want to add a module, you still
           have to list all the built-ins in this array;
           "Data::Password::zxcvbn::Match::BruteForce" is special, and if included here, it will
           be ignored

       •   "match_list_module"

           module name to use instead of "Data::Password::zxcvbn::MatchList" to run all the
           computations; the module should really be a subclass of that default one, with maybe
           some customised messages

       •   "ranked_dictionaries"

       •   "l33t_table"

           dictionaries and transliteration table, see
           "Data::Password::zxcvbn::Match::Dictionary"

       •   "graphs"

           adjacency graphs for keyboard-related spatial guesses, see
           "Data::Password::zxcvbn::Match::Spatial"

       •   "regexes"

           which regexes to use, see "Data::Password::zxcvbn::Match::Regex"

SEE ALSO

       •   the original implementation by Dropbox <https://github.com/dropbox/zxcvbn>

       •   the Python port <https://github.com/dwolfhub/zxcvbn-python>

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.