lkml.org 
[lkml]   [2022]   [Jun]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH 4.14 017/237] random: document get_random_int() family
    Date
    From: George Spelvin <lkml@sdf.org>

    commit 92e507d216139b356a375afbda2824e85235e748 upstream.

    Explain what these functions are for and when they offer
    an advantage over get_random_bytes().

    (We still need documentation on rng_is_initialized(), the
    random_ready_callback system, and early boot in general.)

    Signed-off-by: George Spelvin <lkml@sdf.org>
    Signed-off-by: Theodore Ts'o <tytso@mit.edu>
    Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
    Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
    ---
    drivers/char/random.c | 83 +++++++++++++++++++++++++++++++++++++++++++++-----
    1 file changed, 76 insertions(+), 7 deletions(-)

    --- a/drivers/char/random.c
    +++ b/drivers/char/random.c
    @@ -101,15 +101,13 @@
    * Exported interfaces ---- output
    * ===============================
    *
    - * There are three exported interfaces; the first is one designed to
    - * be used from within the kernel:
    + * There are four exported interfaces; two for use within the kernel,
    + * and two or use from userspace.
    *
    - * void get_random_bytes(void *buf, int nbytes);
    - *
    - * This interface will return the requested number of random bytes,
    - * and place it in the requested buffer.
    + * Exported interfaces ---- userspace output
    + * -----------------------------------------
    *
    - * The two other interfaces are two character devices /dev/random and
    + * 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
    @@ -122,6 +120,77 @@
    * 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 interface is
    + *
    + * void get_random_bytes(void *buf, int nbytes);
    + *
    + * This interface will return the requested number of random bytes,
    + * and place it in the requested buffer. This is equivalent to a
    + * read from /dev/urandom.
    + *
    + * For less critical applications, there are the functions:
    + *
    + * u32 get_random_u32()
    + * u64 get_random_u64()
    + * unsigned int get_random_int()
    + * unsigned long get_random_long()
    + *
    + * These are produced by a cryptographic RNG seeded from get_random_bytes,
    + * and so do not deplete the entropy pool as much. These are recommended
    + * for most in-kernel operations *if the result is going to be stored in
    + * the kernel*.
    + *
    + * Specifically, the get_random_int() family do not attempt to do
    + * "anti-backtracking". If you capture the state of the kernel (e.g.
    + * by snapshotting the VM), you can figure out previous get_random_int()
    + * return values. But if the value is stored in the kernel anyway,
    + * this is not a problem.
    + *
    + * It *is* safe to expose get_random_int() output to attackers (e.g. as
    + * network cookies); given outputs 1..n, it's not feasible to predict
    + * outputs 0 or n+1. The only concern is an attacker who breaks into
    + * the kernel later; the get_random_int() engine is not reseeded as
    + * often as the get_random_bytes() one.
    + *
    + * get_random_bytes() is needed for keys that need to stay secret after
    + * they are erased from the kernel. For example, any key that will
    + * be wrapped and stored encrypted. And session encryption keys: we'd
    + * like to know that after the session is closed and the keys erased,
    + * the plaintext is unrecoverable to someone who recorded the ciphertext.
    + *
    + * But for network ports/cookies, stack canaries, PRNG seeds, address
    + * space layout randomization, session *authentication* keys, or other
    + * applications where the sensitive data is stored in the kernel in
    + * plaintext for as long as it's sensitive, the get_random_int() family
    + * is just fine.
    + *
    + * Consider ASLR. We want to keep the address space secret from an
    + * outside attacker while the process is running, but once the address
    + * space is torn down, it's of no use to an attacker any more. And it's
    + * stored in kernel data structures as long as it's alive, so worrying
    + * about an attacker's ability to extrapolate it from the get_random_int()
    + * CRNG is silly.
    + *
    + * Even some cryptographic keys are safe to generate with get_random_int().
    + * In particular, keys for SipHash are generally fine. Here, knowledge
    + * of the key authorizes you to do something to a kernel object (inject
    + * packets to a network connection, or flood a hash table), and the
    + * key is stored with the object being protected. Once it goes away,
    + * we no longer care if anyone knows the key.
    + *
    + * 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
    * ==============================
    *

    \
     
     \ /
      Last update: 2022-06-23 19:19    [W:4.029 / U:0.048 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site