.\" Copyright (c) 2017 - 2022 by Stephan Mueller (smueller@chronox.de)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" License.
.TH JITTERENTROPY-RNGD 1  2017-02-11
.SH NAME
jitterentropy-rngd \- CPU Jitter Random Number Generator Daemon
.SH SYNOPSIS
.B jitterentropy-rngd
[\fI\,OPTION\/\fR]
.SH DESCRIPTION
The
.I jitterentropy-rngd
application provides a source of good entropy by collecting CPU
execution time jitter. The collected entropy is injected into
the Linux kernel
.IR /dev/random
device using the
.IR RNDADDENTROPY
ioctl described in \fBrandom\fR(4).
.LP
The entropy in the CPU execution time jitter is magnified by
the CPU Jitter Random Number Generator. The CPU Jitter Random
Number Generator uses the CPU execution timing jitter to
generate a bit stream which complies with different statistical
measurements that determine the bit stream is random.
.LP
The CPU Jitter Random Number Generator works equally well in
virtualized environments as well as on bare-metal provided
a high-resolution timer is made available with the
.BR clock_gettime ()
function. The currently used timer can be checked by reading
the file
.IR /sys/devices/system/clocksource/clocksource0/current_clocksource .
If the clock source shall be changed, one of the available
clock sources listed in the file
.IR /sys/devices/system/clocksource/clocksource0/available_clocksource
can be written into the mentioned
.IR current_clocksource
file and the kernel immediately changes the use clock.
.LP
The CPU Jitter Random Number Generator unconditionally
injects 256 bits of entropy into the Linux kernel during
startup time before it daemonizes. Thus, when the invocation
of the
.IR jitterentropy-rngd
returns, the Linux kernel is seeded with at least 256 bits
of entropy. The reader should consider that the Linux kernel
performs a schedule operation during the injection of data
which implies that immediately after starting the
.IR jitterentropy-rngd
the kernel may still complain about insufficient entropy
available for
.IR /dev/urandom .
.LP
In addition, the
.IR jitterentropy-rngd
injects 256 bits of entropy every 10 minutes unconditionally
irrespective whether the kernel has sufficient entropy or not.
.LP
The following options are supported when invoking
.IR jitterentropy-rngd :
.TP
\fB\-v\fR, \fB\-\-verbose\fR
enable a verbose operation of the daemon. Using this option
multiple times increases the verbosity. Using this option
implies that the
.IR jitterentropy-rngd
will not daemonize.
.TP
\fB\-p\fR, \fB\-\-pid\fR [\fI\,FILE\/\fR]
triggers the creation of a PID file at the given location.
.TP
\fB\-h\fR, \fB\-\-help\fR
displays the help text
.TP
\fB\-\-version\fR
returns the version number of the
.IR jitterentropy-rngd .
.TP
\fB\-s\fR, \fB\-\-sp800-90b\fR
triggers a specific seeding strategy of the kernel /dev/random
device to insert entropy that ensures the ChaCha20 DRNG behind
/dev/random receives 256 bits of entropy as defined by SP800-90B.
.TP
\fB\-f\fR, \fB\-\-flags\fR [\fI\,FLAGS\/\fR]
allows specifying the flags value documented with
.IR jitterentropy(3)
when allocating the Jitter RNG.
.TP
\fB\-o\fR, \fB\-\-osr\fR [\fI\,OSR\/\fR]
allows specifying the oversampling rate (OSR) as documented with
.IR jitterentropy(3)
when allocating the Jitter RNG.
.PP
.SH NOTES
The
.IR jitterentropy-rngd
does not perform write operations on any file system object.
Thus, it can be executed on a fully read-only mounted file
system.
.LP
The random bit stream generated by
.IR jitterentropy-rngd
is NOT processed by a cryptographically secure whitening
function. Nonetheless, it is believed that the output
can be used as a source for cryptographically secure
key material or other cryptographically sensitive data.
.PP
.SH SEE ALSO
\fBrandom\fR(4)
\fBclock_gettime\fR(2)