NAME

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

SYNOPSIS

 use Crypt::Password;
 
 my $hashed = password("newpassword");
 
 $user->set_password($hashed);
 
 if (password($from_database)->check($password_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, use check()

 # 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.

 # 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) 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 give it to password() again to ->check($given_password).

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. Actually, if you are running on Linux/glibc you can pass the first password as the salt to the second and it will get it right. Anyway, the danger:

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, ->check($it) against the thing you can trust. You could also use crypt_password(), 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 Darwin/FreeSec I would love to hear from you.

FUNCTIONS

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

Constructs a Crypt::Password object.

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

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

METHODS

check ( $another_password )

Checks the given password hashes the same as that this object represents.

crypt

Returns the crypt string, same as stringifying the object.

salt

Returns the salt.

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.

On FreeSec's crypt, the crypted format is much different. Firstly, salt strings must be either two or eight characters long, in the latter case they will be prepended with an underscore for you. In the string you get back we also put the salt between two dollar signs, to make it slightly less ambiguous, less likely for password() to assume something is crypted when it is not...

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