NAME

Crypt::Password - Unix-style, Variously Hashed Passwords

SYNOPSIS

 use Crypt::Password;
 
 my $hashed = password("plaintext");
 
 $user->set_password($hashed);
 
 if (check_password($hash_from_database, $text_from_user)) {
     # authenticated
 }

 my $definitely_crypted_just_then = crypt_password($maybe_already_crypted);

 # you also might want to
 password($a) eq password($b)
 # WARNING: password() will embody but not crypt an already crypted string.
 #          if you are checking something from the outside world, pass both
 #          things to check_password()

 # imagine stealing a crypted string and using it as a password. it happens.

 # WARNING: the following applies to glibc's crypt() only
 #          Non-Linux systems beware, see KNOWN ISSUES

 # Default algorithm, supplied salt:
 my $hashed = password("password", "salt");
 
 # md5, no salt:
 my $hashed = password("password", "", "md5");
 
 # sha512, invented salt: 
 my $hashed = password("password", undef, "sha512");

DESCRIPTION

This is just a wrapper for perl's crypt(), which can do everything you would probably want to do to store a password, but this is to make usage easier. The object stringifies to the return string of the crypt() function, which is (on Linux/glibc et al) in Modular Crypt Format:

 # scalar($hashed):
 #    v digest   v hash ->
 #   $5$%RK2BU%L$aFZd1/4Gpko/sJZ8Oh.ZHg9UvxCjkH1YYoLZI6tw7K8
 #      ^ salt ^

That you can store, etc, retrieve then use it in check_password() to validate a login, etc.

Not without some danger, so read on, you could also string compare it to the output of another password(), as long as the salt is the same. If you pass a crypted string as the salt it will use the same salt.

If the given string is already hashed it is assumed to be okay to use it as is. So if you are checking something from the outside world pass it as the second argument to check_password($saved, $wild). You could also use crypt_password($wild), which will definitely crypt its input.

This means simpler code and users can supply pre-hashed passwords initially, but if you do it wrong a stolen hash could be used as a password, so buck up your ideas.

If you aren't running Linux/glibc, everything after the WARNING in the synopsis is dubious as. If you've got insight into how this module can work better on your platform I would love to hear from you.

FUNCTIONS

password ( $password [, $salt [, $algorithm]] )

Constructs a Crypt::Password object.

check_password ( $saved_crypt, $wild_password )

Checks that $wild_password is what $saved_crypt was.

crypt_password ( $password [, $salt [, $algorithm]] )

Same as above but will definitely crypt $password, even if it looks crypted. See warning labels.

KNOWN ISSUES

Cryptographic functionality depends greatly on your local crypt(3). Old Linux may not support sha*, many other platforms only support md5, or that and Blowfish, etc. You are likely fine, but you should run the test suite and read the output carefully. Better still, run your own test suite and you'll know you're okay.

Implementations break down into Modular Format and Extended Format.

Linux/glib does Modular Format as described in DESCRIPTION, it supports many algorithms, supposedly.

FreeSec and most BSDs do Extended Format with the DES algorithm. We modify the output so it's easier to parse again by putting dollar signs in around the salt. The salt must be 2 or 8 characters long, or just 2 on Windows.

SUPPORT, SOURCE

If you have a problem, submit a test case via a fork of the github repo.

 http://github.com/st3vil/Crypt-Password

AUTHOR AND LICENCE

Code by Steve Eirium, nostrasteve@gmail.com, idea by Sam Vilain, sam.vilain@catalyst.net.nz. Development commissioned by NZ Registry Services.

Copyright 2009, NZ Registry Services. This module is licensed under the Artistic License v2.0, which permits relicensing under other Free Software licenses.

SEE ALSO

Digest::SHA, Authen::Passphrase, Crypt::SaltedHash