path: root/manual/crypt.texi

@node Cryptographic Functions, Debugging Support, System Configuration, Top
@chapter Cryptographic Functions
@c %MENU% Password storage and strongly unpredictable bytes

@menu
* crypt::                       A one-way function for passwords.
* Unpredictable Bytes::         Randomness for cryptography purposes.
@end menu

@node crypt
@section Encrypting Passwords

On many systems, it is unnecessary to have any kind of user
authentication; for instance, a workstation which is not connected to a
network probably does not need any user authentication, because to use
the machine an intruder must have physical access.

Sometimes, however, it is necessary to be sure that a user is authorized
to use some service a machine provides---for instance, to log in as a
particular user id (@pxref{Users and Groups}).  One traditional way of
doing this is for each user to choose a secret @dfn{password}; then, the
system can ask someone claiming to be a user what the user's password
is, and if the person gives the correct password then the system can
grant the appropriate privileges.

If all the passwords are just stored in a file somewhere, then this file
has to be very carefully protected.  To avoid this, passwords are run
through a @dfn{one-way function}, a function which makes it difficult to
work out what its input was by looking at its output, before storing in
the file.

@Theglibc{} provides a one-way function that is compatible with
the behavior of the @code{crypt} function introduced in FreeBSD 2.0.
It supports two one-way algorithms: one based on the MD5
message-digest algorithm that is compatible with modern BSD systems,
and the other based on the Data Encryption Standard (DES) that is
compatible with Unix systems.

@deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
@standards{BSD, crypt.h}
@standards{SVID, crypt.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
@c Besides the obvious problem of returning a pointer into static
@c storage, the DES initializer takes an internal lock with the usual
@c set of problems for AS- and AC-Safety.  The FIPS mode checker and the
@c NSS implementations of may leak file descriptors if canceled.  The
@c The MD5, SHA256 and SHA512 implementations will malloc on long keys,
@c and NSS relies on dlopening, which brings about another can of worms.

The @code{crypt} function takes a password, @var{key}, as a string, and
a @var{salt} character array which is described below, and returns a
printable ASCII string which starts with another salt.  It is believed
that, given the output of the function, the best way to find a @var{key}
that will produce that output is to guess values of @var{key} until the
original value of @var{key} is found.

The @var{salt} parameter does two things.  Firstly, it selects which
algorithm is used, the MD5-based one or the DES-based one.  Secondly, it
makes life harder for someone trying to guess passwords against a file
containing many passwords; without a @var{salt}, an intruder can make a
guess, run @code{crypt} on it once, and compare the result with all the
passwords.  With a @var{salt}, the intruder must run @code{crypt} once
for each different salt.

For the MD5-based algorithm, the @var{salt} should consist of the string
@code{$1$}, followed by up to 8 characters, terminated by either
another @code{$} or the end of the string.  The result of @code{crypt}
will be the @var{salt}, followed by a @code{$} if the salt didn't end
with one, followed by 22 characters from the alphabet
@code{./0-9A-Za-z}, up to 34 characters total.  Every character in the
@var{key} is significant.

For the DES-based algorithm, the @var{salt} should consist of two
characters from the alphabet @code{./0-9A-Za-z}, and the result of
@code{crypt} will be those two characters followed by 11 more from the
same alphabet, 13 in total.  Only the first 8 characters in the
@var{key} are significant.

The MD5-based algorithm has no limit on the useful length of the
password used, and is slightly more secure.  It is therefore preferred
over the DES-based algorithm.

When the user enters their password for the first time, the @var{salt}
should be set to a new string which is reasonably random.  To verify a
password against the result of a previous call to @code{crypt}, pass
the result of the previous call as the @var{salt}.
@end deftypefun

@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
@standards{GNU, crypt.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
@c Compared with crypt, this function fixes the @mtasurace:crypt
@c problem, but nothing else.

The @code{crypt_r} function does the same thing as @code{crypt}, but
takes an extra parameter which includes space for its result (among
other things), so it can be reentrant.  @code{data@w{->}initialized} must be
cleared to zero before the first time @code{crypt_r} is called.

The @code{crypt_r} function is a GNU extension.
@end deftypefun

The @code{crypt} and @code{crypt_r} functions are prototyped in the
header @file{crypt.h}.

The following short program is an example of how to use @code{crypt} the
first time a password is entered.  Note that the @var{salt} generation
is just barely acceptable; in particular, it is not unique between
machines, and in many applications it would not be acceptable to let an
attacker know what time the user's password was last set.

@smallexample
@include genpass.c.texi
@end smallexample

The next program shows how to verify a password.  It prompts the user
for a password and prints ``Access granted.'' if the user types
@code{GNU libc manual}.

@smallexample
@include testpass.c.texi
@end smallexample

@node Unpredictable Bytes
@section Generating Unpredictable Bytes

Some cryptographic applications (such as session key generation) need
unpredictable bytes.

In general, application code should use a deterministic random bit
generator, which could call the @code{getentropy} function described
below internally to obtain randomness to seed the generator.  The
@code{getrandom} function is intended for low-level applications which
need additional control over the blocking behavior.

@deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
@standards{GNU, sys/random.h}
@safety{@mtsafe{}@assafe{}@acsafe{}}

This function writes @var{length} bytes of random data to the array
starting at @var{buffer}, which must be at most 256 bytes long.  The
function returns zero on success.  On failure, it returns @code{-1} and
@code{errno} is updated accordingly.

The @code{getentropy} function is declared in the header file
@file{sys/random.h}.  It is derived from OpenBSD.

The @code{getentropy} function is not a cancellation point.  A call to
@code{getentropy} can block if the system has just booted and the kernel
entropy pool has not yet been initialized.  In this case, the function
will keep blocking even if a signal arrives, and return only after the
entropy pool has been initialized.

The @code{getentropy} function can fail with several errors, some of
which are listed below.

@table @code
@item ENOSYS
The kernel does not implement the required system call.

@item EFAULT
The combination of @var{buffer} and @var{length} arguments specifies
an invalid memory range.

@item EIO
More than 256 bytes of randomness have been requested, or the buffer
could not be overwritten with random data for an unspecified reason.

@end table

@end deftypefun

@deftypefun ssize_t getrandom (void *@var{buffer}, size_t @var{length}, unsigned int @var{flags})
@standards{GNU, sys/random.h}
@safety{@mtsafe{}@assafe{}@acsafe{}}

This function writes @var{length} bytes of random data to the array
starting at @var{buffer}.  On success, this function returns the number
of bytes which have been written to the buffer (which can be less than
@var{length}).  On error, @code{-1} is returned, and @code{errno} is
updated accordingly.

The @code{getrandom} function is declared in the header file
@file{sys/random.h}.  It is a GNU extension.

The following flags are defined for the @var{flags} argument:

@table @code
@item GRND_RANDOM
Use the @file{/dev/random} (blocking) pool instead of the
@file{/dev/urandom} (non-blocking) pool to obtain randomness.  If the
@code{GRND_RANDOM} flag is specified, the @code{getrandom} function can
block even after the randomness source has been initialized.

@item GRND_NONBLOCK
Instead of blocking, return to the caller immediately if no data is
available.
@end table

The @code{getrandom} function is a cancellation point.

Obtaining randomness from the @file{/dev/urandom} pool (i.e., a call
without the @code{GRND_RANDOM} flag) can block if the system has just
booted and the pool has not yet been initialized.

The @code{getrandom} function can fail with several errors, some of
which are listed below.  In addition, the function may not fill the
buffer completely and return a value less than @var{length}.

@table @code
@item ENOSYS
The kernel does not implement the @code{getrandom} system call.

@item EAGAIN
No random data was available and @code{GRND_NONBLOCK} was specified in
@var{flags}.

@item EFAULT
The combination of @var{buffer} and @var{length} arguments specifies
an invalid memory range.

@item EINTR
The system call was interrupted.  During the system boot process, before
the kernel randomness pool is initialized, this can happen even if
@var{flags} is zero.

@item EINVAL
The @var{flags} argument contains an invalid combination of flags.
@end table

@end deftypefun