.\" Copyright (c) 1989 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley.  The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)crypt.3	6.2 (Berkeley) 03/06/91
.\"
.TH CRYPT 3  ""
.AT 3
.SH NAME
crypt, setkey, encrypt, des_setkey, des_cipher \- DES encryption
.SH SYNOPSIS
.nf
.ft B
char *crypt(char *key, char *setting);

void setkey(char *key);
void encrypt(char *block, int flag);

void des_setkey(char *key);
void des_cipher(char *in, char *out, unsigned long salt, int count);
.ft R
.fi
.SH DESCRIPTION
.I Crypt
is the password encryption routine.
It is based on the NBS Data Encryption Standard, with variations intended to
frustrate key search attempts.
.IR Crypt 's
first argument is a NUL-terminated string (normally a user's typed
password).
The second is a character array, 9 bytes in length, consisting of an
underscore (``_'') followed by 4 bytes of iteration count and 4 bytes
of salt.
Both the iteration
.I count
and the 
.I salt 
are encoded as follows: only 6 bits per character are used, with the least
significant bits occurring first.
The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
respectively.
The
.I salt
is used to perturb the DES algorithm in one of 16777216 different ways
(specifically, if bit
.I N
of the
.I salt
is set then bits
.I N
and
.I N+24
are swapped in the DES ``E'' box output).
Then the
.I key
is used to perform
.I count
cumulative encryptions of a 64-bit constant.
.\" XXX need to describe what really happens with the key.
The returned value is a character array, 20 bytes in length, consisting
of the
.I setting
followed by the encoded 64-bit encryption.
.PP
For compatibility with historical versions of
.IR crypt (3),
the
.I setting
may consist of 2 bytes of salt, encoded as above, in which case an
iteration
.I count
of 25 is used, fewer perturbations of DES are available, at most 8
characters of
.I key
are used, and the returned value is a character array 13 bytes in length.
.PP
The other four functions provide (rather primitive) access to the actual
DES algorithm.
The argument to
.I setkey
is a character array of length 64 containing only the characters
with numerical value 0 and 1.
A 56-bit key is derived from dividing this array by dividing the string
into groups of 8 and ignoring the last bit in each group.
.PP
The argument to the
.I encrypt
entry is likewise a character array of length 64 containing 0's and 1's.
The argument array is modified in place to a similar array representing
the bits of the argument after having been subjected to the DES algorithm
using the key set by
.IR setkey .
If
.I flag
is 0, the argument is encrypted; if non-zero, it is decrypted.
.PP
.I Des_setkey
and
.I des_cipher
are faster but less portable than
.I setkey
and
.IR encrypt .
The argument to
.I des_setkey
is a character array of length 8.
The
.B least
significant bit in each character is ignored and the next 7 bits of each
character are concatenated to yield a 56-bit key.
.I Des_cipher
encrypts (or decrypts if
.I count
is negative) the 64-bits stored in the 8 characters at
.I in
using
.I abs(count)
iterations of DES and stores the 64-bit result in the 8 characters at
.IR out .
The
.I salt
specifies perturbations to DES as described above.
.SH "SEE ALSO"
login(1), passwd(1), getpass(3), passwd(5)
.sp
.IR "Mathematical Cryptology for Computer Scientists and Mathematicians" ,
Wayne Patterson, 1987, ISBN 0-8476-7438-X.
.sp
.IR "Password Security: A Case History" ,
R. Morris and Ken Thompson,
Communications of the ACM, vol. 22, pp. 594-597, Nov. 1979.
.sp
.IR "DES will be Totally Insecure within Ten Years" ,
M.E. Hellman, IEEE Spectrum, vol. 16, pp. 32-39, July 1979.
.SH BUGS
Dropping the
.I least
significant bit in each character of the argument to
.I des_setkey
is ridiculous.
.PP
The return value of
.I crypt
points to static data whose content is overwritten by each call.