text: /* Copyright (c) 2001, Matej Pfajfar.
   * Copyright (c) 2001-2004, Roger Dingledine.
   * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   * Copyright (c) 2007-2021, The Tor Project, Inc. */
  /* See LICENSE for licensing information */
  
  /**
   * \file crypto_rand_fast.c
   *
   * \brief A fast strong PRNG for use when our underlying cryptographic
   *   library's PRNG isn't fast enough.
   **/
  
  /* This library is currently implemented to use the same implementation
   * technique as libottery, using AES-CTR-256 as our underlying stream cipher.
   * It's backtracking-resistant immediately, and prediction-resistant after
   * a while.
   *
   * Here's how it works:
   *
   * We generate pseudorandom bytes using AES-CTR-256.  We generate BUFLEN bytes
   * at a time.  When we do this, we keep the first SEED_LEN bytes as the key
   * and the IV for our next invocation of AES_CTR, and yield the remaining
   * BUFLEN - SEED_LEN bytes to the user as they invoke the PRNG.  As we yield
   * bytes to the user, we clear them from the buffer.
   *
   * After we have refilled the buffer RESEED_AFTER times, we mix in an
   * additional SEED_LEN bytes from our strong PRNG into the seed.
   *
   * If the user ever asks for a huge number of bytes at once, we pull SEED_LEN
   * bytes from the PRNG and use them with our stream cipher to fill the user's
   * request.
   */
  
  #define CRYPTO_PRIVATE
  
  #include "lib/crypt_ops/crypto_rand.h"
  #include "lib/crypt_ops/crypto_cipher.h"
  #include "lib/crypt_ops/crypto_digest.h"
  #include "lib/crypt_ops/crypto_util.h"
  #include "lib/intmath/cmp.h"
  #include "lib/cc/ctassert.h"
  #include "lib/malloc/map_anon.h"
  #include "lib/thread/threads.h"
  
  #include "lib/log/util_bug.h"
  
  #ifdef HAVE_SYS_TYPES_H
  #include <sys/types.h>
  #endif
  #ifdef HAVE_UNISTD_H
  #include <unistd.h>
  #endif
  
  #include <string.h>
  
  #ifdef NOINHERIT_CAN_FAIL
  #define CHECK_PID
  #endif
  
  #ifdef CHECK_PID
  #define PID_FIELD_LEN sizeof(pid_t)
  #else
  #define PID_FIELD_LEN 0
  #endif
  
  /* Alias for CRYPTO_FAST_RNG_SEED_LEN to make our code shorter.
   */
  #define SEED_LEN (CRYPTO_FAST_RNG_SEED_LEN)
  
  /* The amount of space that we mmap for a crypto_fast_rng_t.
   */
  #define MAPLEN 4096
  
  /* The number of random bytes that we can yield to the user after each
   * time we fill a crypto_fast_rng_t's buffer.
   */
  #define BUFLEN (MAPLEN - 2*sizeof(uint16_t) - SEED_LEN - PID_FIELD_LEN)
  
  /* The number of buffer refills after which we should fetch more
   * entropy from crypto_strongest_rand().
   */
  #define RESEED_AFTER 16
  
  /* The length of the stream cipher key we will use for the PRNG, in bytes.
   */
  #define KEY_LEN (CRYPTO_FAST_RNG_SEED_LEN - CIPHER_IV_LEN)
  /* The length of the stream cipher key we will use for the PRNG, in bits.
   */
  #define KEY_BITS (KEY_LEN * 8)
  
  /* Make sure that we have a key length we can actually use with AES. */
  CTASSERT(KEY_BITS == 128 || KEY_BITS == 192 || KEY_BITS == 256);
  
  struct crypto_fast_rng_t {
    /** How many more fills does this buffer have before we should mix
     * in the output of crypto_strongest_rand()?
     *
     * This value may be negative if unit tests are enabled.  If so, it
     * indicates that we should never mix in extra data from
     * crypto_strongest_rand().
     */
    int16_t n_till_reseed;
    /** How many bytes are remaining in cbuf_t.bytes? */
    uint16_t bytes_left;
  #ifdef CHECK_PID
    /** Which process owns this fast_rng?  If this value is zero, we do not
     * need to test the owner. */
    pid_t owner;
  #endif
    struct cbuf_t {
      /** The seed (key and IV) that we will use the next time that we refill
       * cbuf_t. */
      uint8_t seed[SEED_LEN];
      /**
       * Bytes that we are yielding to the user.  The next byte to be
       * yielded is at bytes[BUFLEN-bytes_left]; all other bytes in this
       * array are set to zero.
       */
      uint8_t bytes[BUFLEN];
    } buf;
  };
  
  /* alignof(uint8_t) should be 1, so there shouldn't be any padding in cbuf_t.
   */
  CTASSERT(sizeof(struct cbuf_t) == BUFLEN+SEED_LEN);
  /* We're trying to fit all of the RNG state into a nice mmapable chunk.
   */
  CTASSERT(sizeof(crypto_fast_rng_t) <= MAPLEN);
  
  /**
   * Initialize and return a new fast PRNG, using a strong random seed.
   *
   * Note that this object is NOT thread-safe.  If you need a thread-safe
   * prng, use crypto_rand(), or wrap this in a mutex.
   **/
  crypto_fast_rng_t *
  crypto_fast_rng_new(void)
  {
    uint8_t seed[SEED_LEN];
    crypto_strongest_rand(seed, sizeof(seed));
    crypto_fast_rng_t *result = crypto_fast_rng_new_from_seed(seed);
    memwipe(seed, 0, sizeof(seed));
    return result;
  }
  
  /**
   * Initialize and return a new fast PRNG, using a seed value specified
   * in <b>seed</b>.  This value must be CRYPTO_FAST_RNG_SEED_LEN bytes
   * long.
   *
   * Note that this object is NOT thread-safe.  If you need a thread-safe
   * prng, you should probably look at get_thread_fast_rng().  Alternatively,
   * use crypto_rand(), wrap this in a mutex.
   **/
  crypto_fast_rng_t *
  crypto_fast_rng_new_from_seed(const uint8_t *seed)
  {
    unsigned inherit = INHERIT_RES_KEEP;
    /* We try to allocate this object as securely as we can, to avoid
     * having it get dumped, swapped, or shared after fork.
     */
    crypto_fast_rng_t *result = tor_mmap_anonymous(sizeof(*result),
                                  ANONMAP_PRIVATE | ANONMAP_NOINHERIT,
                                  &inherit);
    memcpy(result->buf.seed, seed, SEED_LEN);
    /* Causes an immediate refill once the user asks for data. */
    result->bytes_left = 0;
    result->n_till_reseed = RESEED_AFTER;
  #ifdef CHECK_PID
    if (inherit == INHERIT_RES_KEEP) {
      /* This value will neither be dropped nor zeroed after fork, so we need to
       * check our pid to make sure we are not sharing it across a fork.  This
       * can be expensive if the pid value isn't cached, sadly.
       */
      result->owner = getpid();
    }
  #elif defined(_WIN32)
    /* Windows can't fork(), so there's no need to noinherit. */
  #else
    /* We decided above that noinherit would always do _something_. Assert here
     * that we were correct. */
    tor_assertf(inherit != INHERIT_RES_KEEP,
                "We failed to create a non-inheritable memory region, even "
                "though we believed such a failure to be impossible! This is "
                "probably a bug in Tor support for your platform; please report "
                "it.");
  #endif /* defined(CHECK_PID) || ... */
    return result;
  }
  
  #ifdef TOR_UNIT_TESTS
  /**
   * Unit tests only: prevent a crypto_fast_rng_t from ever mixing in more
   * entropy.
   */
  void
  crypto_fast_rng_disable_reseed(crypto_fast_rng_t *rng)
  {
    rng->n_till_reseed = -1;
  }
  #endif /* defined(TOR_UNIT_TESTS) */
  
  /**
   * Helper: create a crypto_cipher_t object from SEED_LEN bytes of
   * input.  The first KEY_LEN bytes are used as the stream cipher's key,
   * and the remaining CIPHER_IV_LEN bytes are used as its IV.
   **/
  static inline crypto_cipher_t *
  cipher_from_seed(const uint8_t *seed)
  {
    return crypto_cipher_new_with_iv_and_bits(seed, seed+KEY_LEN, KEY_BITS);
  }
  
  /**
   * Helper: mix additional entropy into <b>rng</b> by using our XOF to mix the
   * old value for the seed with some additional bytes from
   * crypto_strongest_rand().
   **/
  static void
  crypto_fast_rng_add_entopy(crypto_fast_rng_t *rng)
  {
    crypto_xof_t *xof = crypto_xof_new();
    crypto_xof_add_bytes(xof, rng->buf.seed, SEED_LEN);
    {
      uint8_t seedbuf[SEED_LEN];
      crypto_strongest_rand(seedbuf, SEED_LEN);
      crypto_xof_add_bytes(xof, seedbuf, SEED_LEN);
      memwipe(seedbuf, 0, SEED_LEN);
    }
    crypto_xof_squeeze_bytes(xof, rng->buf.seed, SEED_LEN);
    crypto_xof_free(xof);
  }
  
  /**
   * Helper: refill the seed bytes and output buffer of <b>rng</b>, using
   * the input seed bytes as input (key and IV) for the stream cipher.
   *
   * If the n_till_reseed counter has reached zero, mix more random bytes into
   * the seed before refilling the buffer.
   **/
  static void
  crypto_fast_rng_refill(crypto_fast_rng_t *rng)
  {
    rng->n_till_reseed--;
    if (rng->n_till_reseed == 0) {
      /* It's time to reseed the RNG. */
      crypto_fast_rng_add_entopy(rng);
      rng->n_till_reseed = RESEED_AFTER;
    } else if (rng->n_till_reseed < 0) {
  #ifdef TOR_UNIT_TESTS
      /* Reseeding is disabled for testing; never do it on this prng. */
      rng->n_till_reseed = -1;
  #else
      /* If testing is disabled, this shouldn't be able to become negative. */
      tor_assert_unreached();
  #endif /* defined(TOR_UNIT_TESTS) */
    }
    /* Now fill rng->buf with output from our stream cipher, initialized from
     * that seed value. */
    crypto_cipher_t *c = cipher_from_seed(rng->buf.seed);
    memset(&rng->buf, 0, sizeof(rng->buf));
    crypto_cipher_crypt_inplace(c, (char*)&rng->buf, sizeof(rng->buf));
    crypto_cipher_free(c);
  
    rng->bytes_left = sizeof(rng->buf.bytes);
  }
  
  /**
   * Release all storage held by <b>rng</b>.
   **/
  void
  crypto_fast_rng_free_(crypto_fast_rng_t *rng)
  {
    if (!rng)
      return;
    memwipe(rng, 0, sizeof(*rng));
    tor_munmap_anonymous(rng, sizeof(*rng));
  }
  
  /**
   * Helper: extract bytes from the PRNG, refilling it as necessary. Does not
   * optimize the case when the user has asked for a huge output.
   **/
  static void
  crypto_fast_rng_getbytes_impl(crypto_fast_rng_t *rng, uint8_t *out,
                                const size_t n)
  {
  #ifdef CHECK_PID
    if (rng->owner) {
      /* Note that we only need to do this check when we have owner set: that
       * is, when our attempt to block inheriting failed, and the result was
       * INHERIT_RES_KEEP.
       *
       * If the result was INHERIT_RES_DROP, then any attempt to access the rng
       * memory after forking will crash.
       *
       * If the result was INHERIT_RES_ZERO, then forking will set the bytes_left
       * and n_till_reseed fields to zero.  This function will call
       * crypto_fast_rng_refill(), which will in turn reseed the PRNG.
       *
       * So we only need to do this test in the case when mmap_anonymous()
       * returned INHERIT_KEEP.  We avoid doing it needlessly, since getpid() is
       * often a system call, and that can be slow.
       */
      tor_assert(rng->owner == getpid());
    }
  #endif /* defined(CHECK_PID) */
  
    size_t bytes_to_yield = n;
  
    while (bytes_to_yield) {
      if (rng->bytes_left == 0)
        crypto_fast_rng_refill(rng);
  
      const size_t to_copy = MIN(rng->bytes_left, bytes_to_yield);
  
      tor_assert(sizeof(rng->buf.bytes) >= rng->bytes_left);
      uint8_t *copy_from = rng->buf.bytes +
        (sizeof(rng->buf.bytes) - rng->bytes_left);
      memcpy(out, copy_from, to_copy);
      memset(copy_from, 0, to_copy);
  
      out += to_copy;
      bytes_to_yield -= to_copy;
      rng->bytes_left -= to_copy;
    }
  }
  
  /**
   * Extract <b>n</b> bytes from <b>rng</b> into the buffer at <b>out</b>.
   **/
  void
  crypto_fast_rng_getbytes(crypto_fast_rng_t *rng, uint8_t *out, size_t n)
  {
    if (PREDICT_UNLIKELY(n > BUFLEN)) {
      /* The user has asked for a lot of output; generate it from a stream
       * cipher seeded by the PRNG rather than by pulling it out of the PRNG
       * directly.
       */
      uint8_t seed[SEED_LEN];
      crypto_fast_rng_getbytes_impl(rng, seed, SEED_LEN);
      crypto_cipher_t *c = cipher_from_seed(seed);
      memset(out, 0, n);
      crypto_cipher_crypt_inplace(c, (char*)out, n);
      crypto_cipher_free(c);
      memwipe(seed, 0, sizeof(seed));
      return;
    }
  
    crypto_fast_rng_getbytes_impl(rng, out, n);
  }
  
  #if defined(TOR_UNIT_TESTS)
  /** for white-box testing: return the number of bytes that are returned from
   * the user for each invocation of the stream cipher in this RNG. */
  size_t
  crypto_fast_rng_get_bytes_used_per_stream(void)
  {
    return BUFLEN;
  }
  #endif /* defined(TOR_UNIT_TESTS) */
  
  /**
   * Thread-local instance for our fast RNG.
   **/
  static tor_threadlocal_t thread_rng;
  
  /**
   * Return a per-thread fast RNG, initializing it if necessary.
   *
   * You do not need to free this yourself.
   *
   * It is NOT safe to share this value across threads.
   **/
  crypto_fast_rng_t *
  get_thread_fast_rng(void)
  {
    crypto_fast_rng_t *rng = tor_threadlocal_get(&thread_rng);
  
    if (PREDICT_UNLIKELY(rng == NULL)) {
      rng = crypto_fast_rng_new();
      tor_threadlocal_set(&thread_rng, rng);
    }
  
    return rng;
  }
  
  /**
   * Used when a thread is exiting: free the per-thread fast RNG if needed.
   * Invoked from the crypto subsystem's thread-cleanup code.
   **/
  void
  destroy_thread_fast_rng(void)
  {
    crypto_fast_rng_t *rng = tor_threadlocal_get(&thread_rng);
    if (!rng)
      return;
    crypto_fast_rng_free(rng);
    tor_threadlocal_set(&thread_rng, NULL);
  }
  
  #ifdef TOR_UNIT_TESTS
  /**
   * Replace the current thread's rng with <b>rng</b>. For use by the
   * unit tests only.  Returns the previous thread rng.
   **/
  crypto_fast_rng_t *
  crypto_replace_thread_fast_rng(crypto_fast_rng_t *rng)
  {
    crypto_fast_rng_t *old_rng =  tor_threadlocal_get(&thread_rng);
    tor_threadlocal_set(&thread_rng, rng);
    return old_rng;
  }
  #endif /* defined(TOR_UNIT_TESTS) */
  
  /**
   * Initialize the global thread-local key that will be used to keep track
   * of per-thread fast RNG instances.  Called from the crypto subsystem's
   * initialization code.
   **/
  void
  crypto_rand_fast_init(void)
  {
    tor_threadlocal_init(&thread_rng);
  }
  
  /**
   * Initialize the global thread-local key that will be used to keep track
   * of per-thread fast RNG instances.  Called from the crypto subsystem's
   * shutdown code.
   **/
  void
  crypto_rand_fast_shutdown(void)
  {
    destroy_thread_fast_rng();
    tor_threadlocal_destroy(&thread_rng);
  }
  