mirror of git://sourceware.org/git/glibc.git
155 lines
6.0 KiB
Plaintext
155 lines
6.0 KiB
Plaintext
@node Cryptographic Functions, Debugging Support, System Configuration, Top
|
|
@chapter Cryptographic Functions
|
|
@c %MENU% A few functions to support cryptographic applications
|
|
|
|
@Theglibc{} includes only one type of special-purpose cryptographic
|
|
functions; these allow use of a source of cryptographically strong
|
|
pseudorandom numbers, if such a source is provided by the operating
|
|
system. Programs that need general-purpose cryptography should use
|
|
a dedicated cryptography library, such as
|
|
@uref{https://www.gnu.org/software/libgcrypt/,,libgcrypt}.
|
|
|
|
@menu
|
|
* Unpredictable Bytes:: Randomness for cryptographic purposes.
|
|
@end menu
|
|
|
|
@node Unpredictable Bytes
|
|
@section Generating Unpredictable Bytes
|
|
@cindex randomness source
|
|
@cindex random numbers, cryptographic
|
|
@cindex pseudo-random numbers, cryptographic
|
|
@cindex cryptographic random number generator
|
|
@cindex deterministic random bit generator
|
|
@cindex CRNG
|
|
@cindex CSPRNG
|
|
@cindex DRBG
|
|
|
|
Cryptographic applications often need random data that will be as
|
|
difficult as possible for a hostile eavesdropper to guess.
|
|
The pseudo-random number generators provided by @theglibc{}
|
|
(@pxref{Pseudo-Random Numbers}) are not suitable for this purpose.
|
|
They produce output that is @emph{statistically} random, but fails to
|
|
be @emph{unpredictable}. Cryptographic applications require a
|
|
@dfn{cryptographic random number generator} (CRNG), also known as a
|
|
@dfn{cryptographically strong pseudo-random number generator} (CSPRNG)
|
|
or a @dfn{deterministic random bit generator} (DRBG).
|
|
|
|
Currently, @theglibc{} does not provide a cryptographic random number
|
|
generator, but it does provide functions that read cryptographically
|
|
strong random data from a @dfn{randomness source} supplied by the
|
|
operating system. This randomness source is a CRNG at heart, but it
|
|
also continually ``re-seeds'' itself from physical sources of
|
|
randomness, such as electronic noise and clock jitter. This means
|
|
applications do not need to do anything to ensure that the random
|
|
numbers it produces are different on each run.
|
|
|
|
The catch, however, is that these functions will only produce
|
|
relatively short random strings in any one call. Often this is not a
|
|
problem, but applications that need more than a few kilobytes of
|
|
cryptographically strong random data should call these functions once
|
|
and use their output to seed a CRNG.
|
|
|
|
Most applications should use @code{getentropy}. The @code{getrandom}
|
|
function is intended for low-level applications which need additional
|
|
control over blocking behavior.
|
|
|
|
@deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
|
|
@standards{GNU, sys/random.h}
|
|
@safety{@mtsafe{}@assafe{}@acsafe{}}
|
|
|
|
This function writes exactly @var{length} bytes of random data to the
|
|
array starting at @var{buffer}. @var{length} can be no more than 256.
|
|
On success, it returns zero. On failure, it returns @math{-1}, and
|
|
@code{errno} is set to indicate the problem. Some of the possible
|
|
errors are listed below.
|
|
|
|
@table @code
|
|
@item ENOSYS
|
|
The operating system does not implement a randomness source, or does
|
|
not support this way of accessing it. (For instance, the system call
|
|
used by this function was added to the Linux kernel in version 3.17.)
|
|
|
|
@item EFAULT
|
|
The combination of @var{buffer} and @var{length} arguments specifies
|
|
an invalid memory range.
|
|
|
|
@item EIO
|
|
@var{length} is larger than 256, or the kernel entropy pool has
|
|
suffered a catastrophic failure.
|
|
@end table
|
|
|
|
A call to @code{getentropy} can only block when the system has just
|
|
booted and the randomness source has not yet been initialized.
|
|
However, if it does block, it cannot be interrupted by signals or
|
|
thread cancellation. Programs intended to run in very early stages of
|
|
the boot process may need to use @code{getrandom} in non-blocking mode
|
|
instead, and be prepared to cope with random data not being available
|
|
at all.
|
|
|
|
The @code{getentropy} function is declared in the header file
|
|
@file{sys/random.h}. It is derived from OpenBSD.
|
|
@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 up to @var{length} bytes of random data to the
|
|
array starting at @var{buffer}. The @var{flags} argument should be
|
|
either zero, or the bitwise OR of some of the following flags:
|
|
|
|
@table @code
|
|
@item GRND_RANDOM
|
|
Use the @file{/dev/random} (blocking) source instead of the
|
|
@file{/dev/urandom} (non-blocking) source to obtain randomness.
|
|
|
|
If this flag is specified, the call may block, potentially for quite
|
|
some time, even after the randomness source has been initialized. If it
|
|
is not specified, the call can only block when the system has just
|
|
booted and the randomness source has not yet been initialized.
|
|
|
|
@item GRND_NONBLOCK
|
|
Instead of blocking, return to the caller immediately if no data is
|
|
available.
|
|
|
|
@item GRND_INSECURE
|
|
Write random data that may not be cryptographically secure.
|
|
@end table
|
|
|
|
Unlike @code{getentropy}, the @code{getrandom} function is a
|
|
cancellation point, and if it blocks, it can be interrupted by
|
|
signals.
|
|
|
|
On success, @code{getrandom} returns the number of bytes which have
|
|
been written to the buffer, which may be less than @var{length}. On
|
|
error, it returns @math{-1}, and @code{errno} is set to indicate the
|
|
problem. Some of the possible errors are:
|
|
|
|
@table @code
|
|
@item ENOSYS
|
|
The operating system does not implement a randomness source, or does
|
|
not support this way of accessing it. (For instance, the system call
|
|
used by this function was added to the Linux kernel in version 3.17.)
|
|
|
|
@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
|
|
|
|
The @code{getrandom} function is declared in the header file
|
|
@file{sys/random.h}. It is a GNU extension.
|
|
|
|
@end deftypefun
|