Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


CRYPT(3)                   Library Functions Manual                   CRYPT(3)

NAME
     crypt, setkey, encrypt, des_setkey, des_cipher - password hashing

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 hashing.  The password hashing
     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 password hashing with a user specified number of
     perturbations is selected.  If setting begins with any other character,
     DES password hashing with a fixed number of perturbations is selected.

   DES password hashing
     The DES password hashing 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 yielding a `ciphertext'.  The value returned is a
     NUL-terminated string, 20 bytes in length, consisting of the setting
     followed by the encoded 64-bit `ciphertext'.

     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 password hashing
     For the MD5 password hashing scheme, the version number (in this case
     `1'), salt and the hashed password are separated by the `$' character.
     An encoded password hash looks like:

           $1$2qGr5PPQ$eT08WBFev3RPLNChixg0H

     The entire encoded MD5 password hash is passed as setting for
     interpretation.

   Argon2 password hashing
     Argon2 is a memory-hard password hashing algorithm.  crypt() provides all
     three variants: argon2i, argon2d, and argon2id.  It is recommended to use
     argon2id, which provides a hybrid combination using argon2i on the first
     pass, and argon2d on the remaining passes.  We parameterize on three
     variables.  First, m_cost (m), specifies the memory usage in KB.  Second,
     t_cost (t), specifies the number of iterations.  Third, parallelism (p)
     specifies the number of threads.  This is currently ignored and one
     thread will always be used.  An encoded Argon2 password hash looks like:

           $argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB$ \
              yeYYrU/rh7E+LI2CAeHTSHVB3iO+OXiNIUHu6NPeTfo

     containing five fields delimited by `$'.  The fields, in order, are
     variant name, version, parameter set, 128-bit salt, and Argon2 hash
     encoded in base64.  The entire encoded Argon2 password hash is required
     to be processed correctly.

   Blowfish bcrypt
     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 hash.  The maximum password length is 72.  The final
     Blowfish password output 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.  An encoded Blowfish
     password hash looks like:

           $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC

     The entire encoded Blowfish password hash is passed as setting for
     interpretation.

RETURN VALUES
     The function crypt() returns a pointer to the encoded hash 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)

     Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich, Argon2: the memory-
     hard function for password hashing and other applications, University of
     Luxembourg, https://www.password-hashing.net/, 2017.

     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.

     The term `encryption' for password hashing does not match the terminology
     of modern cryptography, but the name of the library is entrenched.

     A library for password hashing has no business directly exposing the DES
     cipher itself, which is obsolete and broken as a cipher.

NetBSD 10.99                   October 20, 2021                   NetBSD 10.99