CRYPT(3) Library Functions Manual CRYPT(3)
crypt, setkey, encrypt, des_setkey, des_cipher -- password encryption
Crypt Library (libcrypt, -lcrypt)
crypt(const char *key, const char *setting);
encrypt(char *block, int flag);
des_setkey(const char *key);
des_cipher(const char *in, char *out, long salt, int count);
setkey(const char *key);
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.
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
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
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.
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:
The entire password string is passed as setting for interpretation.
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
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:
The whole Blowfish password string is passed as setting for
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 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.
login(1), passwd(1), pwhash(1), getpass(3), md5(3), passwd(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.
A rotor-based crypt() function appeared in Version 6 AT&T UNIX. The
current style crypt() first appeared in Version 7 AT&T UNIX.
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 crypt() returned either NULL or: on error.
NetBSD 6.1.5 January 1, 2012 NetBSD 6.1.5