1Crypt::UnixCrypt_XS(3)User Contributed Perl DocumentationCrypt::UnixCrypt_XS(3)
2
3
4

NAME

6       Crypt::UnixCrypt_XS - perl xs interface for a portable traditional
7       crypt function.
8

SYNOPSIS

10         use Crypt::UnixCrypt_XS qw/crypt/;
11         my $hashed = crypt( $password, $salt );
12
13         use Crypt::UnixCrypt_XS qw/crypt_rounds fold_password
14             base64_to_block block_to_base64
15             base64_to_int24 int24_to_base64
16             base64_to_int12 int12_to_base64/;
17         $block = crypt_rounds( $password, $nrounds, $saltnum, $block );
18         $password = fold_password( $password );
19         $block = base64_to_block( $base64 );
20         $base64 = block_to_base64( $block );
21         $saltnum = base64_to_int24( $base64 );
22         $base64 = int24_to_base64( $saltnum );
23         $saltnum = base64_to_int12( $base64 );
24         $base64 = int12_to_base64( $saltnum );
25

DESCRIPTION

27       This module implements the DES-based Unix crypt function.  For those
28       who need to construct non-standard variants of crypt, the various
29       building blocks used in crypt are also supplied separately.
30

FUNCTIONS

32       crypt( PASSWORD, SALT )
33           This is the conventional crypt interface.  PASSWORD and SALT are
34           both strings.  The password will be hashed, in a manner determined
35           by the salt, and a string is returned containing the salt and hash.
36           The salt is at the beginning of the returned string, and only the
37           beginning of the salt string is examined, so it is acceptable to
38           use a string returned by crypt as a salt argument.  Three different
39           types of hashing may occur:
40
41           If the salt is an empty string, then the password is ignored and an
42           empty string is returned.  The empty salt/hash string is thus used
43           to not require a password.
44
45           If the salt string starts with two base 64 digits (from the set
46           [./0-9A-Za-z]), then the password is hashed using the traditional
47           DES-based algorithm.  The salt is used to modify the DES algorithm
48           in one of 4096 different ways.  The first eight characters of the
49           password are used as a DES key, to encrypt a block of zeroes
50           through 25 iterations of the modified DES.  The block output by the
51           final iteration is the hash, and it is returned in base 64 (as
52           eleven digits).
53
54           If the salt string starts with an underscore character and then
55           eight base 64 digits then the password is hashed using the extended
56           DES-based algorithm from BSDi.  The first four base 64 digits
57           specify how many encryption rounds are to be performed.  The next
58           four base 64 digits are used to modify the DES algorithm in one of
59           16777216 different ways.  If the password is longer than eight
60           characters, it is hashed down to eight characters before being used
61           as a key, so all characters of the password are significant.
62
63       crypt_rounds( PASSWORD, NROUNDS, SALTNUM, BLOCK )
64           This is the core of the DES-based crypt algorithm, exposed here to
65           allow variant hash functions to be built.  PASSWORD is a string;
66           its first eight characters are used as a DES key.  SALTNUM is an
67           integer; its low 24 bits are used to modify the DES algorithm.
68           BLOCK must be a string exactly eight bytes long.  The data block is
69           passed through NROUNDS iterations of the modified DES, and the
70           final output block (also a string of exactly eight bytes) is
71           returned.
72
73       fold_password( PASSWORD )
74           This is the pre-hashing algorithm used in the extended DES
75           algorithm to fold a long password to the size of a DES key.  It
76           takes a password of any length, and returns a password of eight
77           characters which is completely equivalent in the extended DES
78           algorithm.  Note: the password returned may contain NUL characters.
79           The functions in this module correctly handle NULs in password
80           strings, but a normal C library crypt cannot.  If you need the
81           short password to contain no NULs, perform the substitution
82           "s/\0/\x80/g": the top bit of each password character is ignored,
83           so the result is equivalent.
84
85       base64_to_block( BASE64 )
86           This converts a data block from a string of eleven base 64 digits
87           to a raw string of eight bytes.
88
89       block_to_base64( BLOCK )
90           This converts a data block from a raw string of eight bytes to a
91           string of eleven base 64 digits.
92
93       base64_to_int24( BASE64 )
94           This converts a 24-bit integer from a string of four base 64 digits
95           to a Perl integer.
96
97       int24_to_base64( VALUE )
98           This converts a 24-bit integer from a Perl integer to a string of
99           four base 64 digits.
100
101       base64_to_int12( BASE64 )
102           This converts a 12-bit integer from a string of two base 64 digits
103           to a Perl integer.
104
105       int12_to_base64( VALUE )
106           This converts a 12-bit integer from a Perl integer to a string of
107           two base 64 digits.
108
109   EXPORT
110       None by default.
111

RATIONALE

113       Crypt::UnixCrypt_XS provide a fast portable crypt function. Perl's
114       internal crypt is not present at every system. Perl calls the crypt
115       function of the system's C library. This may lead to trouble if the
116       system's crypt presents different results for the same key and salt,
117       but different processid's. Crypt::UnixCrypt is the cure here, but it is
118       to slow. On my computer Crypt::UnixCrypt_XS is about 800 times faster
119       than Crypt::UnixCrypt.
120

SEE ALSO

122       crypt(3), Crypt::UnixCrypt
123

AUTHOR

125       Boris Zentner, <bzm@2bz.de>, the original C source code was written by
126       Eric Young, eay@psych.uq.oz.au.
127

CREDITS

129       Fixes, Bug Reports, Docs have been generously provided by:
130
131         Andrew Main (Zefram) <zefram@fysh.org>
132         Guenter Knauf
133       Thanks!
134
136       Copyright (C) 2004, 2005, 2006, 2007 by Boris Zentner
137
138       This library is free software; you can redistribute it and/or modify it
139       under the same terms as Perl itself, either Perl version 5.8.3 or, at
140       your option, any later version of Perl 5 you may have available.
141
142
143
144perl v5.34.0                      2021-07-22            Crypt::UnixCrypt_XS(3)
Impressum