This is a note to let you know that I've just added the patch titled
random: rewrite header introductory comment
to the 4.14-stable tree which can be found at:
http://www.kernel.org/git/?p=linux/kernel/git/stable/stable-queue.git;a=summary
The filename of the patch is:
random-rewrite-header-introductory-comment.patch
and it can be found in the queue-4.14 subdirectory.
If you, or anyone else, feels it should not be added to the stable tree,
please let <stable@xxxxxxxxxxxxxxx> know about it.
>From foo@baz Thu Jun 16 07:08:33 PM CEST 2022
From: "Jason A. Donenfeld" <Jason@xxxxxxxxx>
Date: Fri, 11 Feb 2022 12:29:33 +0100
Subject: random: rewrite header introductory comment
From: "Jason A. Donenfeld" <Jason@xxxxxxxxx>
commit 5f75d9f3babea8ae0a2d06724656874f41d317f5 upstream.
Now that we've re-documented the various sections, we can remove the
outdated text here and replace it with a high-level overview.
Cc: Theodore Ts'o <tytso@xxxxxxx>
Reviewed-by: Eric Biggers <ebiggers@xxxxxxxxxx>
Reviewed-by: Dominik Brodowski <linux@xxxxxxxxxxxxxxxxxxxx>
Signed-off-by: Jason A. Donenfeld <Jason@xxxxxxxxx>
Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
---
drivers/char/random.c | 179 +++++---------------------------------------------
1 file changed, 19 insertions(+), 160 deletions(-)
--- a/drivers/char/random.c
+++ b/drivers/char/random.c
@@ -2,168 +2,27 @@
/*
* Copyright (C) 2017-2022 Jason A. Donenfeld <Jason@xxxxxxxxx>. All Rights Reserved.
* Copyright Matt Mackall <mpm@xxxxxxxxxxx>, 2003, 2004, 2005
- * Copyright Theodore Ts'o, 1994, 1995, 1996, 1997, 1998, 1999. All
- * rights reserved.
- */
-
-/*
- * Exported interfaces ---- output
- * ===============================
- *
- * There are four exported interfaces; two for use within the kernel,
- * and two for use from userspace.
- *
- * Exported interfaces ---- userspace output
- * -----------------------------------------
- *
- * The userspace interfaces are two character devices /dev/random and
- * /dev/urandom. /dev/random is suitable for use when very high
- * quality randomness is desired (for example, for key generation or
- * one-time pads), as it will only return a maximum of the number of
- * bits of randomness (as estimated by the random number generator)
- * contained in the entropy pool.
- *
- * The /dev/urandom device does not have this limit, and will return
- * as many bytes as are requested. As more and more random bytes are
- * requested without giving time for the entropy pool to recharge,
- * this will result in random numbers that are merely cryptographically
- * strong. For many applications, however, this is acceptable.
- *
- * Exported interfaces ---- kernel output
- * --------------------------------------
- *
- * The primary kernel interfaces are:
- *
- * void get_random_bytes(void *buf, size_t nbytes);
- * u32 get_random_u32()
- * u64 get_random_u64()
- * unsigned int get_random_int()
- * unsigned long get_random_long()
- *
- * These interfaces will return the requested number of random bytes
- * into the given buffer or as a return value. This is equivalent to a
- * read from /dev/urandom. The get_random_{u32,u64,int,long}() family
- * of functions may be higher performance for one-off random integers,
- * because they do a bit of buffering.
- *
- * prandom_u32()
- * -------------
- *
- * For even weaker applications, see the pseudorandom generator
- * prandom_u32(), prandom_max(), and prandom_bytes(). If the random
- * numbers aren't security-critical at all, these are *far* cheaper.
- * Useful for self-tests, random error simulation, randomized backoffs,
- * and any other application where you trust that nobody is trying to
- * maliciously mess with you by guessing the "random" numbers.
- *
- * Exported interfaces ---- input
- * ==============================
- *
- * The current exported interfaces for gathering environmental noise
- * from the devices are:
- *
- * void add_device_randomness(const void *buf, size_t size);
- * void add_input_randomness(unsigned int type, unsigned int code,
- * unsigned int value);
- * void add_interrupt_randomness(int irq);
- * void add_disk_randomness(struct gendisk *disk);
- * void add_hwgenerator_randomness(const void *buffer, size_t count,
- * size_t entropy);
- * void add_bootloader_randomness(const void *buf, size_t size);
- *
- * add_device_randomness() is for adding data to the random pool that
- * is likely to differ between two devices (or possibly even per boot).
- * This would be things like MAC addresses or serial numbers, or the
- * read-out of the RTC. This does *not* add any actual entropy to the
- * pool, but it initializes the pool to different values for devices
- * that might otherwise be identical and have very little entropy
- * available to them (particularly common in the embedded world).
- *
- * add_input_randomness() uses the input layer interrupt timing, as well as
- * the event type information from the hardware.
- *
- * add_interrupt_randomness() uses the interrupt timing as random
- * inputs to the entropy pool. Using the cycle counters and the irq source
- * as inputs, it feeds the randomness roughly once a second.
- *
- * add_disk_randomness() uses what amounts to the seek time of block
- * layer request events, on a per-disk_devt basis, as input to the
- * entropy pool. Note that high-speed solid state drives with very low
- * seek times do not make for good sources of entropy, as their seek
- * times are usually fairly consistent.
- *
- * All of these routines try to estimate how many bits of randomness a
- * particular randomness source. They do this by keeping track of the
- * first and second order deltas of the event timings.
- *
- * add_hwgenerator_randomness() is for true hardware RNGs, and will credit
- * entropy as specified by the caller. If the entropy pool is full it will
- * block until more entropy is needed.
- *
- * add_bootloader_randomness() is the same as add_hwgenerator_randomness() or
- * add_device_randomness(), depending on whether or not the configuration
- * option CONFIG_RANDOM_TRUST_BOOTLOADER is set.
- *
- * Ensuring unpredictability at system startup
- * ============================================
- *
- * When any operating system starts up, it will go through a sequence
- * of actions that are fairly predictable by an adversary, especially
- * if the start-up does not involve interaction with a human operator.
- * This reduces the actual number of bits of unpredictability in the
- * entropy pool below the value in entropy_count. In order to
- * counteract this effect, it helps to carry information in the
- * entropy pool across shut-downs and start-ups. To do this, put the
- * following lines an appropriate script which is run during the boot
- * sequence:
- *
- * echo "Initializing random number generator..."
- * random_seed=/var/run/random-seed
- * # Carry a random seed from start-up to start-up
- * # Load and then save the whole entropy pool
- * if [ -f $random_seed ]; then
- * cat $random_seed >/dev/urandom
- * else
- * touch $random_seed
- * fi
- * chmod 600 $random_seed
- * dd if=/dev/urandom of=$random_seed count=1 bs=512
- *
- * and the following lines in an appropriate script which is run as
- * the system is shutdown:
- *
- * # Carry a random seed from shut-down to start-up
- * # Save the whole entropy pool
- * echo "Saving random seed..."
- * random_seed=/var/run/random-seed
- * touch $random_seed
- * chmod 600 $random_seed
- * dd if=/dev/urandom of=$random_seed count=1 bs=512
- *
- * For example, on most modern systems using the System V init
- * scripts, such code fragments would be found in
- * /etc/rc.d/init.d/random. On older Linux systems, the correct script
- * location might be in /etc/rcb.d/rc.local or /etc/rc.d/rc.0.
- *
- * Effectively, these commands cause the contents of the entropy pool
- * to be saved at shut-down time and reloaded into the entropy pool at
- * start-up. (The 'dd' in the addition to the bootup script is to
- * make sure that /etc/random-seed is different for every start-up,
- * even if the system crashes without executing rc.0.) Even with
- * complete knowledge of the start-up activities, predicting the state
- * of the entropy pool requires knowledge of the previous history of
- * the system.
- *
- * Configuring the /dev/random driver under Linux
- * ==============================================
+ * Copyright Theodore Ts'o, 1994, 1995, 1996, 1997, 1998, 1999. All rights reserved.
*
- * The /dev/random driver under Linux uses minor numbers 8 and 9 of
- * the /dev/mem major number (#1). So if your system does not have
- * /dev/random and /dev/urandom created already, they can be created
- * by using the commands:
+ * This driver produces cryptographically secure pseudorandom data. It is divided
+ * into roughly six sections, each with a section header:
*
- * mknod /dev/random c 1 8
- * mknod /dev/urandom c 1 9
+ * - Initialization and readiness waiting.
+ * - Fast key erasure RNG, the "crng".
+ * - Entropy accumulation and extraction routines.
+ * - Entropy collection routines.
+ * - Userspace reader/writer interfaces.
+ * - Sysctl interface.
+ *
+ * The high level overview is that there is one input pool, into which
+ * various pieces of data are hashed. Some of that data is then "credited" as
+ * having a certain number of bits of entropy. When enough bits of entropy are
+ * available, the hash is finalized and handed as a key to a stream cipher that
+ * expands it indefinitely for various consumers. This key is periodically
+ * refreshed as the various entropy collectors, described below, add data to the
+ * input pool and credit it. There is currently no Fortuna-like scheduler
+ * involved, which can lead to malicious entropy sources causing a premature
+ * reseed, and the entropy estimates are, at best, conservative guesses.
*/
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
Patches currently in stable-queue which might be from Jason@xxxxxxxxx are
queue-4.14/random-do-not-take-pool-spinlock-at-boot.patch
queue-4.14/random-remove-kernel.random.read_wakeup_threshold.patch
queue-4.14/random-simplify-arithmetic-function-flow-in-account.patch
queue-4.14/random-order-timer-entropy-functions-below-interrupt-functions.patch
queue-4.14/random-introduce-drain_entropy-helper-to-declutter-crng_reseed.patch
queue-4.14/random-fix-locking-in-crng_fast_load.patch
queue-4.14/random-cleanup-uuid-handling.patch
queue-4.14/random-group-userspace-read-write-functions.patch
queue-4.14/random-make-credit_entropy_bits-always-safe.patch
queue-4.14/latent_entropy-avoid-build-error-when-plugin-cflags-are-not-set.patch
queue-4.14/revert-hwrng-core-freeze-khwrng-thread-during-suspend.patch
queue-4.14/drivers-char-random.c-make-primary_crng-static.patch
queue-4.14/random-do-not-re-init-if-crng_reseed-completes-before-primary-init.patch
queue-4.14/random-always-fill-buffer-in-get_random_bytes_wait.patch
queue-4.14/random-use-proper-jiffies-comparison-macro.patch
queue-4.14/init-call-time_init-before-rand_initialize.patch
queue-4.14/random-split-primary-secondary-crng-init-paths.patch
queue-4.14/random-pull-add_hwgenerator_randomness-declaration-into-random.h.patch
queue-4.14/random-unify-early-init-crng-load-accounting.patch
queue-4.14/drivers-char-random.c-remove-unused-stuct-poolinfo-poolbits.patch
queue-4.14/random-use-blake2s-instead-of-sha1-in-extraction.patch
queue-4.14/random-make-cpu-trust-a-boot-parameter.patch
queue-4.14/random-convert-to-using-fops-write_iter.patch
queue-4.14/random-initialize-chacha20-constants-with-correct-endianness.patch
queue-4.14/random-remove-incomplete-last_data-logic.patch
queue-4.14/random-group-entropy-extraction-functions.patch
queue-4.14/random-optimize-add_interrupt_randomness.patch
queue-4.14/random-add-proper-spdx-header.patch
queue-4.14/linux-random.h-remove-arch_has_random-arch_has_random_seed.patch
queue-4.14/random-rewrite-header-introductory-comment.patch
queue-4.14/random-make-dev-random-be-almost-like-dev-urandom.patch
queue-4.14/random-remove-ifdef-d-out-interrupt-bench.patch
queue-4.14/um-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/lib-crypto-sha1-re-roll-loops-to-reduce-code-size.patch
queue-4.14/random-tie-batched-entropy-generation-to-base_crng-generation.patch
queue-4.14/sparc-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/random-use-linear-min-entropy-accumulation-crediting.patch
queue-4.14/random-remove-batched-entropy-locking.patch
queue-4.14/xtensa-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/powerpc-remove-arch_has_random-arch_has_random_seed.patch
queue-4.14/fdt-add-support-for-rng-seed.patch
queue-4.14/random-continually-use-hwgenerator-randomness.patch
queue-4.14/random-access-input_pool_data-directly-rather-than-through-pointer.patch
queue-4.14/random-add-arch_get_random_-long_early.patch
queue-4.14/random-inline-leaves-of-rand_initialize.patch
queue-4.14/random-cleanup-poolinfo-abstraction.patch
queue-4.14/random-wire-up-fops-splice_-read-write-_iter.patch
queue-4.14/random-handle-latent-entropy-and-command-line-from-random_init.patch
queue-4.14/random-remove-use_input_pool-parameter-from-crng_reseed.patch
queue-4.14/random-credit-architectural-init-the-exact-amount.patch
queue-4.14/ia64-define-get_cycles-macro-for-arch-override.patch
queue-4.14/random-replace-custom-notifier-chain-with-standard-one.patch
queue-4.14/random-support-freezable-kthreads-in-add_hwgenerator_randomness.patch
queue-4.14/random-document-get_random_int-family.patch
queue-4.14/random-remove-the-blocking-pool.patch
queue-4.14/random-avoid-initializing-twice-in-credit-race.patch
queue-4.14/random-avoid-warnings-for-config_numa-builds.patch
queue-4.14/crypto-drbg-add-fips-140-2-ctrng-for-noise-source.patch
queue-4.14/random-mark-bootloader-randomness-code-as-__init.patch
queue-4.14/random-zero-buffer-after-reading-entropy-from-userspace.patch
queue-4.14/random-remove-whitespace-and-reorder-includes.patch
queue-4.14/random-ignore-grnd_random-in-getentropy-2.patch
queue-4.14/random-clear-fast-pool-crng-and-batches-in-cpuhp-bring-up.patch
queue-4.14/random-document-add_hwgenerator_randomness-with-other-input-functions.patch
queue-4.14/random-fix-typo-in-add_timer_randomness.patch
queue-4.14/random-do-crng-pre-init-loading-in-worker-rather-than-irq.patch
queue-4.14/powerpc-use-bool-in-archrandom.h.patch
queue-4.14/random-do-not-split-fast-init-input-in-add_hwgenerator_randomness.patch
queue-4.14/timekeeping-add-raw-clock-fallback-for-random_get_entropy.patch
queue-4.14/random-early-initialization-of-chacha-constants.patch
queue-4.14/crypto-drbg-prepare-for-more-fine-grained-tracking-of-seeding-state.patch
queue-4.14/random-delete-code-to-pull-data-into-pools.patch
queue-4.14/crypto-drbg-always-try-to-free-jitter-rng-instance.patch
queue-4.14/random-simplify-entropy-debiting.patch
queue-4.14/random-don-t-reset-crng_init_cnt-on-urandom_read.patch
queue-4.14/random-skip-fast_init-if-hwrng-provides-large-chunk-of-entropy.patch
queue-4.14/random-use-siphash-as-interrupt-entropy-accumulator.patch
queue-4.14/random-avoid-checking-crng_ready-twice-in-random_init.patch
queue-4.14/random-fix-soft-lockup-when-trying-to-read-from-an-uninitialized-blocking-pool.patch
queue-4.14/random-group-sysctl-functions.patch
queue-4.14/random-don-t-let-644-read-only-sysctls-be-written-to.patch
queue-4.14/random-document-crng_fast_key_erasure-destination-possibility.patch
queue-4.14/random-only-wake-up-writers-after-zap-if-threshold-was-passed.patch
queue-4.14/random-use-wait_event_freezable-in-add_hwgenerator_randomness.patch
queue-4.14/random-check-for-signal-and-try-earlier-when-generating-entropy.patch
queue-4.14/random-check-for-signals-every-page_size-chunk-of-dev-random.patch
queue-4.14/arm-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/random-absorb-fast-pool-into-input-pool-after-fast-load.patch
queue-4.14/random-give-sysctl_random_min_urandom_seed-a-more-sensible-value.patch
queue-4.14/crypto-blake2s-generic-c-library-implementation-and-selftest.patch
queue-4.14/random-cleanup-fractional-entropy-shift-constants.patch
queue-4.14/random-use-rdseed-instead-of-rdrand-in-entropy-extraction.patch
queue-4.14/random-move-rand_initialize-earlier.patch
queue-4.14/random-don-t-wake-crng_init_wait-when-crng_init-1.patch
queue-4.14/random-add-a-urandom_read_nowait-for-random-apis-that-don-t-warn.patch
queue-4.14/random-do-not-sign-extend-bytes-for-rotation-when-mixing.patch
queue-4.14/random-move-initialization-functions-out-of-hot-pages.patch
queue-4.14/random-remove-dead-code-left-over-from-blocking-pool.patch
queue-4.14/drivers-char-random.c-constify-poolinfo_table.patch
queue-4.14/crypto-drbg-track-whether-drbg-was-seeded-with-rng_is_initialized.patch
queue-4.14/random-use-computational-hash-for-entropy-extraction.patch
queue-4.14/random-add-and-use-pr_fmt.patch
queue-4.14/random-round-robin-registers-as-ulong-not-u32.patch
queue-4.14/random-always-wake-up-entropy-writers-after-extraction.patch
queue-4.14/s390-remove-arch_has_random-arch_has_random_seed.patch
queue-4.14/random-do-not-xor-rdrand-when-writing-into-dev-random.patch
queue-4.14/crypto-drbg-make-reseeding-from-get_random_bytes-synchronous.patch
queue-4.14/random-convert-to-entropy_bits-for-better-code-readability.patch
queue-4.14/char-random-add-a-newline-at-the-end-of-the-file.patch
queue-4.14/random-move-randomize_page-into-mm-where-it-belongs.patch
queue-4.14/random-only-call-crng_finalize_init-for-primary_crng.patch
queue-4.14/random-cleanup-integer-types.patch
queue-4.14/random-re-add-removed-comment-about-get_random_-u32-u64-reseeding.patch
queue-4.14/random-unify-cycles_t-and-jiffies-usage-and-types.patch
queue-4.14/random-insist-on-random_get_entropy-existing-in-order-to-simplify.patch
queue-4.14/random-group-initialization-wait-functions.patch
queue-4.14/linux-random.h-mark-config_arch_random-functions-__must_check.patch
queue-4.14/random-remove-unused-extract_entropy-reserved-argument.patch
queue-4.14/random-check-for-signal_pending-outside-of-need_resched-check.patch
queue-4.14/random-access-primary_pool-directly-rather-than-through-pointer.patch
queue-4.14/random-fix-sysctl-documentation-nits.patch
queue-4.14/random-remove-unused-tracepoints.patch
queue-4.14/random-only-read-from-dev-random-after-its-pool-has-received-128-bits.patch
queue-4.14/nios2-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/random-treat-bootloader-trust-toggle-the-same-way-as-cpu-trust-toggle.patch
queue-4.14/random-make-consistent-usage-of-crng_ready.patch
queue-4.14/lib-crypto-blake2s-move-hmac-construction-into-wireguard.patch
queue-4.14/parisc-define-get_cycles-macro-for-arch-override.patch
queue-4.14/x86-tsc-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/crypto-chacha20-fix-keystream-alignment-for-chacha20_block.patch
queue-4.14/random-add-grnd_insecure-to-return-best-effort-non-cryptographic-bytes.patch
queue-4.14/random-fix-whitespace-pre-random-bytes-work.patch
queue-4.14/crypto-drbg-move-dynamic-reseed_threshold-adjustments-to-__drbg_seed.patch
queue-4.14/random-check-for-signals-after-page-of-pool-writes.patch
queue-4.14/random-make-random_get_entropy-return-an-unsigned-long.patch
queue-4.14/random-check-for-crng_init-0-in-add_device_randomness.patch
queue-4.14/random-add-a-config-option-to-trust-the-cpu-s-hwrng.patch
queue-4.14/random-remove-unnecessary-unlikely.patch
queue-4.14/random-defer-fast-pool-mixing-to-worker.patch
queue-4.14/random-harmonize-crng-init-done-messages.patch
queue-4.14/crypto-blake2s-include-linux-bug.h-instead-of-asm-bug.h.patch
queue-4.14/random-use-static-branch-for-crng_ready.patch
queue-4.14/random-rather-than-entropy_store-abstraction-use-global.patch
queue-4.14/drivers-char-random.c-remove-unused-dont_count_entropy.patch
queue-4.14/random-remove-extern-from-functions-in-header.patch
queue-4.14/siphash-use-one-source-of-truth-for-siphash-permutations.patch
queue-4.14/random-group-entropy-collection-functions.patch
queue-4.14/random-de-duplicate-input_pool-constants.patch
queue-4.14/random-mix-build-time-latent-entropy-into-pool-at-init.patch
queue-4.14/random-remove-useless-header-comment.patch
queue-4.14/linux-random.h-use-false-with-bool.patch
queue-4.14/maintainers-co-maintain-random.c.patch
queue-4.14/random-remove-outdated-int_max-6-check-in-urandom_read.patch
queue-4.14/m68k-use-fallback-for-random_get_entropy-instead-of-zero.patch
queue-4.14/alpha-define-get_cycles-macro-for-arch-override.patch
queue-4.14/random-mix-bootloader-randomness-into-pool.patch
queue-4.14/random-remove-some-dead-code-of-poolinfo.patch
queue-4.14/random-do-not-use-batches-when-crng_ready.patch
queue-4.14/crypto-drbg-always-seeded-with-sp800-90b-compliant-noise-source.patch
queue-4.14/s390-define-get_cycles-macro-for-arch-override.patch
queue-4.14/random-do-not-pretend-to-handle-premature-next-security-model.patch
queue-4.14/random-avoid-arch_get_random_seed_long-when-collecting-irq-randomness.patch
queue-4.14/random-use-is_enabled-config_numa-instead-of-ifdefs.patch
queue-4.14/random-make-crng-state-queryable.patch
queue-4.14/random-avoid-superfluous-call-to-rdrand-in-crng-extraction.patch
queue-4.14/random-use-symbolic-constants-for-crng_init-states.patch
queue-4.14/random-reseed-more-often-immediately-after-booting.patch
queue-4.14/random-ensure-early-rdseed-goes-through-mixer-on-init.patch
queue-4.14/random-deobfuscate-irq-u32-u64-contributions.patch
queue-4.14/random-do-not-use-input-pool-from-hard-irqs.patch
queue-4.14/random-help-compiler-out-with-fast_mix-by-using-simpler-arguments.patch
queue-4.14/revert-random-use-static-branch-for-crng_ready.patch
queue-4.14/random-fix-crash-on-multiple-early-calls-to-add_bootloader_randomness.patch
queue-4.14/random-return-nbytes-filled-from-hw-rng.patch
queue-4.14/random-account-for-arch-randomness-in-bits.patch
queue-4.14/crypto-blake2s-adjust-include-guard-naming.patch
queue-4.14/random-do-not-allow-user-to-keep-crng-key-around-on-stack.patch
queue-4.14/x86-remove-arch_has_random-arch_has_random_seed.patch
queue-4.14/crypto-deduplicate-le32_to_cpu_array-and-cpu_to_le32_array.patch
queue-4.14/random-remove-ratelimiting-for-in-kernel-unseeded-randomness.patch
queue-4.14/random-remove-unused-irq_flags-argument-from-add_interrupt_randomness.patch
queue-4.14/random-prepend-remaining-pool-constants-with-pool_.patch
queue-4.14/powerpc-define-get_cycles-macro-for-arch-override.patch
queue-4.14/random-remove-unused-output_pool-constants.patch
queue-4.14/mips-use-fallback-for-random_get_entropy-instead-of-just-c0-random.patch
queue-4.14/random-use-hash-function-for-crng_slow_load.patch
queue-4.14/random-fix-typo-in-comments.patch
queue-4.14/random-remove-preempt-disabled-region.patch
queue-4.14/random-use-proper-return-types-on-get_random_-int-long-_wait.patch
