++ed by:
KES JACOBY

2 PAUSE users
2 non-PAUSE users.

Gianni Ceccarelli

NAME

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

VERSION

version 1.0.2

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.

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 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:

SEE ALSO

AUTHOR

Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 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.