NAME

Crypt::Password::Util - Crypt password utilities

VERSION

This document describes version 0.17 of Crypt::Password::Util (from Perl distribution Crypt-Password-Util), released on 2016-01-21.

SYNOPSIS

 use Crypt::Password::Util qw(
     crypt
     looks_like_crypt
     crypt_type
 );

Generating crypted password:

 say crypt('pass'); # automatically choose the appropriate type and salt

Recognizing whether a string is a crypted password:

 # return yes/no
 say looks_like_crypt('62F4a6/89.12z');   # 1
 say looks_like_crypt('foo');             # 0

 # return the crypt type
 say crypt_type('62F4a6/89.12z');                    # CRYPT
 say crypt_type('$1$$...');                          # MD5-CRYPT
 say crypt_type('$apr1$4DdvgCFk$...');               # MD5-CRYPT
 say crypt_type('$5$4DdvgCFk$...');                  # SSHA256
 say crypt_type('$6$4DdvgCFk$...');                  # SSHA512
 say crypt_type('1a1dc91c907325c69271ddf0c944bc72'); # PLAIN-MD5
 say crypt_type('$2a$08$TTSynMjJTrXiv3qEZFyM1.H9tjv71i57p2r63QEJe/2p0p/m1GIy2'); # BCRYPT
 say crypt_type('foo');                              # undef

 # return detailed information
 my $res = crypt_type('$1$$oXYGukVGYa16SN.Pw5vNt/', 1);
 # => {type=>'MD5-CRYPT', header=>'$1$', salt=>'', hash=>'oXYGukVGYa16SN.Pw5vNt/'}
 $res = crypt_type('foo', 1);
 # => undef

DESCRIPTION

Crypt::Password::Util provides routines to: 1) generate crypted password; 2) recognition of whether a string is a crypted password or not, and its crypt type.

It recognizes several types of crypt methods:

BCRYPT
Passphrase scheme based on Blowfish, designed by Niels Provos and David Mazieres for OpenBSD.

Recognized by: $2$ or $2a$ header followed by cost, followed by 22 base64-digits salt and 31 digits hash.

More info: <https://www.usenix.org/legacy/event/usenix99/provos/provos_html/>
CRYPT
Traditional DES crypt.

Recognized by: 11 digit base64 characters.

More info: <http://perldoc.perl.org/functions/crypt.html>
EXT-DES
Extended DES crypt.

Recognized by: underscore followed by 19 digit base64 characters.

More info: <https://en.wikipedia.org/wiki/Crypt_%28C%29#BSDi_extended_DES-based_scheme>
MD5-CRYPT
A baroque passphrase scheme based on MD5, designed by Poul-Henning Kamp and originally implemented in FreeBSD.

Recognized by: $1$ or $apr1$ header.

More info: <http://static.usenix.org/event/usenix99/provos/provos_html/node10.html>
PLAIN-MD5
Unsalted MD5 hash, popular with PHP web applications.

Recognized by: 32 digits of hex characters.

More info: <http://en.wikipedia.org/wiki/MD5>
SSHA256
Salted SHA256, supported by glibc 2.7+.

Recognized by: $5$ header.

More info: <http://en.wikipedia.org/wiki/SHA-2>
SSHA512
Salted SHA512, supported by glibc 2.7+.

Recognized by: $6$ header.

More info: <http://en.wikipedia.org/wiki/SHA-2>

FUNCTIONS

looks_like_crypt($str) => bool

Return true if $str looks like a crypted password. If you want more information instead of just a yes/no, use "crypt_type()".

crypt_type($str[, $detail]) => str|hash

Return crypt type, or undef if $str does not look like a crypted password. Currently known types:

If $detail is set to true, will return a hashref of information instead. This include "type", as well as the parsed header, salt, etc.

crypt($str) => str

Try to create a "reasonably secure" crypt password with the support available from the system's crypt().

Will first try to create a cost-based crypt, using rounds value that will approximately take ~10ms (on my PC computer, an Intel Core i5-2400 CPU, that is) to create. This lets a server verify ~100 passwords per second, which should be enough for many cases. On OpenBSD, will try BCRYPT with cost=7. On other systems, will try SSHA512 with rounds=15000.

If the above fails (unsupported by your crypt()), will fallback to MD5-CRYPT (supported by NetBSD), then CRYPT. Will die if that also fails.

HOMEPAGE

Please visit the project's homepage at <https://metacpan.org/release/Crypt-Password-Util>.

SOURCE

Source repository is at <https://github.com/perlancar/perl-Crypt-Password-Util>.

BUGS

Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Crypt-Password-Util>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.