1Data::Password::zxcvbn:U:sMeartcCho(n3t)ributed Perl DocDuamtean:t:aPtaisosnword::zxcvbn::Match(3)
2
3
4

NAME

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

VERSION

9       version 1.1.2
10

SYNOPSIS

12         package My::Password::Match::Something;
13         use Moo;
14         with 'Data::Password::zxcvbn::Match';
15
16         has some_info => (is=>'ro');
17
18         sub make {
19           my ($class, $password) = @_;
20           return [ $class->new({
21             token => some_substring_of($password),
22             i => position_of_first_char($token,$password),
23             j => position_of_last_char($token,$password),
24             some_info => whatever_needed(),
25           }) ];
26         }
27
28         sub estimate_guesses {
29           my ($self) = @_;
30           return $self->some_complexity_estimate();
31         }
32
33         sub feedback_warning { 'this is a bad idea' }
34         sub feedback_suggestions { return [ 'do something else' ] }
35
36         1;
37

DESCRIPTION

39       zxcvbn estimates the strength of a password by guessing which way a
40       generic password cracker would produce it, and then guessing after how
41       many tries it would produce it.
42
43       This role provides the basic behaviour and interface for the classes
44       that implement that guessing.
45

ATTRIBUTES

47   "token"
48       Required string: the portion of the password that this object matches.
49       For example, if your class represents "sequences of digits", an
50       instance made from the password "abc1234def" would have "token =>
51       '1234'".
52
53   "i", "j"
54       Required integers: the indices of the first and last character of
55       "token" in the password. For the example above, we would have "i => 3,
56       j => 6".
57
58   "guesses"
59       The estimated number of attempts that a generic password cracker would
60       need to guess the particular "token". The value for this attribute is
61       generated on demand by calling ""estimate_guesses"".
62

REQUIRED METHODS

64   "make"
65         sub make {
66           my ($class, $password) = @_;
67           return [ $class->new(\%something), ... ];
68         }
69
70       This factory method should return a sorted arrayref of instances, one
71       for each substring of the $password that could be generated / guessed
72       with the logic that your class represents.
73
74   "estimate_guesses"
75         sub estimate_guesses {
76           my ($self) = @_;
77           return $self->some_complexity_estimate();
78         }
79
80       This method should return an integer, representing an estimate of the
81       number of attempts that a generic password cracker would need to guess
82       the particular "token" within the logic that your class represents. For
83       example, if your class represents "sequences of digits", you could
84       hypothesise that the cracker would go in order from 1, so you'd write:
85
86         sub estimate_guesses { return 0 + shift->token }
87
88   "feedback_warning"
89       This method should return a string (possibly empty), or an arrayref
90       "[$string,@values]" suitable for localisation. The returned value
91       should explain what's wrong, e.g. 'this is a top-10 common password'.
92
93   "feedback_suggestions"
94       This method should return a possibly-empty array of suggestions to help
95       choose a less guessable password. e.g. 'Add another word or two';
96       again, elements can be strings or arrayrefs for localisation.
97

METHODS

99   "compare"
100         $match1 <=> $match2
101         $match1 cmp $match2
102
103       The comparison operators are overloaded to sort by ""i"" and ""j"", so
104       a sorted list of matches will cover the password from left to right.
105
106   "guesses_log10"
107       The logarithm in base 10 of ""guesses"".
108
109   "guesses_for_password"
110         my $guesses = $match->guesses_for_password($password);
111
112       This method will return the same value as ""guesses"", or some minimum
113       number of guesses, whichever is higher.
114
115       This is to make sure that all match have a measurable impact on the
116       estimation of the total complexity.
117
118   "get_feedback"
119         my %feedback = %{ $match->get_feedback($is_sole_match) };
120
121       Returns a hashref, with verbal feedback to help choose better
122       passwords. The hash contains:
123
124       •   "warning"
125
126           string (or arrayref for localisation), produced by calling
127           ""feedback_warning""
128
129       •   "suggestions"
130
131           arrayref of strings (or arrayrefs for localisation), produced by
132           calling ""feedback_suggestions"".
133
134   "TO_JSON"
135   "fields_for_json"
136       Matches can be serialised to JSON. The serialisation will be a
137       dictionary with all the fields returned by ""fields_for_json"". By
138       default, it will contain "token i j guesses guesses_log10".
139

AUTHOR

141       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>
142

144       This software is copyright (c) 2022 by BroadBean UK, a CareerBuilder
145       Company.
146
147       This is free software; you can redistribute it and/or modify it under
148       the same terms as the Perl 5 programming language system itself.
149
150
151
152perl v5.36.1                      2023-09-13  Data::Password::zxcvbn::Match(3)
Impressum