manual/crypt.texi

   1 @node Cryptographic Functions, Debugging Support, System Configuration, Top
   2 @chapter Cryptographic Functions
   3 @c %MENU% A few functions to support cryptographic applications
   4
   5 @Theglibc{} includes only one type of special-purpose cryptographic
   6 functions; these allow use of a source of cryptographically strong
   7 pseudorandom numbers, if such a source is provided by the operating
   8 system.  Programs that need general-purpose cryptography should use
   9 a dedicated cryptography library, such as
  10 @uref{https://www.gnu.org/software/libgcrypt/,,libgcrypt}.
  11
  12 @menu
  13 * Unpredictable Bytes::         Randomness for cryptographic purposes.
  14 @end menu
  15
  16 @node Unpredictable Bytes
  17 @section Generating Unpredictable Bytes
  18 @cindex randomness source
  19 @cindex random numbers, cryptographic
  20 @cindex pseudo-random numbers, cryptographic
  21 @cindex cryptographic random number generator
  22 @cindex deterministic random bit generator
  23 @cindex CRNG
  24 @cindex CSPRNG
  25 @cindex DRBG
  26
  27 Cryptographic applications often need random data that will be as
  28 difficult as possible for a hostile eavesdropper to guess.
  29 The pseudo-random number generators provided by @theglibc{}
  30 (@pxref{Pseudo-Random Numbers}) are not suitable for this purpose.
  31 They produce output that is @emph{statistically} random, but fails to
  32 be @emph{unpredictable}.  Cryptographic applications require a
  33 @dfn{cryptographic random number generator} (CRNG), also known as a
  34 @dfn{cryptographically strong pseudo-random number generator} (CSPRNG)
  35 or a @dfn{deterministic random bit generator} (DRBG).
  36
  37 Currently, @theglibc{} does not provide a cryptographic random number
  38 generator, but it does provide functions that read cryptographically
  39 strong random data from a @dfn{randomness source} supplied by the
  40 operating system.  This randomness source is a CRNG at heart, but it
  41 also continually ``re-seeds'' itself from physical sources of
  42 randomness, such as electronic noise and clock jitter.  This means
  43 applications do not need to do anything to ensure that the random
  44 numbers it produces are different on each run.
  45
  46 The catch, however, is that these functions will only produce
  47 relatively short random strings in any one call.  Often this is not a
  48 problem, but applications that need more than a few kilobytes of
  49 cryptographically strong random data should call these functions once
  50 and use their output to seed a CRNG.
  51
  52 Most applications should use @code{getentropy}.  The @code{getrandom}
  53 function is intended for low-level applications which need additional
  54 control over blocking behavior.
  55
  56 @deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
  57 @standards{GNU, sys/random.h}
  58 @safety{@mtsafe{}@assafe{}@acsafe{}}
  59
  60 This function writes exactly @var{length} bytes of random data to the
  61 array starting at @var{buffer}.  @var{length} can be no more than 256.
  62 On success, it returns zero.  On failure, it returns @math{-1}, and
  63 @code{errno} is set to indicate the problem.  Some of the possible
  64 errors are listed below.
  65
  66 @table @code
  67 @item ENOSYS
  68 The operating system does not implement a randomness source, or does
  69 not support this way of accessing it.  (For instance, the system call
  70 used by this function was added to the Linux kernel in version 3.17.)
  71
  72 @item EFAULT
  73 The combination of @var{buffer} and @var{length} arguments specifies
  74 an invalid memory range.
  75
  76 @item EIO
  77 @var{length} is larger than 256, or the kernel entropy pool has
  78 suffered a catastrophic failure.
  79 @end table
  80
  81 A call to @code{getentropy} can only block when the system has just
  82 booted and the randomness source has not yet been initialized.
  83 However, if it does block, it cannot be interrupted by signals or
  84 thread cancellation.  Programs intended to run in very early stages of
  85 the boot process may need to use @code{getrandom} in non-blocking mode
  86 instead, and be prepared to cope with random data not being available
  87 at all.
  88
  89 The @code{getentropy} function is declared in the header file
  90 @file{sys/random.h}.  It is derived from OpenBSD.
  91 @end deftypefun
  92
  93 @deftypefun ssize_t getrandom (void *@var{buffer}, size_t @var{length}, unsigned int @var{flags})
  94 @standards{GNU, sys/random.h}
  95 @safety{@mtsafe{}@assafe{}@acsafe{}}
  96
  97 This function writes up to @var{length} bytes of random data to the
  98 array starting at @var{buffer}.  The @var{flags} argument should be
  99 either zero, or the bitwise OR of some of the following flags:
 100
 101 @table @code
 102 @item GRND_RANDOM
 103 Use the @file{/dev/random} (blocking) source instead of the
 104 @file{/dev/urandom} (non-blocking) source to obtain randomness.
 105
 106 If this flag is specified, the call may block, potentially for quite
 107 some time, even after the randomness source has been initialized.  If it
 108 is not specified, the call can only block when the system has just
 109 booted and the randomness source has not yet been initialized.
 110
 111 @item GRND_NONBLOCK
 112 Instead of blocking, return to the caller immediately if no data is
 113 available.
 114
 115 @item GRND_INSECURE
 116 Write random data that may not be cryptographically secure.
 117 @end table
 118
 119 Unlike @code{getentropy}, the @code{getrandom} function is a
 120 cancellation point, and if it blocks, it can be interrupted by
 121 signals.
 122
 123 On success, @code{getrandom} returns the number of bytes which have
 124 been written to the buffer, which may be less than @var{length}.  On
 125 error, it returns @math{-1}, and @code{errno} is set to indicate the
 126 problem.  Some of the possible errors are:
 127
 128 @table @code
 129 @item ENOSYS
 130 The operating system does not implement a randomness source, or does
 131 not support this way of accessing it.  (For instance, the system call
 132 used by this function was added to the Linux kernel in version 3.17.)
 133
 134 @item EAGAIN
 135 No random data was available and @code{GRND_NONBLOCK} was specified in
 136 @var{flags}.
 137
 138 @item EFAULT
 139 The combination of @var{buffer} and @var{length} arguments specifies
 140 an invalid memory range.
 141
 142 @item EINTR
 143 The system call was interrupted.  During the system boot process, before
 144 the kernel randomness pool is initialized, this can happen even if
 145 @var{flags} is zero.
 146
 147 @item EINVAL
 148 The @var{flags} argument contains an invalid combination of flags.
 149 @end table
 150
 151 The @code{getrandom} function is declared in the header file
 152 @file{sys/random.h}.  It is a GNU extension.
 153
 154 @end deftypefun