Data::Passphrase - rule-based passphrase strength checker
This documentation refers to Data::Passphrase version 0.0.7.
Object-oriented interface:
use Data::Passphrase; # build passphrase object my $passphrase_object = Data::Passphrase->new({ username => $ENV{LOGNAME}, }); # evaluate each rule in turn for (;;) { print 'Passphrase (clear): '; chomp (my $passphrase = <STDIN>); $passphrase_object->set_passphrase($passphrase); $passphrase_object->validate(); my $code = $passphrase_object->get_code (); my $message = $passphrase_object->get_message(); my $score = $passphrase_object->get_score (); print "$code $message, score: $score\%\n"; }
Procedural interface:
use Data::Passphrase qw(validate_passphrase); for (;;) { print 'Passphrase (clear): '; chomp (my $passphrase = <STDIN>); my $result = validate_passphrase { passphrase => $passphrase, username => $ENV{LOGNAME}, }; print "$result->{code} $result->{message}, score: $result->{score}\%\n"; }
This module provides object-oriented and procedural interfaces for checking passphrase strength against a set of customizable rules. An Apache handler that provides HTTP and SOAP services makes strength-checking possible by remote applications.
This module provides an object class for each request, containing the username, the passphrase submitted, configuration data, and more. There is a constructor new, which takes a reference to a hash of initial attribute settings, and accessor methods of the form get_attribute() and set_attribute(). See "Attributes".
new
The object class overloads string and numeric conversion for convenience when writing rules. In string context, an object evaluates to the text of the passphrase itself. In numeric context, the object evaluates to the length of the passphrase.
In addition to the constructor and accessor methods, the following special methods are available.
$value = $self->get_data($key)
Retrieve custom data $value associated with $key. Useful when a rule needs to cache data for retrieval by subsequent rules.
$value
$key
$self->set_data($key, $value)
Associate custom data $value with $key for later retrieval. See also get_data().
$self->validate()
Evaluate each rule on the passphrase specified by the passphrase attribute. Rules are evaulated in the order specified, each one generating a separate score for the passphrase. The lowest score is returned as the overall passphrase score. After this method is called, the code, message, and score attributes will contain the results of the validation.
The attributes below can be accessed via methods of the form get_attribute() and set_attribute().
HTTP-like status code to be returned at the end of the request.
If TRUE, enable debugging to STDERR.
HTTP-like status message to be returned at the end of the request.
The passphrase submitted by the user.
The ruleset used to validate passphrases, either as a Data::Passphrase::Ruleset object or as a filename. Defaults to /etc/passphrase_rules.
The resultant score, usually between 0 and 100, for the passphrase.
The username, which may be useful to rules. Defaults to $r->user().
$results = validate_passphrase \%attributes
Validate a passphrase. Attributes passed in %attributes are the same as for the object-oriented interface. $results contains three entries -- code, message, and score -- whose values correspond to those returned by the object-oriented attributes of the same names.
%attributes
$results
code
message
score
Passphrase rules may be specified directly as Data::Passphrase::Rule objects or read from a script file (see "EXAMPLES"). This script should return a reference to a list of hash references, each of which is used to construct a Data::Passphrase::Rule object. Hence, the following attributes have meaning to the module and related programs:
status code returned if passphrase fails this rule
status message returned if passphrase fails this rule
passphrase(s) used to test this rule
code to do the validation and return a score
When validating passphrases, each subroutine referenced by validate will be called in turn. If every rule's validate subroutine returns a value exceeding the passing score (which defaults to 0.6), a code of 200 and message of Passphrase accepted will be returned; otherwise, the code and message specified will be returned.
validate
Passphrase accepted
The validation subroutine is called with two arguments: an Data::Passphrase object, and a reference to a hash of user-defined data. The Data::Passphrase class makes use of operator overloading to allow some convenient syntax in the rules. In string context, the object evaluates to the text of the passphrase to avoid the need to call get_passphrase(). In numeric context, the object evaluates to the length of the passphrase.
Using the set_data() method, a rule can stow away data for use by a later rule. The data is stored as key/value pairs in a hash. A reference to this hash is passed as the second argument to the validate method; you can also use get_data() to get to it.
Return values from the validate subroutine are interpreted as follows:
The candidate passphrase has passed this rule. Return 200 Passphrase accepted without processing any subsequent rules.
200 Passphrase accepted
The candidate passphrase has failed this rule. Continue with subsequent rules; the lowest score returned by all the rules will be multiplied by 100, have it's non-integer part removed, and returned.
The candidate passphrase has passed this rule. Continue with subsequent rules and return 200 Passphrase accepted if the passphrase passes all of them. The lowest score returned by all the rules will be multiplied by 100, have it's non-integer part removed, and returned.
For the benefit of the HTTP services provided by Data::Passphrase::Apache, most rules should use codes in the 4xx range, which according to RFC 2616 denotes a client error. It's wise to avoid codes in the 40x or 41x range because they already have common meanings. Choosing a different code for each rule makes it easier for applications to understand why a passphrase was rejected, but it's not required.
The HTTP services provided by Data::Passphrase::Apache build status lines from the code and message attributes. The string "Passphrase " is prepended to the latter. The message should always be phrased as if the passphrase failed to pass the rule, for example, is too short.
is too short
The test attribute specifies one or more passphrases that should fail the rule and is meant to be used by an external program such as the included passphrase-test program. It may be represented in any way understandable by the test program, but passphrase-test expects a single passphrase in a scalar, a reference to an array of one or more passphrases, or a reference to a subroutine that returns zero or more passphrases. This attribute also serves as documentation for the rule in the form of example passphrases the rule is meant to disallow.
Here's an example with only one rule:
Readonly my $MINIMUM_TOTAL_CHARACTERS => 15; return [ { code => 450, message => 'is too short', test => 'X' x ($MINIMUM_TOTAL_CHARACTERS - 1), validate => sub { $_[0] >= $MINIMUM_TOTAL_CHARACTERS }, }, ]; __EOF__
This rule causes 450 Passphrase is too short and a score of 0 to be returned for any passphrase shorter than 15 characters. The validate subroutine can use $_[0] as a comparator because in numeric context it evaluates to the length of the passphrase even though it's an Data::Passphrase object. The test data is just a string of 14 Xs -- the passphrase-test script will check to make sure this string results in a 450.
450 Passphrase is too short
0
$_[0]
The validate routine can be written to provide a more informative score:
test => { 'X' x ($MINIMUM_TOTAL_CHARACTERS - 1) => { score => 56 } }, validate => sub { $_[0] / ($MINIMUM_TOTAL_CHARACTERS / 0.6) },
By dividing by a "preferred" length, we get a score that varies based on the length of the candidate passphrase. In this case we divide by 25, which makes 15 a passing score. Specifying a hash for the test attribute lets us test the score of a passphrase that should fail.
For more examples, see the included passphrase_rules file.
/etc/passphrase_rules
Andrew J. Korty <ajk@iu.edu>
Data::Passphrase::Apache(3), Data::Passphrase::Ruleset(3)
To install Data::Passphrase, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Passphrase
CPAN shell
perl -MCPAN -e shell install Data::Passphrase
For more information on module installation, please visit the detailed CPAN module installation guide.