.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::UnixCrypt_XS 3pm"
.TH Crypt::UnixCrypt_XS 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::UnixCrypt_XS \- perl xs interface for a portable traditional 
crypt function.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  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 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the DES-based Unix \fIcrypt\fR function.  For those who need to construct non-standard variants of \fIcrypt\fR, the various building blocks used in \fIcrypt\fR are also supplied separately.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "crypt( \s-1PASSWORD, SALT\s0 )" 4
.IX Item "crypt( PASSWORD, SALT )"
This is the conventional \fIcrypt\fR interface.  \fI\s-1PASSWORD\s0\fR and \fI\s-1SALT\s0\fR 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 \fIcrypt\fR as a salt argument.  Three different types of hashing may occur:
.Sp
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.
.Sp
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 \s-1DES\s0 algorithm in one of 4096 different ways.  The first eight characters of the password are used as a \s-1DES\s0 key, to encrypt a block of zeroes through 25 iterations of the modified \s-1DES.\s0  The block output by the final iteration is the hash, and it is returned in base 64 (as eleven digits).
.Sp
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 \s-1DES\s0 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.
.IP "crypt_rounds( \s-1PASSWORD, NROUNDS, SALTNUM, BLOCK\s0 )" 4
.IX Item "crypt_rounds( PASSWORD, NROUNDS, SALTNUM, BLOCK )"
This is the core of the DES-based \fIcrypt\fR algorithm, exposed here to allow variant hash functions to be built.  \fI\s-1PASSWORD\s0\fR is a string; its first eight characters are used as a \s-1DES\s0 key.  \fI\s-1SALTNUM\s0\fR is an integer; its low 24 bits are used to modify the \s-1DES\s0 algorithm.  \fI\s-1BLOCK\s0\fR must be a string exactly eight bytes long.  The data block is passed through \fI\s-1NROUNDS\s0\fR iterations of the modified \s-1DES,\s0 and the final output block (also a string of exactly eight bytes) is returned.
.IP "fold_password( \s-1PASSWORD\s0 )" 4
.IX Item "fold_password( PASSWORD )"
This is the pre-hashing algorithm used in the extended \s-1DES\s0 algorithm to fold a long password to the size of a \s-1DES\s0 key.  It takes a password of any length, and returns a password of eight characters which is completely equivalent in the extended \s-1DES\s0 algorithm.  Note: the password returned may contain \s-1NUL\s0 characters.  The functions in this module correctly handle NULs in password strings, but a normal C library \fIcrypt\fR cannot.  If you need the short password to contain no NULs, perform the substitution \f(CW\*(C`s/\e0/\ex80/g\*(C'\fR: the top bit of each password character is ignored, so the result is equivalent.
.IP "base64_to_block( \s-1BASE64\s0 )" 4
.IX Item "base64_to_block( BASE64 )"
This converts a data block from a string of eleven base 64 digits to a raw string of eight bytes.
.IP "block_to_base64( \s-1BLOCK\s0 )" 4
.IX Item "block_to_base64( BLOCK )"
This converts a data block from a raw string of eight bytes to a string of eleven base 64 digits.
.IP "base64_to_int24( \s-1BASE64\s0 )" 4
.IX Item "base64_to_int24( BASE64 )"
This converts a 24\-bit integer from a string of four base 64 digits to a Perl integer.
.IP "int24_to_base64( \s-1VALUE\s0 )" 4
.IX Item "int24_to_base64( VALUE )"
This converts a 24\-bit integer from a Perl integer to a string of four base 64 digits.
.IP "base64_to_int12( \s-1BASE64\s0 )" 4
.IX Item "base64_to_int12( BASE64 )"
This converts a 12\-bit integer from a string of two base 64 digits to a Perl integer.
.IP "int12_to_base64( \s-1VALUE\s0 )" 4
.IX Item "int12_to_base64( VALUE )"
This converts a 12\-bit integer from a Perl integer to a string of two base 64 digits.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.
.SH "RATIONALE"
.IX Header "RATIONALE"
Crypt::UnixCrypt_XS provide a fast portable crypt function. Perl's internal crypt is not present at every system. Perl calls the \fIcrypt\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CWcrypt(3)\fR, Crypt::UnixCrypt
.SH "AUTHOR"
.IX Header "AUTHOR"
Boris Zentner, <bzm@2bz.de>, the original C source code was 
written by Eric Young, eay@psych.uq.oz.au.
.SH "CREDITS"
.IX Header "CREDITS"
Fixes, Bug Reports, Docs have been generously provided by:
.PP
.Vb 3
\&  Andrew Main (Zefram) <zefram@fysh.org>
\&  Guenter Knauf
\&Thanks!
.Ve
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2004, 2005, 2006, 2007 by Boris Zentner
.PP
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.