cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
random_int.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * cryptlib Randomness Internal Interface *
4 * Copyright Peter Gutmann 1995-2006 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _RANDOM_INT_DEFINED
9 
10 #define _RANDOM_INT_DEFINED
11 
12 #if defined( INC_ALL )
13  #include "des.h"
14  #include "random.h"
15 #else
16  #include "crypt/des.h"
17  #include "random/random.h"
18 #endif /* Compiler-specific includes */
19 
20 /****************************************************************************
21 * *
22 * Randomness Constants and Data Types *
23 * *
24 ****************************************************************************/
25 
26 /* The maximum amount of random data needed by any cryptlib operation,
27  equivalent to the size of a maximum-length PKC key. However this isn't
28  the absolute length because when generating the k value for DLP
29  operations we get n + m bits and then reduce via one of the DLP
30  parameters to get the value within range. If we just got n bits this
31  would introduce a bias into the top bit, see the DLP code for more
32  details. Because of this we allow a length slightly larger than the
33  maximum PKC key size */
34 
35 #define MAX_RANDOM_BYTES ( CRYPT_MAX_PKCSIZE + 8 )
36 
37 /* The size in bytes of the randomness pool and the size of the X9.17
38  post-processor generator pool */
39 
40 #define RANDOMPOOL_SIZE 256
41 #define X917_POOLSIZE 8
42 
43 /* The allocated size of the randomness pool, which allows for the overflow
44  created by the fact that the hash function blocksize isn't any useful
45  multiple of a power of 2 */
46 
47 #define RANDOMPOOL_ALLOCSIZE ( ( ( RANDOMPOOL_SIZE + 20 - 1 ) / 20 ) * 20 )
48 
49 /* The number of short samples of previous output that we keep for the FIPS
50  140 continuous tests, and the number of retries that we perform if we
51  detect a repeat of a previous output */
52 
53 #define RANDOMPOOL_SAMPLES 16
54 #define RANDOMPOOL_RETRIES 5
55 
56 /* The number of times that we cycle the X9.17 generator before we load new
57  key and state variables. This means that we re-seed for every
58  X917_MAX_BYTES of output produced */
59 
60 #define X917_MAX_BYTES 4096
61 #define X917_MAX_CYCLES ( X917_MAX_BYTES / X917_POOLSIZE )
62 
63 /* In order to perform a FIPS 140-compliant check we have to signal a hard
64  failure on the first repeat value rather than retrying the operation in
65  case it's a one-off fault. In order to avoid problems with false
66  positives we take a larger-than-normal sample of RANDOMPOOL_SAMPLE_SIZE
67  bytes for the first value, which we compare as a backup check if the
68  standard short sample indicates a repeat */
69 
70 #define RANDOMPOOL_SAMPLE_SIZE 16
71 
72 /* The size of the X9.17 generator key, 112 bits for EDE 3DES, and the size
73  of the generator output, 64 bits */
74 
75 #define X917_KEYSIZE 16
76 #define X917_BLOCKSIZE X917_POOLSIZE
77 
78 /* The scheduled DES keys for the X9.17 generator */
79 
80 typedef struct {
81  Key_schedule desKey1, desKey2, desKey3;
82  } X917_3DES_KEY;
83 
84 #define DES_KEYSIZE sizeof( Key_schedule )
85 
86 /* Random pool information. We keep track of the write position in the
87  pool, which tracks where new data is added. Whenever we add new data the
88  write position is updated, once we reach the end of the pool we mix the
89  pool and start again at the beginning. We track the pool status by
90  recording the quality of the pool contents (1-100) and the number of
91  times the pool has been mixed, we can't draw data from the pool unless
92  both of these values have reached an acceptable level. In addition to
93  the pool state information we keep track of the previous
94  RANDOMPOOL_SAMPLES output samples to check for stuck-at faults or (short)
95  cyles */
96 
97 typedef struct {
98  /* Pool state information */
99  BUFFER( RANDOMPOOL_ALLOCSIZE, randomPoolPos ) \
100  BYTE randomPool[ RANDOMPOOL_ALLOCSIZE + 8 ];/* Random byte pool */
101  int randomPoolPos; /* Current write position in the pool */
102 
103  /* Pool status information */
104  int randomQuality; /* Level of randomness in the pool */
105  int randomPoolMixes; /* Number of times pool has been mixed */
106 
107  /* X9.17 generator state information */
108  BUFFER_FIXED( X917_POOLSIZE ) \
109  BYTE x917Pool[ X917_POOLSIZE + 8 ]; /* Generator state */
110  BUFFER_FIXED( X917_POOLSIZE ) \
111  BYTE x917DT[ X917_POOLSIZE + 8 ]; /* Date/time vector */
112  X917_3DES_KEY x917Key; /* Scheduled 3DES key */
113  BOOLEAN x917Inited; /* Whether generator has been inited */
114  int x917Count; /* No.of times generator has been cycled */
115  BOOLEAN useX931; /* X9.17 vs. X9.31 operation (see code comments */
116 
117  /* Information for the FIPS 140 continuous tests */
118  ARRAY( RANDOMPOOL_SAMPLES, prevOutputIndex ) \
119  unsigned long prevOutput[ RANDOMPOOL_SAMPLES + 2 ];
120  ARRAY( RANDOMPOOL_SAMPLES, prevOutputIndex ) \
121  unsigned long x917PrevOutput[ RANDOMPOOL_SAMPLES + 2 ];
122  int prevOutputIndex;
123  BUFFER_FIXED( RANDOMPOOL_SAMPLE_SIZE ) \
124  BYTE x917OuputSample[ RANDOMPOOL_SAMPLE_SIZE + 8 ];
125 
126 #if 0 /* See comment in addEntropyQuality */
127  /* Other status information used to check the pool's operation */
128  int entropyByteCount; /* Number of bytes entropy added */
129 #endif /* 0 */
130 
131  /* Random seed data information if seeding is done from a stored seed */
132 #ifdef CONFIG_RANDSEED
133  BOOLEAN seedProcessed; /* Whether stored seed has been processed */
134  int seedSize; /* Size of stored seed data */
135  int seedUpdateCount; /* When to update stored seed data */
136 #endif /* CONFIG_RANDSEED */
137  } RANDOM_INFO;
138 
139 
140 /****************************************************************************
141 * *
142 * Randomness Internal Interface Functions *
143 * *
144 ****************************************************************************/
145 
146 /* Prototypes for functions in random.c */
147 
148 STDC_NONNULL_ARG( ( 1 ) ) \
149 void initRandomPool( INOUT RANDOM_INFO *randomInfo );
150 STDC_NONNULL_ARG( ( 1 ) ) \
151 void endRandomPool( INOUT RANDOM_INFO *randomInfo );
152 
153 /* Prototypes for functions in rand_x917.c */
154 
155 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2, 3 ) ) \
156 int setKeyX917( INOUT RANDOM_INFO *testRandomInfo,
157  IN_BUFFER_C( X917_KEYSIZE ) const BYTE *key,
158  IN_BUFFER_C( X917_POOLSIZE ) const BYTE *state,
159  IN_BUFFER_OPT_C( X917_POOLSIZE ) const BYTE *dateTime );
160 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
161 int generateX917( INOUT RANDOM_INFO *testRandomInfo,
162  INOUT_BUFFER_FIXED( length ) BYTE *data,
163  IN_RANGE( 1, MAX_RANDOM_BYTES ) const int length );
164 CHECK_RETVAL \
165 int randomAlgorithmSelfTest( void );
166 CHECK_RETVAL \
167 int selfTestX917( INOUT RANDOM_INFO *randomInfo,
168  IN_BUFFER_C( X917_KEYSIZE ) const BYTE *key );
169 CHECK_RETVAL \
170 int fipsTestX917( INOUT RANDOM_INFO *randomInfo );
171 
172 #endif /* _RANDOM_INT_DEFINED */
Generated on Thu Jan 10 2013 10:00:51 for cryptlib by   doxygen 1.8.2