September 4, 2005 CRYPT 3

### NAME

crypt, setkey, encrypt, des_setkey, des_cipher - password encryption

### LIBRARY

Crypt Library (libcrypt, -lcrypt)

### SYNOPSIS

```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`)
```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(3), 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 and NULL on failure. 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)

### 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.