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

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.

perl v5.36.0                                       2023-04-04                        Data::Password::zxcvbn(3pm)

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.

       Returnvalue

       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"

Name

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

Synopsis

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

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