Fix PRNG.
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index 5f41736..4b54b51 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -17,6 +17,7 @@ OpenSSL  -  Frequently Asked Questions
 [USER] Questions on using the OpenSSL applications
 
 * Why do I get a "PRNG not seeded" error message?
+* Why do I get an "unable to write 'random state'" error message?
 * How do I create certificates or certificate requests?
 * Why can't I create certificate requests?
 * Why does <SSL program> fail with a certificate verify error?
@@ -47,6 +48,7 @@ OpenSSL  -  Frequently Asked Questions
 * Why do I get errors about unknown algorithms?
 * Why can't the OpenSSH configure script detect OpenSSL?
 * Can I use OpenSSL's SSL library with non-blocking I/O?
+* Why doesn't my server application receive a client certificate?
 
 ===============================================================================
 
@@ -55,7 +57,7 @@ OpenSSL  -  Frequently Asked Questions
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 0.9.6 was released on September 24th, 2000.
+OpenSSL 0.9.6b was released on July 9th, 2001.
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
@@ -119,11 +121,6 @@ A number of Linux and *BSD distributions include OpenSSL.
 autoconf will probably be used in future OpenSSL versions. If it was
 less Unix-centric, it might have been used much earlier.
 
-libtool has repeatadly been reported by some members of the OpenSSL
-development and others to be a pain to use.  So far, those in the
-development team who have said anything about this have expressed
-a wish to avoid libtool for that reason.
-
 
 [LEGAL] =======================================================================
 
@@ -165,6 +162,7 @@ correctly.  Many open source operating systems provide a "randomness
 device" that serves this purpose.  On other systems, applications have
 to call the RAND_add() or RAND_seed() function with appropriate data
 before generating keys or performing public key encryption.
+(These functions initialize the pseudo-random number generator, PRNG.)
 
 Some broken applications do not do this.  As of version 0.9.5, the
 OpenSSL functions that need randomness report an error if the random
@@ -174,18 +172,36 @@ application you are using.  It is likely that it never worked
 correctly.  OpenSSL 0.9.5 and later make the error visible by refusing
 to perform potentially insecure encryption.
 
-On systems without /dev/urandom, it is a good idea to use the Entropy
-Gathering Demon; see the RAND_egd() manpage for details.
-
-Most components of the openssl command line tool try to use the
-file $HOME/.rnd (or $RANDFILE, if this environment variable is set)
-for seeding the PRNG.  If this file does not exist or is too short,
-the "PRNG not seeded" error message may occur.
-
-[Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version
-0.9.5 does not do this and will fail on systems without /dev/urandom
-when trying to password-encrypt an RSA key!  This is a bug in the
-library; try a later version instead.]
+On systems without /dev/urandom and /dev/random, it is a good idea to
+use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for
+details.  Starting with version 0.9.7, OpenSSL will automatically look
+for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and
+/etc/entropy.
+
+Most components of the openssl command line utility automatically try
+to seed the random number generator from a file.  The name of the
+default seeding file is determined as follows: If environment variable
+RANDFILE is set, then it names the seeding file.  Otherwise if
+environment variable HOME is set, then the seeding file is $HOME/.rnd.
+If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will
+use file .rnd in the current directory while OpenSSL 0.9.6a uses no
+default seeding file at all.  OpenSSL 0.9.6b and later will behave
+similarly to 0.9.6a, but will use a default of "C:\" for HOME on
+Windows systems if the environment variable has not been set.
+
+If the default seeding file does not exist or is too short, the "PRNG
+not seeded" error message may occur.
+
+The openssl command line utility will write back a new state to the
+default seeding file (and create this file if necessary) unless
+there was no sufficient seeding.
+
+Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work.
+Use the "-rand" option of the OpenSSL command line tools instead.
+The $RANDFILE environment variable and $HOME/.rnd are only used by the
+OpenSSL command line tools. Applications using the OpenSSL library
+provide their own configuration options to specify the entropy source,
+please check out the documentation coming the with application.
 
 For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested
 installing the SUNski package from Sun patch 105710-01 (Sparc) which
@@ -195,6 +211,18 @@ versions.  However, be warned that /dev/random is usually a blocking
 device, which may have some effects on OpenSSL.
 
 
+* Why do I get an "unable to write 'random state'" error message?
+
+
+Sometimes the openssl command line utility does not abort with
+a "PRNG not seeded" error message, but complains that it is
+"unable to write 'random state'".  This message refers to the
+default seeding file (see previous answer).  A possible reason
+is that no default filename is known because neither RANDFILE
+nor HOME is set.  (Versions up to 0.9.6 used file ".rnd" in the
+current directory in this case, but this has changed with 0.9.6a.)
+
+
 * How do I create certificates or certificate requests?
 
 Check out the CA.pl(1) manual page. This provides a simple wrapper round
@@ -495,44 +523,16 @@ OpenSSL_add_all_algorithms(). See the manual page for more information.
 
 * Why can't the OpenSSH configure script detect OpenSSL?
 
-There is a problem with OpenSSH 1.2.2p1, in that the configure script
-can't find the installed OpenSSL libraries.  The problem is actually
-a small glitch that is easily solved with the following patch to be
-applied to the OpenSSH distribution:
-
------ snip:start -----
---- openssh-1.2.2p1/configure.in.orig  Thu Mar 23 18:56:58 2000
-+++ openssh-1.2.2p1/configure.in       Thu Mar 23 18:55:05 2000
-@@ -152,10 +152,10 @@
- AC_MSG_CHECKING([for OpenSSL/SSLeay directory])
- for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do
-       if test ! -z "$ssldir" ; then
--              LIBS="$saved_LIBS -L$ssldir"
-+              LIBS="$saved_LIBS -L$ssldir/lib"
-               CFLAGS="$CFLAGS -I$ssldir/include"
-               if test "x$need_dash_r" = "x1" ; then
--                      LIBS="$LIBS -R$ssldir"
-+                      LIBS="$LIBS -R$ssldir/lib"
-               fi
-       fi
-       LIBS="$LIBS -lcrypto"
---- openssh-1.2.2p1/configure.orig     Thu Mar 23 18:55:02 2000
-+++ openssh-1.2.2p1/configure  Thu Mar 23 18:57:08 2000
-@@ -1890,10 +1890,10 @@
- echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5
- for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do
-       if test ! -z "$ssldir" ; then
--              LIBS="$saved_LIBS -L$ssldir"
-+              LIBS="$saved_LIBS -L$ssldir/lib"
-               CFLAGS="$CFLAGS -I$ssldir/include"
-               if test "x$need_dash_r" = "x1" ; then
--                      LIBS="$LIBS -R$ssldir"
-+                      LIBS="$LIBS -R$ssldir/lib"
-               fi
-       fi
-       LIBS="$LIBS -lcrypto"
------ snip:end -----
+Several reasons for problems with the automatic detection exist.
+OpenSSH requires at least version 0.9.5a of the OpenSSL libraries.
+Sometimes the distribution has installed an older version in the system
+locations that is detected instead of a new one installed. The OpenSSL
+library might have been compiled for another CPU or another mode (32/64 bits).
+Permissions might be wrong.
 
+The general answer is to check the config.log file generated when running
+the OpenSSH configure script. It should contain the detailed information
+on why the OpenSSL library was not detected or considered incompatible.
 
 * Can I use OpenSSL's SSL library with non-blocking I/O?
 
@@ -548,5 +548,12 @@ requiring a bi-directional message exchange; both SSL_read() and
 SSL_write() will try to continue any pending handshake.
 
 
+* Why doesn't my server application receive a client certificate?
+
+Due to the TLS protocol definition, a client will only send a certificate,
+if explicitely asked by the server. Use the SSL_VERIFY_PEER flag of the
+SSL_CTX_set_verify() function to enable the use of client certificates.
+
+
 ===============================================================================