]>
Commit | Line | Data |
---|---|---|
4ec2d4d2 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon |
4ec2d4d2 UM |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/rand.h> | |
10 | ||
11 | int RAND_egd(const char *path); | |
420125f9 LJ |
12 | int RAND_egd_bytes(const char *path, int bytes); |
13 | ||
14 | int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes); | |
4ec2d4d2 UM |
15 | |
16 | =head1 DESCRIPTION | |
17 | ||
f367ac2b | 18 | RAND_egd() queries the Entropy Gathering Daemon (EGD) on socket B<path>. |
9b86974e | 19 | It queries 255 bytes and uses L<RAND_add(3)> to seed the |
420125f9 LJ |
20 | OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for |
21 | RAND_egd_bytes(path, 255); | |
22 | ||
f367ac2b | 23 | RAND_egd_bytes() queries EGD on socket B<path>. |
9b86974e | 24 | It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the |
420125f9 | 25 | OpenSSL built-in PRNG. |
9fbc45b1 UM |
26 | This function is more flexible than RAND_egd(). |
27 | When only one secret key must | |
28 | be generated, it is not necessary to request the full amount 255 bytes from | |
f367ac2b | 29 | the EGD socket. This can be advantageous, since the amount of randomness |
9fbc45b1 | 30 | that can be retrieved from EGD over time is limited. |
420125f9 LJ |
31 | |
32 | RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket | |
33 | B<path>. If B<buf> is given, B<bytes> bytes are queried and written into | |
34 | B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the | |
9b86974e | 35 | OpenSSL built-in PRNG using L<RAND_add(3)>. |
420125f9 LJ |
36 | |
37 | =head1 NOTES | |
38 | ||
f367ac2b RS |
39 | On systems without /dev/*random devices providing randomness from the kernel, |
40 | EGD provides | |
41 | a socket interface through which randomness can be gathered in chunks up to | |
420125f9 LJ |
42 | 255 bytes. Several chunks can be queried during one connection. |
43 | ||
390ead1e UM |
44 | EGD is available from http://www.lothar.com/tech/crypto/ (C<perl |
45 | Makefile.PL; make; make install> to install). It is run as B<egd> | |
46 | I<path>, where I<path> is an absolute path designating a socket. When | |
47 | RAND_egd() is called with that path as an argument, it tries to read | |
f367ac2b | 48 | random bytes that EGD has collected. RAND_egd() retrieves randomness from the |
706c5a4d LJ |
49 | daemon using the daemon's "non-blocking read" command which shall |
50 | be answered immediately by the daemon without waiting for additional | |
f367ac2b | 51 | randomness to be collected. The write and read socket operations in the |
706c5a4d | 52 | communication are blocking. |
390ead1e | 53 | |
420125f9 | 54 | Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is |
e0b0dc11 | 55 | available from |
8ac40b4d | 56 | http://prngd.sourceforge.net/ . |
420125f9 | 57 | PRNGD does employ an internal PRNG itself and can therefore never run |
f367ac2b | 58 | out of randomness. |
e0b0dc11 | 59 | |
f367ac2b | 60 | OpenSSL automatically queries EGD when randomness is requested via RAND_bytes() |
96dfab9e LJ |
61 | or the status is checked via RAND_status() for the first time, if the socket |
62 | is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool. | |
466e4249 | 63 | |
390ead1e | 64 | =head1 RETURN VALUE |
4ec2d4d2 | 65 | |
420125f9 LJ |
66 | RAND_egd() and RAND_egd_bytes() return the number of bytes read from the |
67 | daemon on success, and -1 if the connection failed or the daemon did not | |
68 | return enough data to fully seed the PRNG. | |
69 | ||
70 | RAND_query_egd_bytes() returns the number of bytes read from the daemon on | |
71 | success, and -1 if the connection failed. The PRNG state is not considered. | |
4ec2d4d2 UM |
72 | |
73 | =head1 SEE ALSO | |
74 | ||
b97fdb57 | 75 | L<RAND_bytes(3)>, L<RAND_add(3)>, |
9b86974e | 76 | L<RAND_cleanup(3)> |
4ec2d4d2 | 77 | |
e2f92610 RS |
78 | =head1 COPYRIGHT |
79 | ||
80 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
81 | ||
82 | Licensed under the OpenSSL license (the "License"). You may not use | |
83 | this file except in compliance with the License. You can obtain a copy | |
84 | in the file LICENSE in the source distribution or at | |
85 | L<https://www.openssl.org/source/license.html>. | |
86 | ||
87 | =cut |