NAME
crypt,
setkey,
encrypt,
des_setkey,
des_cipher —
password encryption
LIBRARY
Crypt Library (libcrypt, -lcrypt)
SYNOPSIS
#include <unistd.h>
char *
crypt(
const char
*key,
const char
*setting);
int
encrypt(
char
*block,
int flag);
int
des_setkey(
const
char *key);
int
des_cipher(
const
char *in,
char *out,
long salt,
int count);
#include <stdlib.h>
int
setkey(
const char
*key);
DESCRIPTION
The
crypt() function performs password encryption. The
encryption scheme used by
crypt() is dependent upon the
contents of the
NUL
-terminated string
setting. If it begins with a string character
(‘
$
’) and a number then a different
algorithm is used depending on the number. At the moment a
‘
$1
’ chooses MD5 hashing and a
‘
$2
’ chooses Blowfish hashing; see below
for more information. If
setting begins with the ``_''
character, DES encryption with a user specified number of perturbations is
selected. If
setting begins with any other character,
DES encryption with a fixed number of perturbations is selected.
DES encryption
The DES encryption scheme is derived from the NBS Data Encryption Standard.
Additional code has been added to deter key search attempts and to use
stronger hashing algorithms. In the DES case, the second argument to
crypt() 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
count and the
salt are encoded with 6 bits per character, least
significant bits first. The values 0 to 63 are encoded by the characters
``./0-9A-Za-z'', respectively.
The
salt is used to induce disorder in to the DES
algorithm in one of 16777216 possible ways (specifically, if bit
i of the
salt is set then bits
i and
i+24 are swapped in the DES ``E''
box output). The
key is divided into groups of 8
characters (a short final group is null-padded) and the low-order 7 bits of
each character (56 bits per group) are used to form the DES key as follows:
the first group of 56 bits becomes the initial DES key. For each additional
group, the XOR of the group bits and the encryption of the DES key with itself
becomes the next DES key. Then the final DES key is used to perform
count cumulative encryptions of a 64-bit constant. The
value returned is a
NUL
-terminated string, 20 bytes in
length, consisting of the
setting followed by the
encoded 64-bit encryption.
For compatibility with historical versions of
crypt(), the
setting may consist of 2 bytes of salt, encoded as
above, in which case an iteration
count of 25 is used,
fewer perturbations of DES are available, at most 8 characters of
key are used, and the returned value is a
NUL
-terminated string 13 bytes in length.
The functions
encrypt(),
setkey(),
des_setkey() and
des_cipher() allow
limited access to the DES algorithm itself. The
key
argument to
setkey() is a 64 character array of binary
values (numeric 0 or 1). A 56-bit key is derived from this array by dividing
the array into groups of 8 and ignoring the last bit in each group.
The
encrypt() argument
block is also a
64 character array of binary values. If the value of
flag is 0, the argument
block is
encrypted, otherwise it is decrypted. The encryption or decryption is returned
in the original array
block after using the key
specified by
setkey() to process it.
The
des_setkey() and
des_cipher() functions
are faster but less portable than
setkey() and
encrypt(). The argument to
des_setkey() is
a character array of length 8. The
least significant bit in
each character is ignored and the next 7 bits of each character are
concatenated to yield a 56-bit key. The function
des_cipher() encrypts (or decrypts if
count is negative) the 64-bits stored in the 8
characters at
in using
abs(3) of
count iterations of DES and stores the 64-bit result in
the 8 characters at
out. The
salt
specifies perturbations to DES as described above.
MD5 encryption
For the MD5 encryption scheme, the version number (in this case ``1''),
salt and the hashed password are separated by the ``$''
character. A valid password looks like this:
``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
The entire password string is passed as
setting for
interpretation.
Blowfish crypt
The Blowfish version of
crypt() has 128 bits of
salt in order to make building dictionaries of common
passwords space consuming. The initial state of the Blowfish cipher is
expanded using the
salt and the
password repeating the process a variable number of
rounds, which is encoded in the password string. The maximum password length
is 72. The final Blowfish password entry is created by encrypting the string
“OrpheanBeholderScryDoubt”
with the Blowfish state 64 times.
The version number, the logarithm of the number of rounds and the concatenation
of salt and hashed password are separated by the
‘
$
’ character. An encoded ‘8’
would specify 256 rounds. A valid Blowfish password looks like this:
“$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC”.
The whole Blowfish password string is passed as
setting
for interpretation.
RETURN VALUES
The function
crypt() returns a pointer to the encrypted value
on success.
The behavior of
crypt() on errors isn't well standardized.
Some implementations simply can't fail (unless the process dies, in which case
they obviously can't return), others return
NULL
or a
fixed string. Most implementations don't set
errno, but
some do.
Version 2 of the Single UNIX Specification
(“SUSv2”) specifies only returning
NULL
and setting
errno as a
valid behavior, and defines only one possible error
(
ENOSYS
, “The functionality is not supported on
this implementation.”) Unfortunately, most existing applications aren't
prepared to handle
NULL
returns from
crypt(). The description below corresponds to this
implementation of
crypt() only. The behavior may change to
match standards, other implementations or existing applications.
crypt() may only fail (and return) when passed an invalid or
unsupported
setting, in which case it returns a pointer
to a magic string that is shorter than 13 characters and is guaranteed to
differ from
setting. This behavior is safe for older
applications which assume that
crypt() can't fail, when both
setting new passwords and authenticating against existing password hashes.
The functions
setkey(),
encrypt(),
des_setkey(), and
des_cipher() return 0 on
success and 1 on failure. Historically, the functions
setkey() and
encrypt() did not return any
value. They have been provided return values primarily to distinguish
implementations where hardware support is provided but not available or where
the DES encryption is not available due to the usual political silliness.
SEE ALSO
login(1),
passwd(1),
pwhash(1),
getpass(3),
md5(3),
passwd(5),
passwd.conf(5)
Wayne Patterson,
Mathematical Cryptology for Computer Scientists and
Mathematicians, ISBN 0-8476-7438-X,
1987.
R. Morris and Ken
Thompson, Password Security: A Case History,
Communications of the ACM, vol.
22, pp. 594-597, Nov.
1979.
M.E. Hellman, DES
will be Totally Insecure within Ten Years, IEEE
Spectrum, vol. 16, pp.
32-39, July 1979.
HISTORY
A rotor-based
crypt() function appeared in
Version 6 AT&T UNIX. The current style
crypt() first appeared in
Version 7
AT&T UNIX.
BUGS
Dropping the
least significant bit in each character of the
argument to
des_setkey() is ridiculous.
The
crypt() function leaves its result in an internal static
object and returns a pointer to that object. Subsequent calls to
crypt() will modify the same object.
Before
NetBSD 6.0 crypt() returned
either
NULL
or
:
on
error.