NAME¶
Crypt::UnixCrypt_XS - perl xs interface for a portable traditional crypt
function.
SYNOPSIS¶
use Crypt::UnixCrypt_XS qw/crypt/;
my $hashed = crypt( $password, $salt );
use Crypt::UnixCrypt_XS qw/crypt_rounds fold_password
base64_to_block block_to_base64
base64_to_int24 int24_to_base64
base64_to_int12 int12_to_base64/;
$block = crypt_rounds( $password, $nrounds, $saltnum, $block );
$password = fold_password( $password );
$block = base64_to_block( $base64 );
$base64 = block_to_base64( $block );
$saltnum = base64_to_int24( $base64 );
$base64 = int24_to_base64( $saltnum );
$saltnum = base64_to_int12( $base64 );
$base64 = int12_to_base64( $saltnum );
DESCRIPTION¶
This module implements the DES-based Unix
crypt function. For those who
need to construct non-standard variants of
crypt, the various building
blocks used in
crypt are also supplied separately.
FUNCTIONS¶
- crypt( PASSWORD, SALT )
- This is the conventional crypt interface. PASSWORD and
SALT are both strings. The password will be hashed, in a manner
determined by the salt, and a string is returned containing the salt and
hash. The salt is at the beginning of the returned string, and only the
beginning of the salt string is examined, so it is acceptable to use a
string returned by crypt as a salt argument. Three different types
of hashing may occur:
If the salt is an empty string, then the password is ignored and an empty
string is returned. The empty salt/hash string is thus used to not require
a password.
If the salt string starts with two base 64 digits (from the set
[./0-9A-Za-z]), then the password is hashed using the traditional
DES-based algorithm. The salt is used to modify the DES algorithm in one
of 4096 different ways. The first eight characters of the password are
used as a DES key, to encrypt a block of zeroes through 25 iterations of
the modified DES. The block output by the final iteration is the hash, and
it is returned in base 64 (as eleven digits).
If the salt string starts with an underscore character and then eight base
64 digits then the password is hashed using the extended DES-based
algorithm from BSDi. The first four base 64 digits specify how many
encryption rounds are to be performed. The next four base 64 digits are
used to modify the DES algorithm in one of 16777216 different ways. If the
password is longer than eight characters, it is hashed down to eight
characters before being used as a key, so all characters of the password
are significant.
- crypt_rounds( PASSWORD, NROUNDS, SALTNUM, BLOCK )
- This is the core of the DES-based crypt algorithm, exposed here to
allow variant hash functions to be built. PASSWORD is a string; its
first eight characters are used as a DES key. SALTNUM is an
integer; its low 24 bits are used to modify the DES algorithm.
BLOCK must be a string exactly eight bytes long. The data block is
passed through NROUNDS iterations of the modified DES, and the
final output block (also a string of exactly eight bytes) is
returned.
- fold_password( PASSWORD )
- This is the pre-hashing algorithm used in the extended DES algorithm to
fold a long password to the size of a DES key. It takes a password of any
length, and returns a password of eight characters which is completely
equivalent in the extended DES algorithm. Note: the password returned may
contain NUL characters. The functions in this module correctly handle NULs
in password strings, but a normal C library crypt cannot. If you
need the short password to contain no NULs, perform the substitution
"s/\0/\x80/g": the top bit of each password character is
ignored, so the result is equivalent.
- base64_to_block( BASE64 )
- This converts a data block from a string of eleven base 64 digits to a raw
string of eight bytes.
- block_to_base64( BLOCK )
- This converts a data block from a raw string of eight bytes to a string of
eleven base 64 digits.
- base64_to_int24( BASE64 )
- This converts a 24-bit integer from a string of four base 64 digits to a
Perl integer.
- int24_to_base64( VALUE )
- This converts a 24-bit integer from a Perl integer to a string of four
base 64 digits.
- base64_to_int12( BASE64 )
- This converts a 12-bit integer from a string of two base 64 digits to a
Perl integer.
- int12_to_base64( VALUE )
- This converts a 12-bit integer from a Perl integer to a string of two base
64 digits.
EXPORT¶
None by default.
RATIONALE¶
Crypt::UnixCrypt_XS provide a fast portable crypt function. Perl's internal
crypt is not present at every system. Perl calls the
crypt function of
the system's C library. This may lead to trouble if the system's crypt
presents different results for the same key and salt, but different
processid's. Crypt::UnixCrypt is the cure here, but it is to slow. On my
computer Crypt::UnixCrypt_XS is about 800 times faster than Crypt::UnixCrypt.
SEE ALSO¶
crypt(3), Crypt::UnixCrypt
AUTHOR¶
Boris Zentner, <bzm@2bz.de>, the original C source code was written by
Eric Young, eay@psych.uq.oz.au.
CREDITS¶
Fixes, Bug Reports, Docs have been generously provided by:
Andrew Main (Zefram) <zefram@fysh.org>
Guenter Knauf
Thanks!
COPYRIGHT AND LICENSE¶
Copyright (C) 2004, 2005, 2006, 2007 by Boris Zentner
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.8.3 or, at your option,
any later version of Perl 5 you may have available.