\"      $NetBSD: crypt.3,v 1.35 2023/01/17 14:27:11 uwe 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 October 20, 2021
Dt CRYPT 3
Os
Sh NAME
Nm crypt ,
Nm setkey ,
Nm encrypt ,
Nm des_setkey ,
Nm des_cipher
Nd password hashing
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 hashing.
The password hashing scheme used by
Fn crypt
is dependent upon the contents of the
Tn 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
Ql _
character,
Tn DES
password hashing with a user specified number of
perturbations is selected.
If
Ar setting
begins with any other character,
Tn DES
password hashing with a fixed
number of perturbations is selected.
Ss DES password hashing
The
Tn DES
password hashing 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
Tn DES
case, the second argument to
Fn crypt
is a character array, 9 bytes in length, consisting of an underscore
Pq Ql _
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
Ql ./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
Dq 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
Tn DES
key as follows: the first group of 56 bits becomes the initial
Tn DES
key.
For each additional group, the XOR of the group bits and the encryption of the
Tn DES
key with itself becomes the next
Tn DES
key.
Then the final
Tn DES
key is used to perform
Ar count
cumulative encryptions of a 64-bit constant yielding a
Sq ciphertext .
The value returned is a
Tn NUL Ns -terminated
string, 20 bytes in length, consisting
of the
Ar setting
followed by the encoded 64-bit
Sq ciphertext .
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
Tn 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 password hashing
For the
Tn MD5
password hashing scheme, the version number (in this case
Ql 1 ) ,
Fa salt
and the hashed password are separated
by the
Ql $
character.
An encoded password hash looks like:
Pp
Dl "$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H"
Pp
The entire encoded MD5 password hash is passed as
Fa setting
for interpretation.
Ss Argon2 password hashing
Argon2 is a memory-hard password 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,
Va m_cost ( Li m ) ,
specifies the memory usage in
Tn KB .
Second,
Va t_cost ( Li t ) ,
specifies the number of iterations.
Third,
Va parallelism ( Li p )
specifies the number of threads.
This is currently ignored and one thread will always be used.
An encoded Argon2 password hash looks like:
Bd -literal -offset indent
$argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB$ \e
  yeYYrU/rh7E+LI2CAeHTSHVB3iO+OXiNIUHu6NPeTfo
Ed
Pp
containing five fields delimited by
Ql $ .
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.
Ss "Blowfish" bcrypt
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 hash.
The maximum password length is 72.
The final Blowfish password output is created by encrypting the string
Pp
Dl 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.
An encoded Blowfish password hash looks like:
Pp
Dl "$2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC"
Pp
The entire encoded Blowfish password hash is passed as
Fa setting
for interpretation.
Sh RETURN VALUES
The function
Fn crypt
returns a pointer to the encoded hash 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
Tn 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 "Argon2: the memory-hard function for password hashing and other applications"
%A Alex Biryukov
%A Daniel Dinu
%A Dmitry Khovratovich
%D 2017
%I University of Luxembourg
%U https://www.password-hashing.net/
Re
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
Li \*q:\*q
on error.
Pp
The term
Sq encryption
for password hashing does not match the terminology of modern
cryptography, but the name of the library is entrenched.
Pp
A library for password hashing has no business directly exposing the
Tn DES
cipher itself, which is obsolete and broken as a cipher.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.