1 @node Cryptographic Functions, Debugging Support, System Configuration, Top
2 @chapter Cryptographic Functions
3 @c %MENU% A few functions to support cryptographic applications
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}.
13 * Unpredictable Bytes:: Randomness for cryptographic purposes.
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
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).
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.
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.
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.
56 @deftypefun int getentropy (void *@var{buffer}, size_t @var{length})
57 @standards{GNU, sys/random.h}
58 @safety{@mtsafe{}@assafe{}@acsafe{}}
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.
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.)
73 The combination of @var{buffer} and @var{length} arguments specifies
74 an invalid memory range.
77 @var{length} is larger than 256, or the kernel entropy pool has
78 suffered a catastrophic failure.
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
89 The @code{getentropy} function is declared in the header file
90 @file{sys/random.h}. It is derived from OpenBSD.
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{}}
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:
103 Use the @file{/dev/random} (blocking) source instead of the
104 @file{/dev/urandom} (non-blocking) source to obtain randomness.
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.
112 Instead of blocking, return to the caller immediately if no data is
116 Write random data that may not be cryptographically secure.
119 Unlike @code{getentropy}, the @code{getrandom} function is a
120 cancellation point, and if it blocks, it can be interrupted by
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:
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.)
135 No random data was available and @code{GRND_NONBLOCK} was specified in
139 The combination of @var{buffer} and @var{length} arguments specifies
140 an invalid memory range.
143 The system call was interrupted. During the system boot process, before
144 the kernel randomness pool is initialized, this can happen even if
148 The @var{flags} argument contains an invalid combination of flags.
151 The @code{getrandom} function is declared in the header file
152 @file{sys/random.h}. It is a GNU extension.