NetBSD/lib/libcrypt/crypt.3

.\"	$NetBSD: crypt.3,v 1.29 2019/10/21 05:16:51 wiz Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)crypt.3	8.2 (Berkeley) 12/11/93
.\"
.Dd January 1, 2012
.Dt CRYPT 3
.Os
.Sh NAME
.Nm crypt ,
.Nm setkey ,
.Nm encrypt ,
.Nm des_setkey ,
.Nm des_cipher
.Nd password encryption
.Sh LIBRARY
.Lb libcrypt
.Sh SYNOPSIS
.In unistd.h
.Ft "char *"
.Fn crypt "const char *key" "const char *setting"
.Ft int
.Fn encrypt "char *block" "int flag"
.Ft int
.Fn des_setkey "const char *key"
.Ft int
.Fn des_cipher "const char *in" "char *out" "long salt" "int count"
.In stdlib.h
.Ft int
.Fn setkey "const char *key"
.Sh DESCRIPTION
The
.Fn crypt
function
performs password encryption.
The encryption scheme used by
.Fn crypt
is dependent upon the contents of the
.Dv NUL Ns -terminated
string
.Ar setting .
If it begins
with a string character
.Pq Ql $
and a number then a different algorithm is used depending on the number.
At the moment a
.Ql $1
chooses MD5 hashing and a
.Ql $2
chooses Blowfish hashing; see below for more information.
If
.Ar setting
begins with the ``_'' character, DES encryption with a user specified number
of perturbations is selected.
If
.Ar setting
begins with any other character, DES encryption with a fixed number
of perturbations is selected.
.Ss DES encryption
The DES encryption scheme is derived from the
.Tn 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
.Fn 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
.Fa count
and the
.Fa 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.
.Pp
The
.Fa salt
is used to induce disorder in to the
.Tn DES
algorithm
in one of 16777216
possible ways
(specifically, if bit
.Em i
of the
.Ar salt
is set then bits
.Em i
and
.Em i+24
are swapped in the
.Tn DES
``E'' box output).
The
.Ar 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
.Ar count
cumulative encryptions of a 64-bit constant.
The value returned is a
.Dv NUL Ns -terminated
string, 20 bytes in length, consisting
of the
.Ar setting
followed by the encoded 64-bit encryption.
.Pp
For compatibility with historical versions of
.Fn crypt ,
the
.Ar setting
may consist of 2 bytes of salt, encoded as above, in which case an
iteration
.Ar count
of 25 is used, fewer perturbations of
.Tn DES
are available, at most 8
characters of
.Ar key
are used, and the returned value is a
.Dv NUL Ns -terminated
string 13 bytes in length.
.Pp
The
functions
.Fn encrypt ,
.Fn setkey ,
.Fn des_setkey
and
.Fn des_cipher
allow limited access to the
.Tn DES
algorithm itself.
The
.Ar key
argument to
.Fn 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.
.Pp
The
.Fn encrypt
argument
.Fa block
is also a 64 character array of
binary values.
If the value of
.Fa flag
is 0,
the argument
.Fa block
is encrypted, otherwise it
is decrypted.
The encryption or decryption is returned in the original
array
.Fa block
after using the
key specified
by
.Fn setkey
to process it.
.Pp
The
.Fn des_setkey
and
.Fn des_cipher
functions are faster but less portable than
.Fn setkey
and
.Fn encrypt .
The argument to
.Fn des_setkey
is a character array of length 8.
The
.Em 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
.Fn des_cipher
encrypts (or decrypts if
.Fa count
is negative) the 64-bits stored in the 8 characters at
.Fa in
using
.Xr abs 3
of
.Fa count
iterations of
.Tn DES
and stores the 64-bit result in the 8 characters at
.Fa out .
The
.Fa salt
specifies perturbations to
.Tn DES
as described above.
.Ss MD5 encryption
For the
.Tn MD5
encryption scheme, the version number (in this case ``1''),
.Fa salt
and the hashed password are separated
by the ``$'' character.
A valid password looks like this:
.Pp
``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
.Pp
The entire password string is passed as
.Fa setting
for interpretation.
.Ss Argon2 encryption
Argon2 is a memory-hard hashing algorithm.
.Fn 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), specfies the number of iterations.
Third, parallelism (p) specifies the number of threads.
A valid Argon2 encoded password looks similar to
.Bd -literal
$argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB$ \
   yeYYrU/rh7E+LI2CAeHTSHVB3iO+OXiNIUHu6NPeTfo
.Ed
containing five fields delimited by '$'.
The fields, in order, are variant name, version, parameter set,
128-bit salt, and encoded password.
The complete password string is required to be processed correctly.
.Ss "Blowfish" crypt
The
.Tn Blowfish
version of
.Fn crypt
has 128 bits of
.Fa salt
in order to make building dictionaries of common passwords space consuming.
The initial state of the
.Tn Blowfish
cipher is expanded using the
.Fa salt
and the
.Fa 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
.Pp
.Dq OrpheanBeholderScryDoubt
.Pp
with the
.Tn Blowfish
state 64 times.
.Pp
The version number, the logarithm of the number of rounds and
the concatenation of salt and hashed password are separated by the
.Ql $
character.
An encoded
.Sq 8
would specify 256 rounds.
A valid Blowfish password looks like this:
.Pp
.Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
.Pp
The whole Blowfish password string is passed as
.Fa setting
for interpretation.
.Sh RETURN VALUES
The function
.Fn crypt
returns a pointer to the encrypted value on success.
.Pp
The behavior of
.Fn 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
.Dv NULL
or a fixed string.
Most implementations don't set
.Va errno ,
but some do.
.St -susv2
specifies
only returning
.Dv NULL
and setting
.Va errno
as a valid behavior, and defines
only one possible error
.Er ( ENOSYS ,
.Dq "The functionality is not supported on this implementation." )
Unfortunately, most existing applications aren't prepared to handle
.Dv NULL
returns from
.Fn crypt .
The description below corresponds to this implementation of
.Fn crypt
only.
The behavior may change to match standards, other implementations or existing
applications.
.Pp
.Fn crypt
may only fail (and return) when passed an invalid or unsupported
.Fa setting ,
in which case it returns a pointer to a magic string that is shorter than 13
characters and is guaranteed to differ from
.Fa setting .
This behavior is safe for older applications which assume that
.Fn crypt
can't fail, when both setting new passwords and authenticating against
existing password hashes.
.Pp
The functions
.Fn setkey ,
.Fn encrypt ,
.Fn des_setkey ,
and
.Fn des_cipher
return 0 on success and 1 on failure.
Historically, the functions
.Fn setkey
and
.Fn 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.
.Sh SEE ALSO
.Xr login 1 ,
.Xr passwd 1 ,
.Xr pwhash 1 ,
.Xr getpass 3 ,
.Xr md5 3 ,
.Xr passwd 5 ,
.Xr passwd.conf 5
.Rs
.%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
.%A Wayne Patterson
.%D 1987
.%N ISBN 0-8476-7438-X
.Re
.Rs
.%T "Password Security: A Case History"
.%A R. Morris
.%A Ken Thompson
.%J "Communications of the ACM"
.%V vol. 22
.%P pp. 594-597
.%D Nov. 1979
.Re
.Rs
.%T "DES will be Totally Insecure within Ten Years"
.%A M.E. Hellman
.%J "IEEE Spectrum"
.%V vol. 16
.%P pp. 32-39
.%D July 1979
.Re
.Sh HISTORY
A rotor-based
.Fn crypt
function appeared in
.At v6 .
The current style
.Fn crypt
first appeared in
.At v7 .
.Sh BUGS
Dropping the
.Em least
significant bit in each character of the argument to
.Fn des_setkey
is ridiculous.
.Pp
The
.Fn crypt
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.Fn crypt
will modify the same object.
.Pp
Before
.Nx 6.0
.Fn crypt
returned either
.Dv NULL
or
.Dv \&:
on error.