NAME

Data::Password::zxcvbn::Match - role for match objects

VERSION

version 1.0.2

SYNOPSIS

package My::Password::Match::Something;
use Moo;
with 'Data::Password::zxcvbn::Match';

has some_info => (is=>'ro');

sub make {
  my ($class, $password) = @_;
  return [ $class->new({
    token => some_substring_of($password),
    i => position_of_first_char($token,$password),
    j => position_of_last_char($token,$password),
    some_info => whatever_needed(),
  }) ];
}

sub estimate_guesses {
  my ($self) = @_;
  return $self->some_complexity_estimate();
}

sub feedback_warning { 'this is a bad idea' }
sub feedback_suggestions { return [ 'do something else' ] }

1;

DESCRIPTION

zxcvbn estimates the strength of a password by guessing which way a generic password cracker would produce it, and then guessing after how many tries it would produce it.

This role provides the basic behaviour and interface for the classes that implement that guessing.

ATTRIBUTES

token

Required string: the portion of the password that this object matches. For example, if your class represents "sequences of digits", an instance made from the password abc1234def would have token => '1234'.

i, j

Required integers: the indices of the first and last character of "token" in the password. For the example above, we would have i => 3, j => 6.

guesses

The estimated number of attempts that a generic password cracker would need to guess the particular "token". The value for this attribute is generated on demand by calling "estimate_guesses".

REQUIRED METHODS

make

sub make {
  my ($class, $password) = @_;
  return [ $class->new(\%something), ... ];
}

This factory method should return a sorted arrayref of instances, one for each substring of the $password that could be generated / guessed with the logic that your class represents.

estimate_guesses

sub estimate_guesses {
  my ($self) = @_;
  return $self->some_complexity_estimate();
}

This method should return an integer, representing an estimate of the number of attempts that a generic password cracker would need to guess the particular "token" within the logic that your class represents. For example, if your class represents "sequences of digits", you could hypothesise that the cracker would go in order from 1, so you'd write:

sub estimate_guesses { return 0 + shift->token }

feedback_warning

This method should return a string (possibly empty), or an arrayref [$string,@values] suitable for localisation. The returned value should explain what's wrong, e.g. 'this is a top-10 common password'.

feedback_suggestions

This method should return 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.

METHODS

compare

$match1 <=> $match2
$match1 cmp $match2

The comparison operators are overloaded to sort by "i" and "j", so a sorted list of matches will cover the password from left to right.

guesses_log10

The logarithm in base 10 of "guesses".

guesses_for_password

my $guesses = $match->guesses_for_password($password);

This method will return the same value as "guesses", or some minimum number of guesses, whichever is higher.

This is to make sure that all match have a measurable impact on the estimation of the total complexity.

get_feedback

my %feedback = %{ $match->get_feedback($is_sole_match) };

Returns a hashref, with verbal feedback to help choose better passwords. The hash contains:

• warning

  string (or arrayref for localisation), produced by calling "feedback_warning"

• suggestions

  arrayref of strings (or arrayrefs for localisation), produced by calling "feedback_suggestions".

TO_JSON

fields_for_json

Matches can be serialised to JSON. The serialisation will be a dictionary with all the fields returned by "fields_for_json". By default, it will contain token i j guesses guesses_log10.

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.

cpanm Data::Password::zxcvbn

perl -MCPAN -e shell
install Data::Password::zxcvbn