]>
Commit | Line | Data |
---|---|---|
60b52453 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4d524e10 | 5 | rand - pseudo-random number generator |
60b52453 UM |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/rand.h> | |
10 | ||
5bf73873 GT |
11 | int RAND_set_rand_engine(ENGINE *engine); |
12 | ||
fba90464 BM |
13 | int RAND_bytes(unsigned char *buf, int num); |
14 | int RAND_pseudo_bytes(unsigned char *buf, int num); | |
60b52453 | 15 | |
fba90464 BM |
16 | void RAND_seed(const void *buf, int num); |
17 | void RAND_add(const void *buf, int num, int entropy); | |
4ec2d4d2 | 18 | int RAND_status(void); |
60b52453 | 19 | |
fba90464 | 20 | int RAND_load_file(const char *file, long max_bytes); |
60b52453 | 21 | int RAND_write_file(const char *file); |
fba90464 | 22 | const char *RAND_file_name(char *file, size_t num); |
60b52453 | 23 | |
4ec2d4d2 UM |
24 | int RAND_egd(const char *path); |
25 | ||
5bf73873 GT |
26 | void RAND_set_rand_method(const RAND_METHOD *meth); |
27 | const RAND_METHOD *RAND_get_rand_method(void); | |
60b52453 UM |
28 | RAND_METHOD *RAND_SSLeay(void); |
29 | ||
30 | void RAND_cleanup(void); | |
31 | ||
5bf73873 GT |
32 | /* For Win32 only */ |
33 | void RAND_screen(void); | |
34 | int RAND_event(UINT, WPARAM, LPARAM); | |
35 | ||
60b52453 UM |
36 | =head1 DESCRIPTION |
37 | ||
5bf73873 GT |
38 | Since the introduction of the ENGINE API, the recommended way of controlling |
39 | default implementations is by using the ENGINE API functions. The default | |
40 | B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by | |
41 | RAND_get_rand_method(), is only used if no ENGINE has been set as the default | |
cda01d55 | 42 | "rand" implementation. Hence, these two functions are no longer the recommended |
5bf73873 GT |
43 | way to control defaults. |
44 | ||
45 | If an alternative B<RAND_METHOD> implementation is being used (either set | |
46 | directly or as provided by an ENGINE module), then it is entirely responsible | |
47 | for the generation and management of a cryptographically secure PRNG stream. The | |
48 | mechanisms described below relate solely to the software PRNG implementation | |
49 | built in to OpenSSL and used by default. | |
50 | ||
60b52453 UM |
51 | These functions implement a cryptographically secure pseudo-random |
52 | number generator (PRNG). It is used by other library functions for | |
53 | example to generate random keys, and applications can use it when they | |
54 | need randomness. | |
55 | ||
56 | A cryptographic PRNG must be seeded with unpredictable data such as | |
57 | mouse movements or keys pressed at random by the user. This is | |
9b86974e RS |
58 | described in L<RAND_add(3)>. Its state can be saved in a seed file |
59 | (see L<RAND_load_file(3)>) to avoid having to go through the | |
bb075f88 | 60 | seeding process whenever the application is started. |
60b52453 | 61 | |
9b86974e | 62 | L<RAND_bytes(3)> describes how to obtain random data from the |
bb075f88 | 63 | PRNG. |
60b52453 UM |
64 | |
65 | =head1 INTERNALS | |
66 | ||
67 | The RAND_SSLeay() method implements a PRNG based on a cryptographic | |
68 | hash function. | |
69 | ||
70 | The following description of its design is based on the SSLeay | |
71 | documentation: | |
72 | ||
73 | First up I will state the things I believe I need for a good RNG. | |
74 | ||
75 | =over 4 | |
76 | ||
77 | =item 1 | |
78 | ||
79 | A good hashing algorithm to mix things up and to convert the RNG 'state' | |
80 | to random numbers. | |
81 | ||
82 | =item 2 | |
83 | ||
84 | An initial source of random 'state'. | |
85 | ||
86 | =item 3 | |
87 | ||
88 | The state should be very large. If the RNG is being used to generate | |
89 | 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). | |
90 | If your RNG state only has 128 bits, you are obviously limiting the | |
91 | search space to 128 bits, not 2048. I'm probably getting a little | |
92 | carried away on this last point but it does indicate that it may not be | |
93 | a bad idea to keep quite a lot of RNG state. It should be easier to | |
94 | break a cipher than guess the RNG seed data. | |
95 | ||
96 | =item 4 | |
97 | ||
98 | Any RNG seed data should influence all subsequent random numbers | |
99 | generated. This implies that any random seed data entered will have | |
100 | an influence on all subsequent random numbers generated. | |
101 | ||
102 | =item 5 | |
103 | ||
104 | When using data to seed the RNG state, the data used should not be | |
105 | extractable from the RNG state. I believe this should be a | |
106 | requirement because one possible source of 'secret' semi random | |
107 | data would be a private key or a password. This data must | |
108 | not be disclosed by either subsequent random numbers or a | |
109 | 'core' dump left by a program crash. | |
110 | ||
111 | =item 6 | |
112 | ||
113 | Given the same initial 'state', 2 systems should deviate in their RNG state | |
114 | (and hence the random numbers generated) over time if at all possible. | |
115 | ||
116 | =item 7 | |
117 | ||
118 | Given the random number output stream, it should not be possible to determine | |
119 | the RNG state or the next random number. | |
120 | ||
121 | =back | |
122 | ||
123 | The algorithm is as follows. | |
124 | ||
125 | There is global state made up of a 1023 byte buffer (the 'state'), a | |
c88a900f | 126 | working hash value ('md'), and a counter ('count'). |
60b52453 UM |
127 | |
128 | Whenever seed data is added, it is inserted into the 'state' as | |
129 | follows. | |
130 | ||
c88a900f | 131 | The input is chopped up into units of 20 bytes (or less for |
0b5cfe32 UM |
132 | the last block). Each of these blocks is run through the hash |
133 | function as follows: The data passed to the hash function | |
134 | is the current 'md', the same number of bytes from the 'state' | |
135 | (the location determined by in incremented looping index) as | |
136 | the current 'block', the new key data 'block', and 'count' | |
137 | (which is incremented after each use). | |
138 | The result of this is kept in 'md' and also xored into the | |
139 | 'state' at the same locations that were used as input into the | |
140 | hash function. I | |
60b52453 UM |
141 | believe this system addresses points 1 (hash function; currently |
142 | SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash | |
143 | function and xor). | |
144 | ||
145 | When bytes are extracted from the RNG, the following process is used. | |
c88a900f | 146 | For each group of 10 bytes (or less), we do the following: |
60b52453 | 147 | |
e9ad0d2c BM |
148 | Input into the hash function the local 'md' (which is initialized from |
149 | the global 'md' before any bytes are generated), the bytes that are to | |
150 | be overwritten by the random bytes, and bytes from the 'state' | |
151 | (incrementing looping index). From this digest output (which is kept | |
152 | in 'md'), the top (up to) 10 bytes are returned to the caller and the | |
153 | bottom 10 bytes are xored into the 'state'. | |
60b52453 | 154 | |
37794691 UM |
155 | Finally, after we have finished 'num' random bytes for the caller, |
156 | 'count' (which is incremented) and the local and global 'md' are fed | |
157 | into the hash function and the results are kept in the global 'md'. | |
158 | ||
159 | I believe the above addressed points 1 (use of SHA-1), 6 (by hashing | |
160 | into the 'state' the 'old' data from the caller that is about to be | |
c88a900f | 161 | overwritten) and 7 (by not using the 10 bytes given to the caller to |
37794691 | 162 | update the 'state', but they are used to update 'md'). |
60b52453 UM |
163 | |
164 | So of the points raised, only 2 is not addressed (but see | |
9b86974e | 165 | L<RAND_add(3)>). |
60b52453 UM |
166 | |
167 | =head1 SEE ALSO | |
168 | ||
9b86974e RS |
169 | L<BN_rand(3)>, L<RAND_add(3)>, |
170 | L<RAND_load_file(3)>, L<RAND_egd(3)>, | |
171 | L<RAND_bytes(3)>, | |
172 | L<RAND_set_rand_method(3)>, | |
173 | L<RAND_cleanup(3)> | |
60b52453 UM |
174 | |
175 | =cut |