diff options
Diffstat (limited to 'src/lib/libcrypto/doc/RAND_add.pod')
-rw-r--r-- | src/lib/libcrypto/doc/RAND_add.pod | 77 |
1 files changed, 0 insertions, 77 deletions
diff --git a/src/lib/libcrypto/doc/RAND_add.pod b/src/lib/libcrypto/doc/RAND_add.pod deleted file mode 100644 index 67c66f3e0c..0000000000 --- a/src/lib/libcrypto/doc/RAND_add.pod +++ /dev/null | |||
@@ -1,77 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add | ||
6 | entropy to the PRNG | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/rand.h> | ||
11 | |||
12 | void RAND_seed(const void *buf, int num); | ||
13 | |||
14 | void RAND_add(const void *buf, int num, double entropy); | ||
15 | |||
16 | int RAND_status(void); | ||
17 | |||
18 | int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); | ||
19 | void RAND_screen(void); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, | ||
24 | if the data at B<buf> are unpredictable to an adversary, this | ||
25 | increases the uncertainty about the state and makes the PRNG output | ||
26 | less predictable. Suitable input comes from user interaction (random | ||
27 | key presses, mouse movements) and certain hardware events. The | ||
28 | B<entropy> argument is (the lower bound of) an estimate of how much | ||
29 | randomness is contained in B<buf>, measured in bytes. Details about | ||
30 | sources of randomness and how to estimate their entropy can be found | ||
31 | in the literature, e.g. RFC 1750. | ||
32 | |||
33 | RAND_add() may be called with sensitive data such as user entered | ||
34 | passwords. The seed values cannot be recovered from the PRNG output. | ||
35 | |||
36 | OpenSSL makes sure that the PRNG state is unique for each thread. On | ||
37 | systems that provide C</dev/urandom>, the randomness device is used | ||
38 | to seed the PRNG transparently. However, on all other systems, the | ||
39 | application is responsible for seeding the PRNG by calling RAND_add(), | ||
40 | L<RAND_egd(3)|RAND_egd(3)> | ||
41 | or L<RAND_load_file(3)|RAND_load_file(3)>. | ||
42 | |||
43 | RAND_seed() is equivalent to RAND_add() when B<num == entropy>. | ||
44 | |||
45 | RAND_event() collects the entropy from Windows events such as mouse | ||
46 | movements and other user interaction. It should be called with the | ||
47 | B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to | ||
48 | the window procedure. It will estimate the entropy contained in the | ||
49 | event message (if any), and add it to the PRNG. The program can then | ||
50 | process the messages as usual. | ||
51 | |||
52 | The RAND_screen() function is available for the convenience of Windows | ||
53 | programmers. It adds the current contents of the screen to the PRNG. | ||
54 | For applications that can catch Windows events, seeding the PRNG by | ||
55 | calling RAND_event() is a significantly better source of | ||
56 | randomness. It should be noted that both methods cannot be used on | ||
57 | servers that run without user interaction. | ||
58 | |||
59 | =head1 RETURN VALUES | ||
60 | |||
61 | RAND_status() and RAND_event() return 1 if the PRNG has been seeded | ||
62 | with enough data, 0 otherwise. | ||
63 | |||
64 | The other functions do not return values. | ||
65 | |||
66 | =head1 SEE ALSO | ||
67 | |||
68 | L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, | ||
69 | L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> | ||
70 | |||
71 | =head1 HISTORY | ||
72 | |||
73 | RAND_seed() and RAND_screen() are available in all versions of SSLeay | ||
74 | and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL | ||
75 | 0.9.5, RAND_event() in OpenSSL 0.9.5a. | ||
76 | |||
77 | =cut | ||