Scroll to navigation

Data::Password::zxcvbn::Match(3pm) User Contributed Perl Documentation Data::Password::zxcvbn::Match(3pm)

NAME

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

VERSION

version 1.0.4

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.

2020-07-13 perl v5.30.3