crypto/jitterentropy.c

   1 /*
   2  * Non-physical true random number generator based on timing jitter --
   3  * Jitter RNG standalone code.
   4  *
   5  * Copyright Stephan Mueller <[email protected]>, 2015 - 2023
   6  *
   7  * Design
   8  * ======
   9  *
  10  * See https://www.chronox.de/jent.html
  11  *
  12  * License
  13  * =======
  14  *
  15  * Redistribution and use in source and binary forms, with or without
  16  * modification, are permitted provided that the following conditions
  17  * are met:
  18  * 1. Redistributions of source code must retain the above copyright
  19  *    notice, and the entire permission notice in its entirety,
  20  *    including the disclaimer of warranties.
  21  * 2. Redistributions in binary form must reproduce the above copyright
  22  *    notice, this list of conditions and the following disclaimer in the
  23  *    documentation and/or other materials provided with the distribution.
  24  * 3. The name of the author may not be used to endorse or promote
  25  *    products derived from this software without specific prior
  26  *    written permission.
  27  *
  28  * ALTERNATIVELY, this product may be distributed under the terms of
  29  * the GNU General Public License, in which case the provisions of the GPL2 are
  30  * required INSTEAD OF the above restrictions.  (This clause is
  31  * necessary due to a potential bad interaction between the GPL and
  32  * the restrictions contained in a BSD-style copyright.)
  33  *
  34  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
  35  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  36  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF
  37  * WHICH ARE HEREBY DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE
  38  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  39  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
  40  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  41  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  42  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  43  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  44  * USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH
  45  * DAMAGE.
  46  */
  47
  48 /*
  49  * This Jitterentropy RNG is based on the jitterentropy library
  50  * version 3.4.0 provided at https://www.chronox.de/jent.html
  51  */
  52
  53 #ifdef __OPTIMIZE__
  54  #error "The CPU Jitter random number generator must not be compiled with optimizations. See documentation. Use the compiler switch -O0 for compiling jitterentropy.c."
  55 #endif
  56
  57 typedef unsigned long long      __u64;
  58 typedef long long               __s64;
  59 typedef unsigned int            __u32;
  60 typedef unsigned char           u8;
  61 #define NULL    ((void *) 0)
  62
  63 /* The entropy pool */
  64 struct rand_data {
  65         /* SHA3-256 is used as conditioner */
  66 #define DATA_SIZE_BITS 256
  67         /* all data values that are vital to maintain the security
  68          * of the RNG are marked as SENSITIVE. A user must not
  69          * access that information while the RNG executes its loops to
  70          * calculate the next random value. */
  71         void *hash_state;               /* SENSITIVE hash state entropy pool */
  72         __u64 prev_time;                /* SENSITIVE Previous time stamp */
  73         __u64 last_delta;               /* SENSITIVE stuck test */
  74         __s64 last_delta2;              /* SENSITIVE stuck test */
  75
  76         unsigned int flags;             /* Flags used to initialize */
  77         unsigned int osr;               /* Oversample rate */
  78 #define JENT_MEMORY_ACCESSLOOPS 128
  79 #define JENT_MEMORY_SIZE                                                \
  80         (CONFIG_CRYPTO_JITTERENTROPY_MEMORY_BLOCKS *                    \
  81          CONFIG_CRYPTO_JITTERENTROPY_MEMORY_BLOCKSIZE)
  82         unsigned char *mem;     /* Memory access location with size of
  83                                  * memblocks * memblocksize */
  84         unsigned int memlocation; /* Pointer to byte in *mem */
  85         unsigned int memblocks; /* Number of memory blocks in *mem */
  86         unsigned int memblocksize; /* Size of one memory block in bytes */
  87         unsigned int memaccessloops; /* Number of memory accesses per random
  88                                       * bit generation */
  89
  90         /* Repetition Count Test */
  91         unsigned int rct_count;                 /* Number of stuck values */
  92
  93         /* Adaptive Proportion Test cutoff values */
  94         unsigned int apt_cutoff; /* Intermittent health test failure */
  95         unsigned int apt_cutoff_permanent; /* Permanent health test failure */
  96 #define JENT_APT_WINDOW_SIZE    512     /* Data window size */
  97         /* LSB of time stamp to process */
  98 #define JENT_APT_LSB            16
  99 #define JENT_APT_WORD_MASK      (JENT_APT_LSB - 1)
 100         unsigned int apt_observations;  /* Number of collected observations */
 101         unsigned int apt_count;         /* APT counter */
 102         unsigned int apt_base;          /* APT base reference */
 103         unsigned int health_failure;    /* Record health failure */
 104
 105         unsigned int apt_base_set:1;    /* APT base reference set? */
 106 };
 107
 108 /* Flags that can be used to initialize the RNG */
 109 #define JENT_DISABLE_MEMORY_ACCESS (1<<2) /* Disable memory access for more
 110                                            * entropy, saves MEMORY_SIZE RAM for
 111                                            * entropy collector */
 112
 113 /* -- error codes for init function -- */
 114 #define JENT_ENOTIME            1 /* Timer service not available */
 115 #define JENT_ECOARSETIME        2 /* Timer too coarse for RNG */
 116 #define JENT_ENOMONOTONIC       3 /* Timer is not monotonic increasing */
 117 #define JENT_EVARVAR            5 /* Timer does not produce variations of
 118                                    * variations (2nd derivation of time is
 119                                    * zero). */
 120 #define JENT_ESTUCK             8 /* Too many stuck results during init. */
 121 #define JENT_EHEALTH            9 /* Health test failed during initialization */
 122 #define JENT_ERCT              10 /* RCT failed during initialization */
 123 #define JENT_EHASH             11 /* Hash self test failed */
 124 #define JENT_EMEM              12 /* Can't allocate memory for initialization */
 125
 126 #define JENT_RCT_FAILURE        1 /* Failure in RCT health test. */
 127 #define JENT_APT_FAILURE        2 /* Failure in APT health test. */
 128 #define JENT_PERMANENT_FAILURE_SHIFT    16
 129 #define JENT_PERMANENT_FAILURE(x)       (x << JENT_PERMANENT_FAILURE_SHIFT)
 130 #define JENT_RCT_FAILURE_PERMANENT      JENT_PERMANENT_FAILURE(JENT_RCT_FAILURE)
 131 #define JENT_APT_FAILURE_PERMANENT      JENT_PERMANENT_FAILURE(JENT_APT_FAILURE)
 132
 133 /*
 134  * The output n bits can receive more than n bits of min entropy, of course,
 135  * but the fixed output of the conditioning function can only asymptotically
 136  * approach the output size bits of min entropy, not attain that bound. Random
 137  * maps will tend to have output collisions, which reduces the creditable
 138  * output entropy (that is what SP 800-90B Section 3.1.5.1.2 attempts to bound).
 139  *
 140  * The value "64" is justified in Appendix A.4 of the current 90C draft,
 141  * and aligns with NIST's in "epsilon" definition in this document, which is
 142  * that a string can be considered "full entropy" if you can bound the min
 143  * entropy in each bit of output to at least 1-epsilon, where epsilon is
 144  * required to be <= 2^(-32).
 145  */
 146 #define JENT_ENTROPY_SAFETY_FACTOR      64
 147
 148 #include <linux/fips.h>
 149 #include "jitterentropy.h"
 150
 151 /***************************************************************************
 152  * Adaptive Proportion Test
 153  *
 154  * This test complies with SP800-90B section 4.4.2.
 155  ***************************************************************************/
 156
 157 /*
 158  * See the SP 800-90B comment #10b for the corrected cutoff for the SP 800-90B
 159  * APT.
 160  * https://www.untruth.org/~josh/sp80090b/UL%20SP800-90B-final%20comments%20v1.9%2020191212.pdf
 161  * In the syntax of R, this is C = 2 + qbinom(1 − 2^(−30), 511, 2^(-1/osr)).
 162  * (The original formula wasn't correct because the first symbol must
 163  * necessarily have been observed, so there is no chance of observing 0 of these
 164  * symbols.)
 165  *
 166  * For the alpha < 2^-53, R cannot be used as it uses a float data type without
 167  * arbitrary precision. A SageMath script is used to calculate those cutoff
 168  * values.
 169  *
 170  * For any value above 14, this yields the maximal allowable value of 512
 171  * (by FIPS 140-2 IG 7.19 Resolution # 16, we cannot choose a cutoff value that
 172  * renders the test unable to fail).
 173  */
 174 static const unsigned int jent_apt_cutoff_lookup[15] = {
 175         325, 422, 459, 477, 488, 494, 499, 502,
 176         505, 507, 508, 509, 510, 511, 512 };
 177 static const unsigned int jent_apt_cutoff_permanent_lookup[15] = {
 178         355, 447, 479, 494, 502, 507, 510, 512,
 179         512, 512, 512, 512, 512, 512, 512 };
 180 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 181
 182 static void jent_apt_init(struct rand_data *ec, unsigned int osr)
 183 {
 184         /*
 185          * Establish the apt_cutoff based on the presumed entropy rate of
 186          * 1/osr.
 187          */
 188         if (osr >= ARRAY_SIZE(jent_apt_cutoff_lookup)) {
 189                 ec->apt_cutoff = jent_apt_cutoff_lookup[
 190                         ARRAY_SIZE(jent_apt_cutoff_lookup) - 1];
 191                 ec->apt_cutoff_permanent = jent_apt_cutoff_permanent_lookup[
 192                         ARRAY_SIZE(jent_apt_cutoff_permanent_lookup) - 1];
 193         } else {
 194                 ec->apt_cutoff = jent_apt_cutoff_lookup[osr - 1];
 195                 ec->apt_cutoff_permanent =
 196                                 jent_apt_cutoff_permanent_lookup[osr - 1];
 197         }
 198 }
 199 /*
 200  * Reset the APT counter
 201  *
 202  * @ec [in] Reference to entropy collector
 203  */
 204 static void jent_apt_reset(struct rand_data *ec, unsigned int delta_masked)
 205 {
 206         /* Reset APT counter */
 207         ec->apt_count = 0;
 208         ec->apt_base = delta_masked;
 209         ec->apt_observations = 0;
 210 }
 211
 212 /*
 213  * Insert a new entropy event into APT
 214  *
 215  * @ec [in] Reference to entropy collector
 216  * @delta_masked [in] Masked time delta to process
 217  */
 218 static void jent_apt_insert(struct rand_data *ec, unsigned int delta_masked)
 219 {
 220         /* Initialize the base reference */
 221         if (!ec->apt_base_set) {
 222                 ec->apt_base = delta_masked;
 223                 ec->apt_base_set = 1;
 224                 return;
 225         }
 226
 227         if (delta_masked == ec->apt_base) {
 228                 ec->apt_count++;
 229
 230                 /* Note, ec->apt_count starts with one. */
 231                 if (ec->apt_count >= ec->apt_cutoff_permanent)
 232                         ec->health_failure |= JENT_APT_FAILURE_PERMANENT;
 233                 else if (ec->apt_count >= ec->apt_cutoff)
 234                         ec->health_failure |= JENT_APT_FAILURE;
 235         }
 236
 237         ec->apt_observations++;
 238
 239         if (ec->apt_observations >= JENT_APT_WINDOW_SIZE)
 240                 jent_apt_reset(ec, delta_masked);
 241 }
 242
 243 /***************************************************************************
 244  * Stuck Test and its use as Repetition Count Test
 245  *
 246  * The Jitter RNG uses an enhanced version of the Repetition Count Test
 247  * (RCT) specified in SP800-90B section 4.4.1. Instead of counting identical
 248  * back-to-back values, the input to the RCT is the counting of the stuck
 249  * values during the generation of one Jitter RNG output block.
 250  *
 251  * The RCT is applied with an alpha of 2^{-30} compliant to FIPS 140-2 IG 9.8.
 252  *
 253  * During the counting operation, the Jitter RNG always calculates the RCT
 254  * cut-off value of C. If that value exceeds the allowed cut-off value,
 255  * the Jitter RNG output block will be calculated completely but discarded at
 256  * the end. The caller of the Jitter RNG is informed with an error code.
 257  ***************************************************************************/
 258
 259 /*
 260  * Repetition Count Test as defined in SP800-90B section 4.4.1
 261  *
 262  * @ec [in] Reference to entropy collector
 263  * @stuck [in] Indicator whether the value is stuck
 264  */
 265 static void jent_rct_insert(struct rand_data *ec, int stuck)
 266 {
 267         if (stuck) {
 268                 ec->rct_count++;
 269
 270                 /*
 271                  * The cutoff value is based on the following consideration:
 272                  * alpha = 2^-30 or 2^-60 as recommended in SP800-90B.
 273                  * In addition, we require an entropy value H of 1/osr as this
 274                  * is the minimum entropy required to provide full entropy.
 275                  * Note, we collect (DATA_SIZE_BITS + ENTROPY_SAFETY_FACTOR)*osr
 276                  * deltas for inserting them into the entropy pool which should
 277                  * then have (close to) DATA_SIZE_BITS bits of entropy in the
 278                  * conditioned output.
 279                  *
 280                  * Note, ec->rct_count (which equals to value B in the pseudo
 281                  * code of SP800-90B section 4.4.1) starts with zero. Hence
 282                  * we need to subtract one from the cutoff value as calculated
 283                  * following SP800-90B. Thus C = ceil(-log_2(alpha)/H) = 30*osr
 284                  * or 60*osr.
 285                  */
 286                 if ((unsigned int)ec->rct_count >= (60 * ec->osr)) {
 287                         ec->rct_count = -1;
 288                         ec->health_failure |= JENT_RCT_FAILURE_PERMANENT;
 289                 } else if ((unsigned int)ec->rct_count >= (30 * ec->osr)) {
 290                         ec->rct_count = -1;
 291                         ec->health_failure |= JENT_RCT_FAILURE;
 292                 }
 293         } else {
 294                 /* Reset RCT */
 295                 ec->rct_count = 0;
 296         }
 297 }
 298
 299 static inline __u64 jent_delta(__u64 prev, __u64 next)
 300 {
 301 #define JENT_UINT64_MAX         (__u64)(~((__u64) 0))
 302         return (prev < next) ? (next - prev) :
 303                                (JENT_UINT64_MAX - prev + 1 + next);
 304 }
 305
 306 /*
 307  * Stuck test by checking the:
 308  *      1st derivative of the jitter measurement (time delta)
 309  *      2nd derivative of the jitter measurement (delta of time deltas)
 310  *      3rd derivative of the jitter measurement (delta of delta of time deltas)
 311  *
 312  * All values must always be non-zero.
 313  *
 314  * @ec [in] Reference to entropy collector
 315  * @current_delta [in] Jitter time delta
 316  *
 317  * @return
 318  *      0 jitter measurement not stuck (good bit)
 319  *      1 jitter measurement stuck (reject bit)
 320  */
 321 static int jent_stuck(struct rand_data *ec, __u64 current_delta)
 322 {
 323         __u64 delta2 = jent_delta(ec->last_delta, current_delta);
 324         __u64 delta3 = jent_delta(ec->last_delta2, delta2);
 325
 326         ec->last_delta = current_delta;
 327         ec->last_delta2 = delta2;
 328
 329         /*
 330          * Insert the result of the comparison of two back-to-back time
 331          * deltas.
 332          */
 333         jent_apt_insert(ec, current_delta);
 334
 335         if (!current_delta || !delta2 || !delta3) {
 336                 /* RCT with a stuck bit */
 337                 jent_rct_insert(ec, 1);
 338                 return 1;
 339         }
 340
 341         /* RCT with a non-stuck bit */
 342         jent_rct_insert(ec, 0);
 343
 344         return 0;
 345 }
 346
 347 /*
 348  * Report any health test failures
 349  *
 350  * @ec [in] Reference to entropy collector
 351  *
 352  * @return a bitmask indicating which tests failed
 353  *      0 No health test failure
 354  *      1 RCT failure
 355  *      2 APT failure
 356  *      1<<JENT_PERMANENT_FAILURE_SHIFT RCT permanent failure
 357  *      2<<JENT_PERMANENT_FAILURE_SHIFT APT permanent failure
 358  */
 359 static unsigned int jent_health_failure(struct rand_data *ec)
 360 {
 361         /* Test is only enabled in FIPS mode */
 362         if (!fips_enabled)
 363                 return 0;
 364
 365         return ec->health_failure;
 366 }
 367
 368 /***************************************************************************
 369  * Noise sources
 370  ***************************************************************************/
 371
 372 /*
 373  * Update of the loop count used for the next round of
 374  * an entropy collection.
 375  *
 376  * Input:
 377  * @bits is the number of low bits of the timer to consider
 378  * @min is the number of bits we shift the timer value to the right at
 379  *      the end to make sure we have a guaranteed minimum value
 380  *
 381  * @return Newly calculated loop counter
 382  */
 383 static __u64 jent_loop_shuffle(unsigned int bits, unsigned int min)
 384 {
 385         __u64 time = 0;
 386         __u64 shuffle = 0;
 387         unsigned int i = 0;
 388         unsigned int mask = (1<<bits) - 1;
 389
 390         jent_get_nstime(&time);
 391
 392         /*
 393          * We fold the time value as much as possible to ensure that as many
 394          * bits of the time stamp are included as possible.
 395          */
 396         for (i = 0; ((DATA_SIZE_BITS + bits - 1) / bits) > i; i++) {
 397                 shuffle ^= time & mask;
 398                 time = time >> bits;
 399         }
 400
 401         /*
 402          * We add a lower boundary value to ensure we have a minimum
 403          * RNG loop count.
 404          */
 405         return (shuffle + (1<<min));
 406 }
 407
 408 /*
 409  * CPU Jitter noise source -- this is the noise source based on the CPU
 410  *                            execution time jitter
 411  *
 412  * This function injects the individual bits of the time value into the
 413  * entropy pool using a hash.
 414  *
 415  * ec [in] entropy collector
 416  * time [in] time stamp to be injected
 417  * stuck [in] Is the time stamp identified as stuck?
 418  *
 419  * Output:
 420  * updated hash context in the entropy collector or error code
 421  */
 422 static int jent_condition_data(struct rand_data *ec, __u64 time, int stuck)
 423 {
 424 #define SHA3_HASH_LOOP (1<<3)
 425         struct {
 426                 int rct_count;
 427                 unsigned int apt_observations;
 428                 unsigned int apt_count;
 429                 unsigned int apt_base;
 430         } addtl = {
 431                 ec->rct_count,
 432                 ec->apt_observations,
 433                 ec->apt_count,
 434                 ec->apt_base
 435         };
 436
 437         return jent_hash_time(ec->hash_state, time, (u8 *)&addtl, sizeof(addtl),
 438                               SHA3_HASH_LOOP, stuck);
 439 }
 440
 441 /*
 442  * Memory Access noise source -- this is a noise source based on variations in
 443  *                               memory access times
 444  *
 445  * This function performs memory accesses which will add to the timing
 446  * variations due to an unknown amount of CPU wait states that need to be
 447  * added when accessing memory. The memory size should be larger than the L1
 448  * caches as outlined in the documentation and the associated testing.
 449  *
 450  * The L1 cache has a very high bandwidth, albeit its access rate is  usually
 451  * slower than accessing CPU registers. Therefore, L1 accesses only add minimal
 452  * variations as the CPU has hardly to wait. Starting with L2, significant
 453  * variations are added because L2 typically does not belong to the CPU any more
 454  * and therefore a wider range of CPU wait states is necessary for accesses.
 455  * L3 and real memory accesses have even a wider range of wait states. However,
 456  * to reliably access either L3 or memory, the ec->mem memory must be quite
 457  * large which is usually not desirable.
 458  *
 459  * @ec [in] Reference to the entropy collector with the memory access data -- if
 460  *          the reference to the memory block to be accessed is NULL, this noise
 461  *          source is disabled
 462  * @loop_cnt [in] if a value not equal to 0 is set, use the given value
 463  *                number of loops to perform the LFSR
 464  */
 465 static void jent_memaccess(struct rand_data *ec, __u64 loop_cnt)
 466 {
 467         unsigned int wrap = 0;
 468         __u64 i = 0;
 469 #define MAX_ACC_LOOP_BIT 7
 470 #define MIN_ACC_LOOP_BIT 0
 471         __u64 acc_loop_cnt =
 472                 jent_loop_shuffle(MAX_ACC_LOOP_BIT, MIN_ACC_LOOP_BIT);
 473
 474         if (NULL == ec || NULL == ec->mem)
 475                 return;
 476         wrap = ec->memblocksize * ec->memblocks;
 477
 478         /*
 479          * testing purposes -- allow test app to set the counter, not
 480          * needed during runtime
 481          */
 482         if (loop_cnt)
 483                 acc_loop_cnt = loop_cnt;
 484
 485         for (i = 0; i < (ec->memaccessloops + acc_loop_cnt); i++) {
 486                 unsigned char *tmpval = ec->mem + ec->memlocation;
 487                 /*
 488                  * memory access: just add 1 to one byte,
 489                  * wrap at 255 -- memory access implies read
 490                  * from and write to memory location
 491                  */
 492                 *tmpval = (*tmpval + 1) & 0xff;
 493                 /*
 494                  * Addition of memblocksize - 1 to pointer
 495                  * with wrap around logic to ensure that every
 496                  * memory location is hit evenly
 497                  */
 498                 ec->memlocation = ec->memlocation + ec->memblocksize - 1;
 499                 ec->memlocation = ec->memlocation % wrap;
 500         }
 501 }
 502
 503 /***************************************************************************
 504  * Start of entropy processing logic
 505  ***************************************************************************/
 506 /*
 507  * This is the heart of the entropy generation: calculate time deltas and
 508  * use the CPU jitter in the time deltas. The jitter is injected into the
 509  * entropy pool.
 510  *
 511  * WARNING: ensure that ->prev_time is primed before using the output
 512  *          of this function! This can be done by calling this function
 513  *          and not using its result.
 514  *
 515  * @ec [in] Reference to entropy collector
 516  *
 517  * @return result of stuck test
 518  */
 519 static int jent_measure_jitter(struct rand_data *ec, __u64 *ret_current_delta)
 520 {
 521         __u64 time = 0;
 522         __u64 current_delta = 0;
 523         int stuck;
 524
 525         /* Invoke one noise source before time measurement to add variations */
 526         jent_memaccess(ec, 0);
 527
 528         /*
 529          * Get time stamp and calculate time delta to previous
 530          * invocation to measure the timing variations
 531          */
 532         jent_get_nstime(&time);
 533         current_delta = jent_delta(ec->prev_time, time);
 534         ec->prev_time = time;
 535
 536         /* Check whether we have a stuck measurement. */
 537         stuck = jent_stuck(ec, current_delta);
 538
 539         /* Now call the next noise sources which also injects the data */
 540         if (jent_condition_data(ec, current_delta, stuck))
 541                 stuck = 1;
 542
 543         /* return the raw entropy value */
 544         if (ret_current_delta)
 545                 *ret_current_delta = current_delta;
 546
 547         return stuck;
 548 }
 549
 550 /*
 551  * Generator of one 64 bit random number
 552  * Function fills rand_data->hash_state
 553  *
 554  * @ec [in] Reference to entropy collector
 555  */
 556 static void jent_gen_entropy(struct rand_data *ec)
 557 {
 558         unsigned int k = 0, safety_factor = 0;
 559
 560         if (fips_enabled)
 561                 safety_factor = JENT_ENTROPY_SAFETY_FACTOR;
 562
 563         /* priming of the ->prev_time value */
 564         jent_measure_jitter(ec, NULL);
 565
 566         while (!jent_health_failure(ec)) {
 567                 /* If a stuck measurement is received, repeat measurement */
 568                 if (jent_measure_jitter(ec, NULL))
 569                         continue;
 570
 571                 /*
 572                  * We multiply the loop value with ->osr to obtain the
 573                  * oversampling rate requested by the caller
 574                  */
 575                 if (++k >= ((DATA_SIZE_BITS + safety_factor) * ec->osr))
 576                         break;
 577         }
 578 }
 579
 580 /*
 581  * Entry function: Obtain entropy for the caller.
 582  *
 583  * This function invokes the entropy gathering logic as often to generate
 584  * as many bytes as requested by the caller. The entropy gathering logic
 585  * creates 64 bit per invocation.
 586  *
 587  * This function truncates the last 64 bit entropy value output to the exact
 588  * size specified by the caller.
 589  *
 590  * @ec [in] Reference to entropy collector
 591  * @data [in] pointer to buffer for storing random data -- buffer must already
 592  *            exist
 593  * @len [in] size of the buffer, specifying also the requested number of random
 594  *           in bytes
 595  *
 596  * @return 0 when request is fulfilled or an error
 597  *
 598  * The following error codes can occur:
 599  *      -1      entropy_collector is NULL or the generation failed
 600  *      -2      Intermittent health failure
 601  *      -3      Permanent health failure
 602  */
 603 int jent_read_entropy(struct rand_data *ec, unsigned char *data,
 604                       unsigned int len)
 605 {
 606         unsigned char *p = data;
 607
 608         if (!ec)
 609                 return -1;
 610
 611         while (len > 0) {
 612                 unsigned int tocopy, health_test_result;
 613
 614                 jent_gen_entropy(ec);
 615
 616                 health_test_result = jent_health_failure(ec);
 617                 if (health_test_result > JENT_PERMANENT_FAILURE_SHIFT) {
 618                         /*
 619                          * At this point, the Jitter RNG instance is considered
 620                          * as a failed instance. There is no rerun of the
 621                          * startup test any more, because the caller
 622                          * is assumed to not further use this instance.
 623                          */
 624                         return -3;
 625                 } else if (health_test_result) {
 626                         /*
 627                          * Perform startup health tests and return permanent
 628                          * error if it fails.
 629                          */
 630                         if (jent_entropy_init(0, 0, NULL, ec)) {
 631                                 /* Mark the permanent error */
 632                                 ec->health_failure &=
 633                                         JENT_RCT_FAILURE_PERMANENT |
 634                                         JENT_APT_FAILURE_PERMANENT;
 635                                 return -3;
 636                         }
 637
 638                         return -2;
 639                 }
 640
 641                 if ((DATA_SIZE_BITS / 8) < len)
 642                         tocopy = (DATA_SIZE_BITS / 8);
 643                 else
 644                         tocopy = len;
 645                 if (jent_read_random_block(ec->hash_state, p, tocopy))
 646                         return -1;
 647
 648                 len -= tocopy;
 649                 p += tocopy;
 650         }
 651
 652         return 0;
 653 }
 654
 655 /***************************************************************************
 656  * Initialization logic
 657  ***************************************************************************/
 658
 659 struct rand_data *jent_entropy_collector_alloc(unsigned int osr,
 660                                                unsigned int flags,
 661                                                void *hash_state)
 662 {
 663         struct rand_data *entropy_collector;
 664
 665         entropy_collector = jent_zalloc(sizeof(struct rand_data));
 666         if (!entropy_collector)
 667                 return NULL;
 668
 669         if (!(flags & JENT_DISABLE_MEMORY_ACCESS)) {
 670                 /* Allocate memory for adding variations based on memory
 671                  * access
 672                  */
 673                 entropy_collector->mem = jent_kvzalloc(JENT_MEMORY_SIZE);
 674                 if (!entropy_collector->mem) {
 675                         jent_zfree(entropy_collector);
 676                         return NULL;
 677                 }
 678                 entropy_collector->memblocksize =
 679                         CONFIG_CRYPTO_JITTERENTROPY_MEMORY_BLOCKSIZE;
 680                 entropy_collector->memblocks =
 681                         CONFIG_CRYPTO_JITTERENTROPY_MEMORY_BLOCKS;
 682                 entropy_collector->memaccessloops = JENT_MEMORY_ACCESSLOOPS;
 683         }
 684
 685         /* verify and set the oversampling rate */
 686         if (osr == 0)
 687                 osr = 1; /* H_submitter = 1 / osr */
 688         entropy_collector->osr = osr;
 689         entropy_collector->flags = flags;
 690
 691         entropy_collector->hash_state = hash_state;
 692
 693         /* Initialize the APT */
 694         jent_apt_init(entropy_collector, osr);
 695
 696         /* fill the data pad with non-zero values */
 697         jent_gen_entropy(entropy_collector);
 698
 699         return entropy_collector;
 700 }
 701
 702 void jent_entropy_collector_free(struct rand_data *entropy_collector)
 703 {
 704         jent_kvzfree(entropy_collector->mem, JENT_MEMORY_SIZE);
 705         entropy_collector->mem = NULL;
 706         jent_zfree(entropy_collector);
 707 }
 708
 709 int jent_entropy_init(unsigned int osr, unsigned int flags, void *hash_state,
 710                       struct rand_data *p_ec)
 711 {
 712         /*
 713          * If caller provides an allocated ec, reuse it which implies that the
 714          * health test entropy data is used to further still the available
 715          * entropy pool.
 716          */
 717         struct rand_data *ec = p_ec;
 718         int i, time_backwards = 0, ret = 0, ec_free = 0;
 719         unsigned int health_test_result;
 720
 721         if (!ec) {
 722                 ec = jent_entropy_collector_alloc(osr, flags, hash_state);
 723                 if (!ec)
 724                         return JENT_EMEM;
 725                 ec_free = 1;
 726         } else {
 727                 /* Reset the APT */
 728                 jent_apt_reset(ec, 0);
 729                 /* Ensure that a new APT base is obtained */
 730                 ec->apt_base_set = 0;
 731                 /* Reset the RCT */
 732                 ec->rct_count = 0;
 733                 /* Reset intermittent, leave permanent health test result */
 734                 ec->health_failure &= (~JENT_RCT_FAILURE);
 735                 ec->health_failure &= (~JENT_APT_FAILURE);
 736         }
 737
 738         /* We could perform statistical tests here, but the problem is
 739          * that we only have a few loop counts to do testing. These
 740          * loop counts may show some slight skew and we produce
 741          * false positives.
 742          *
 743          * Moreover, only old systems show potentially problematic
 744          * jitter entropy that could potentially be caught here. But
 745          * the RNG is intended for hardware that is available or widely
 746          * used, but not old systems that are long out of favor. Thus,
 747          * no statistical tests.
 748          */
 749
 750         /*
 751          * We could add a check for system capabilities such as clock_getres or
 752          * check for CONFIG_X86_TSC, but it does not make much sense as the
 753          * following sanity checks verify that we have a high-resolution
 754          * timer.
 755          */
 756         /*
 757          * TESTLOOPCOUNT needs some loops to identify edge systems. 100 is
 758          * definitely too little.
 759          *
 760          * SP800-90B requires at least 1024 initial test cycles.
 761          */
 762 #define TESTLOOPCOUNT 1024
 763 #define CLEARCACHE 100
 764         for (i = 0; (TESTLOOPCOUNT + CLEARCACHE) > i; i++) {
 765                 __u64 start_time = 0, end_time = 0, delta = 0;
 766
 767                 /* Invoke core entropy collection logic */
 768                 jent_measure_jitter(ec, &delta);
 769                 end_time = ec->prev_time;
 770                 start_time = ec->prev_time - delta;
 771
 772                 /* test whether timer works */
 773                 if (!start_time || !end_time) {
 774                         ret = JENT_ENOTIME;
 775                         goto out;
 776                 }
 777
 778                 /*
 779                  * test whether timer is fine grained enough to provide
 780                  * delta even when called shortly after each other -- this
 781                  * implies that we also have a high resolution timer
 782                  */
 783                 if (!delta || (end_time == start_time)) {
 784                         ret = JENT_ECOARSETIME;
 785                         goto out;
 786                 }
 787
 788                 /*
 789                  * up to here we did not modify any variable that will be
 790                  * evaluated later, but we already performed some work. Thus we
 791                  * already have had an impact on the caches, branch prediction,
 792                  * etc. with the goal to clear it to get the worst case
 793                  * measurements.
 794                  */
 795                 if (i < CLEARCACHE)
 796                         continue;
 797
 798                 /* test whether we have an increasing timer */
 799                 if (!(end_time > start_time))
 800                         time_backwards++;
 801         }
 802
 803         /*
 804          * we allow up to three times the time running backwards.
 805          * CLOCK_REALTIME is affected by adjtime and NTP operations. Thus,
 806          * if such an operation just happens to interfere with our test, it
 807          * should not fail. The value of 3 should cover the NTP case being
 808          * performed during our test run.
 809          */
 810         if (time_backwards > 3) {
 811                 ret = JENT_ENOMONOTONIC;
 812                 goto out;
 813         }
 814
 815         /* Did we encounter a health test failure? */
 816         health_test_result = jent_health_failure(ec);
 817         if (health_test_result) {
 818                 ret = (health_test_result & JENT_RCT_FAILURE) ? JENT_ERCT :
 819                                                                 JENT_EHEALTH;
 820                 goto out;
 821         }
 822
 823 out:
 824         if (ec_free)
 825                 jent_entropy_collector_free(ec);
 826
 827         return ret;
 828 }