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.

SEE ALSO

Authen::Passphrase which recognizes more encodings (but currently not SSHA256 and SSHA512).

Crypt::Bcrypt::Easy to generate BCRYPT crypts on systems that do not natively support it.

Crypt::PasswdMD5 to generate MD5-CRYPT crypts on systems that do not natively support it.

Crypt::Password which also provides a routine to compare a password with a crypted password.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by perlancar@cpan.org.

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

cpanm Crypt::Password::Util

perl -MCPAN -e shell
install Crypt::Password::Util