選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。

entropy.c 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479
  1. /*
  2. * Copyright (C) 2012 Michael Brown <mbrown@fensystems.co.uk>.
  3. *
  4. * This program is free software; you can redistribute it and/or
  5. * modify it under the terms of the GNU General Public License as
  6. * published by the Free Software Foundation; either version 2 of the
  7. * License, or any later version.
  8. *
  9. * This program is distributed in the hope that it will be useful, but
  10. * WITHOUT ANY WARRANTY; without even the implied warranty of
  11. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12. * General Public License for more details.
  13. *
  14. * You should have received a copy of the GNU General Public License
  15. * along with this program; if not, write to the Free Software
  16. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17. * 02110-1301, USA.
  18. */
  19. FILE_LICENCE ( GPL2_OR_LATER );
  20. /** @file
  21. *
  22. * Entropy source
  23. *
  24. * This algorithm is designed to comply with ANS X9.82 Part 4 (April
  25. * 2011 Draft) Section 13.3. This standard is unfortunately not
  26. * freely available.
  27. */
  28. #include <stdint.h>
  29. #include <assert.h>
  30. #include <string.h>
  31. #include <errno.h>
  32. #include <ipxe/crypto.h>
  33. #include <ipxe/hash_df.h>
  34. #include <ipxe/entropy.h>
  35. /* Disambiguate the various error causes */
  36. #define EPIPE_REPETITION_COUNT_TEST \
  37. __einfo_error ( EINFO_EPIPE_REPETITION_COUNT_TEST )
  38. #define EINFO_EPIPE_REPETITION_COUNT_TEST \
  39. __einfo_uniqify ( EINFO_EPIPE, 0x01, "Repetition count test failed" )
  40. #define EPIPE_ADAPTIVE_PROPORTION_TEST \
  41. __einfo_error ( EINFO_EPIPE_ADAPTIVE_PROPORTION_TEST )
  42. #define EINFO_EPIPE_ADAPTIVE_PROPORTION_TEST \
  43. __einfo_uniqify ( EINFO_EPIPE, 0x02, "Adaptive proportion test failed" )
  44. /**
  45. * Calculate cutoff value for the repetition count test
  46. *
  47. * @ret cutoff Cutoff value
  48. *
  49. * This is the cutoff value for the Repetition Count Test defined in
  50. * ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.2.
  51. */
  52. static inline __attribute__ (( always_inline )) unsigned int
  53. repetition_count_cutoff ( void ) {
  54. double max_repetitions;
  55. unsigned int cutoff;
  56. /* The cutoff formula for the repetition test is:
  57. *
  58. * C = ( 1 + ( -log2(W) / H_min ) )
  59. *
  60. * where W is set at 2^(-30) (in ANS X9.82 Part 2 (October
  61. * 2011 Draft) Section 8.5.2.1.3.1).
  62. */
  63. max_repetitions = ( 1 + ( 30 / min_entropy_per_sample() ) );
  64. /* Round up to a whole number of repetitions. We don't have
  65. * the ceil() function available, so do the rounding by hand.
  66. */
  67. cutoff = max_repetitions;
  68. if ( cutoff < max_repetitions )
  69. cutoff++;
  70. linker_assert ( ( cutoff >= max_repetitions ), rounding_error );
  71. /* Floating-point operations are not allowed in iPXE since we
  72. * never set up a suitable environment. Abort the build
  73. * unless the calculated number of repetitions is a
  74. * compile-time constant.
  75. */
  76. linker_assert ( __builtin_constant_p ( cutoff ),
  77. repetition_count_cutoff_not_constant );
  78. return cutoff;
  79. }
  80. /**
  81. * Perform repetition count test
  82. *
  83. * @v sample Noise sample
  84. * @ret rc Return status code
  85. *
  86. * This is the Repetition Count Test defined in ANS X9.82 Part 2
  87. * (October 2011 Draft) Section 8.5.2.1.2.
  88. */
  89. static int repetition_count_test ( noise_sample_t sample ) {
  90. static noise_sample_t most_recent_sample;
  91. static unsigned int repetition_count = 0;
  92. /* A = the most recently seen sample value
  93. * B = the number of times that value A has been seen in a row
  94. * C = the cutoff value above which the repetition test should fail
  95. */
  96. /* 1. For each new sample processed:
  97. *
  98. * (Note that the test for "repetition_count > 0" ensures that
  99. * the initial value of most_recent_sample is treated as being
  100. * undefined.)
  101. */
  102. if ( ( sample == most_recent_sample ) && ( repetition_count > 0 ) ) {
  103. /* a) If the new sample = A, then B is incremented by one. */
  104. repetition_count++;
  105. /* i. If B >= C, then an error condition is raised
  106. * due to a failure of the test
  107. */
  108. if ( repetition_count >= repetition_count_cutoff() )
  109. return -EPIPE_REPETITION_COUNT_TEST;
  110. } else {
  111. /* b) Else:
  112. * i. A = new sample
  113. */
  114. most_recent_sample = sample;
  115. /* ii. B = 1 */
  116. repetition_count = 1;
  117. }
  118. return 0;
  119. }
  120. /**
  121. * Window size for the adaptive proportion test
  122. *
  123. * ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.1.1 allows
  124. * five possible window sizes: 16, 64, 256, 4096 and 65536.
  125. *
  126. * We expect to generate relatively few (<256) entropy samples during
  127. * a typical iPXE run; the use of a large window size would mean that
  128. * the test would never complete a single cycle. We use a window size
  129. * of 64, which is the smallest window size that permits values of
  130. * H_min down to one bit per sample.
  131. */
  132. #define ADAPTIVE_PROPORTION_WINDOW_SIZE 64
  133. /**
  134. * Combine adaptive proportion test window size and min-entropy
  135. *
  136. * @v n N (window size)
  137. * @v h H (min-entropy)
  138. * @ret n_h (N,H) combined value
  139. */
  140. #define APC_N_H( n, h ) ( ( (n) << 8 ) | (h) )
  141. /**
  142. * Define a row of the adaptive proportion cutoff table
  143. *
  144. * @v h H (min-entropy)
  145. * @v c16 Cutoff for N=16
  146. * @v c64 Cutoff for N=64
  147. * @v c256 Cutoff for N=256
  148. * @v c4096 Cutoff for N=4096
  149. * @v c65536 Cutoff for N=65536
  150. */
  151. #define APC_TABLE_ROW( h, c16, c64, c256, c4096, c65536) \
  152. case APC_N_H ( 16, h ) : return c16; \
  153. case APC_N_H ( 64, h ) : return c64; \
  154. case APC_N_H ( 256, h ) : return c256; \
  155. case APC_N_H ( 4096, h ) : return c4096; \
  156. case APC_N_H ( 65536, h ) : return c65536;
  157. /** Value used to represent "N/A" in adaptive proportion cutoff table */
  158. #define APC_NA 0
  159. /**
  160. * Look up value in adaptive proportion test cutoff table
  161. *
  162. * @v n N (window size)
  163. * @v h H (min-entropy)
  164. * @ret cutoff Cutoff
  165. *
  166. * This is the table of cutoff values defined in ANS X9.82 Part 2
  167. * (October 2011 Draft) Section 8.5.2.1.3.1.2.
  168. */
  169. static inline __attribute__ (( always_inline )) unsigned int
  170. adaptive_proportion_cutoff_lookup ( unsigned int n, unsigned int h ) {
  171. switch ( APC_N_H ( n, h ) ) {
  172. APC_TABLE_ROW ( 1, APC_NA, 51, 168, 2240, 33537 );
  173. APC_TABLE_ROW ( 2, APC_NA, 35, 100, 1193, 17053 );
  174. APC_TABLE_ROW ( 3, 10, 24, 61, 643, 8705 );
  175. APC_TABLE_ROW ( 4, 8, 16, 38, 354, 4473 );
  176. APC_TABLE_ROW ( 5, 6, 12, 25, 200, 2321 );
  177. APC_TABLE_ROW ( 6, 5, 9, 17, 117, 1220 );
  178. APC_TABLE_ROW ( 7, 4, 7, 15, 71, 653 );
  179. APC_TABLE_ROW ( 8, 4, 5, 9, 45, 358 );
  180. APC_TABLE_ROW ( 9, 3, 4, 7, 30, 202 );
  181. APC_TABLE_ROW ( 10, 3, 4, 5, 21, 118 );
  182. APC_TABLE_ROW ( 11, 2, 3, 4, 15, 71 );
  183. APC_TABLE_ROW ( 12, 2, 3, 4, 11, 45 );
  184. APC_TABLE_ROW ( 13, 2, 2, 3, 9, 30 );
  185. APC_TABLE_ROW ( 14, 2, 2, 3, 7, 21 );
  186. APC_TABLE_ROW ( 15, 1, 2, 2, 6, 15 );
  187. APC_TABLE_ROW ( 16, 1, 2, 2, 5, 11 );
  188. APC_TABLE_ROW ( 17, 1, 1, 2, 4, 9 );
  189. APC_TABLE_ROW ( 18, 1, 1, 2, 4, 7 );
  190. APC_TABLE_ROW ( 19, 1, 1, 1, 3, 6 );
  191. APC_TABLE_ROW ( 20, 1, 1, 1, 3, 5 );
  192. default:
  193. return APC_NA;
  194. }
  195. }
  196. /**
  197. * Calculate cutoff value for the adaptive proportion test
  198. *
  199. * @ret cutoff Cutoff value
  200. *
  201. * This is the cutoff value for the Adaptive Proportion Test defined
  202. * in ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.1.2.
  203. */
  204. static inline __attribute__ (( always_inline )) unsigned int
  205. adaptive_proportion_cutoff ( void ) {
  206. unsigned int h;
  207. unsigned int n;
  208. unsigned int cutoff;
  209. /* Look up cutoff value in cutoff table */
  210. n = ADAPTIVE_PROPORTION_WINDOW_SIZE;
  211. h = min_entropy_per_sample();
  212. cutoff = adaptive_proportion_cutoff_lookup ( n, h );
  213. /* Fail unless cutoff value is a build-time constant */
  214. linker_assert ( __builtin_constant_p ( cutoff ),
  215. adaptive_proportion_cutoff_not_constant );
  216. /* Fail if cutoff value is N/A */
  217. linker_assert ( ( cutoff != APC_NA ),
  218. adaptive_proportion_cutoff_not_applicable );
  219. return cutoff;
  220. }
  221. /**
  222. * Perform adaptive proportion test
  223. *
  224. * @v sample Noise sample
  225. * @ret rc Return status code
  226. *
  227. * This is the Adaptive Proportion Test for the Most Common Value
  228. * defined in ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.3.
  229. */
  230. static int adaptive_proportion_test ( noise_sample_t sample ) {
  231. static noise_sample_t current_counted_sample;
  232. static unsigned int sample_count = ADAPTIVE_PROPORTION_WINDOW_SIZE;
  233. static unsigned int repetition_count;
  234. /* A = the sample value currently being counted
  235. * B = the number of samples examined in this run of the test so far
  236. * N = the total number of samples that must be observed in
  237. * one run of the test, also known as the "window size" of
  238. * the test
  239. * B = the current number of times that S (sic) has been seen
  240. * in the W (sic) samples examined so far
  241. * C = the cutoff value above which the repetition test should fail
  242. * W = the probability of a false positive: 2^-30
  243. */
  244. /* 1. The entropy source draws the current sample from the
  245. * noise source.
  246. *
  247. * (Nothing to do; we already have the current sample.)
  248. */
  249. /* 2. If S = N, then a new run of the test begins: */
  250. if ( sample_count == ADAPTIVE_PROPORTION_WINDOW_SIZE ) {
  251. /* a. A = the current sample */
  252. current_counted_sample = sample;
  253. /* b. S = 0 */
  254. sample_count = 0;
  255. /* c. B = 0 */
  256. repetition_count = 0;
  257. } else {
  258. /* Else: (the test is already running)
  259. * a. S = S + 1
  260. */
  261. sample_count++;
  262. /* b. If A = the current sample, then: */
  263. if ( sample == current_counted_sample ) {
  264. /* i. B = B + 1 */
  265. repetition_count++;
  266. /* ii. If S (sic) > C then raise an error
  267. * condition, because the test has
  268. * detected a failure
  269. */
  270. if ( repetition_count > adaptive_proportion_cutoff() )
  271. return -EPIPE_ADAPTIVE_PROPORTION_TEST;
  272. }
  273. }
  274. return 0;
  275. }
  276. /**
  277. * Get entropy sample
  278. *
  279. * @ret entropy Entropy sample
  280. * @ret rc Return status code
  281. *
  282. * This is the GetEntropy function defined in ANS X9.82 Part 2
  283. * (October 2011 Draft) Section 6.5.1.
  284. */
  285. static int get_entropy ( entropy_sample_t *entropy ) {
  286. static int rc = 0;
  287. noise_sample_t noise;
  288. /* Any failure is permanent */
  289. if ( rc != 0 )
  290. return rc;
  291. /* Get noise sample */
  292. if ( ( rc = get_noise ( &noise ) ) != 0 )
  293. return rc;
  294. /* Perform Repetition Count Test and Adaptive Proportion Test
  295. * as mandated by ANS X9.82 Part 2 (October 2011 Draft)
  296. * Section 8.5.2.1.1.
  297. */
  298. if ( ( rc = repetition_count_test ( noise ) ) != 0 )
  299. return rc;
  300. if ( ( rc = adaptive_proportion_test ( noise ) ) != 0 )
  301. return rc;
  302. /* We do not use any optional conditioning component */
  303. *entropy = noise;
  304. return 0;
  305. }
  306. /**
  307. * Calculate number of samples required for startup tests
  308. *
  309. * @ret num_samples Number of samples required
  310. *
  311. * ANS X9.82 Part 2 (October 2011 Draft) Section 8.5.2.1.5 requires
  312. * that at least one full cycle of the continuous tests must be
  313. * performed at start-up.
  314. */
  315. static inline __attribute__ (( always_inline )) unsigned int
  316. startup_test_count ( void ) {
  317. unsigned int num_samples;
  318. /* At least max(N,C) samples shall be generated by the noise
  319. * source for start-up testing.
  320. */
  321. num_samples = repetition_count_cutoff();
  322. if ( num_samples < adaptive_proportion_cutoff() )
  323. num_samples = adaptive_proportion_cutoff();
  324. linker_assert ( __builtin_constant_p ( num_samples ),
  325. startup_test_count_not_constant );
  326. return num_samples;
  327. }
  328. /**
  329. * Create next nonce value
  330. *
  331. * @ret nonce Nonce
  332. *
  333. * This is the MakeNextNonce function defined in ANS X9.82 Part 4
  334. * (April 2011 Draft) Section 13.3.4.2.
  335. */
  336. static uint32_t make_next_nonce ( void ) {
  337. static uint32_t nonce;
  338. /* The simplest implementation of a nonce uses a large counter */
  339. nonce++;
  340. return nonce;
  341. }
  342. /**
  343. * Obtain entropy input temporary buffer
  344. *
  345. * @v num_samples Number of entropy samples
  346. * @v tmp Temporary buffer
  347. * @v tmp_len Length of temporary buffer
  348. * @ret rc Return status code
  349. *
  350. * This is (part of) the implementation of the Get_entropy_input
  351. * function (using an entropy source as the source of entropy input
  352. * and condensing each entropy source output after each GetEntropy
  353. * call) as defined in ANS X9.82 Part 4 (April 2011 Draft) Section
  354. * 13.3.4.2.
  355. *
  356. * To minimise code size, the number of samples required is calculated
  357. * at compilation time.
  358. */
  359. int get_entropy_input_tmp ( unsigned int num_samples, uint8_t *tmp,
  360. size_t tmp_len ) {
  361. static unsigned int startup_tested = 0;
  362. struct {
  363. uint32_t nonce;
  364. entropy_sample_t sample;
  365. } __attribute__ (( packed )) data;;
  366. uint8_t df_buf[tmp_len];
  367. unsigned int i;
  368. int rc;
  369. /* Enable entropy gathering */
  370. if ( ( rc = entropy_enable() ) != 0 )
  371. return rc;
  372. /* Perform mandatory startup tests, if not yet performed */
  373. for ( ; startup_tested < startup_test_count() ; startup_tested++ ) {
  374. if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
  375. goto err_get_entropy;
  376. }
  377. /* 3. entropy_total = 0
  378. *
  379. * (Nothing to do; the number of entropy samples required has
  380. * already been precalculated.)
  381. */
  382. /* 4. tmp = a fixed n-bit value, such as 0^n */
  383. memset ( tmp, 0, tmp_len );
  384. /* 5. While ( entropy_total < min_entropy ) */
  385. while ( num_samples-- ) {
  386. /* 5.1. ( status, entropy_bitstring, assessed_entropy )
  387. * = GetEntropy()
  388. * 5.2. If status indicates an error, return ( status, Null )
  389. */
  390. if ( ( rc = get_entropy ( &data.sample ) ) != 0 )
  391. goto err_get_entropy;
  392. /* 5.3. nonce = MakeNextNonce() */
  393. data.nonce = make_next_nonce();
  394. /* 5.4. tmp = tmp XOR
  395. * df ( ( nonce || entropy_bitstring ), n )
  396. */
  397. hash_df ( &entropy_hash_df_algorithm, &data, sizeof ( data ),
  398. df_buf, sizeof ( df_buf ) );
  399. for ( i = 0 ; i < tmp_len ; i++ )
  400. tmp[i] ^= df_buf[i];
  401. /* 5.5. entropy_total = entropy_total + assessed_entropy
  402. *
  403. * (Nothing to do; the number of entropy samples
  404. * required has already been precalculated.)
  405. */
  406. }
  407. /* Disable entropy gathering */
  408. entropy_disable();
  409. return 0;
  410. err_get_entropy:
  411. entropy_disable();
  412. return rc;
  413. }