Fix PRNG.
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index a381d1d..4b54b51 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -1,20 +1,23 @@
 OpenSSL  -  Frequently Asked Questions
 --------------------------------------
 
+[MISC] Miscellaneous questions
+
 * Which is the current version of OpenSSL?
 * Where is the documentation?
 * How can I contact the OpenSSL developers?
+* Where can I get a compiled version of OpenSSL?
+* Why aren't tools like 'autoconf' and 'libtool' used?
+
+[LEGAL] Legal questions
+
 * Do I need patent licenses to use OpenSSL?
-* Is OpenSSL thread-safe?
+* Can I use OpenSSL with GPL software? 
+
+[USER] Questions on using the OpenSSL applications
+
 * Why do I get a "PRNG not seeded" error message?
-* Why does the linker complain about undefined symbols?
-* Where can I get a compiled version of OpenSSL?
-* I've compiled a program under Windows and it crashes: why?
-* How do I read or write a DER encoded buffer using the ASN1 functions?
-* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
-* I've called <some function> and it fails, why?
-* I just get a load of numbers for the error output, what do they mean?
-* Why do I get errors about unknown algorithms?
+* 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?
@@ -22,17 +25,39 @@ OpenSSL  -  Frequently Asked Questions
 * How can I create DSA certificates?
 * Why can't I make an SSL connection using a DSA certificate?
 * How can I remove the passphrase on a private key?
-* Why can't the OpenSSH configure script detect OpenSSL?
+* Why can't I use OpenSSL certificates with SSL client authentication?
+* Why does my browser give a warning about a mismatched hostname?
+
+[BUILD] Questions about building and testing OpenSSL
+
+* Why does the linker complain about undefined symbols?
 * Why does the OpenSSL test fail with "bc: command not found"?
 * Why does the OpenSSL test fail with "bc: 1 no implemented"?
 * Why does the OpenSSL compilation fail on Alpha True64 Unix?
 * Why does the OpenSSL compilation fail with "ar: command not found"?
+* Why does the OpenSSL compilation fail on Win32 with VC++?
 
+[PROG] Questions about programming with OpenSSL
+
+* Is OpenSSL thread-safe?
+* I've compiled a program under Windows and it crashes: why?
+* How do I read or write a DER encoded buffer using the ASN1 functions?
+* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
+* I've called <some function> and it fails, why?
+* I just get a load of numbers for the error output, what do they mean?
+* 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?
+
+===============================================================================
+
+[MISC] ========================================================================
 
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 0.9.5a was released on April 1st, 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:
@@ -78,6 +103,27 @@ OpenSSL.  Information on the OpenSSL mailing lists is available from
 <URL: http://www.openssl.org>.
 
 
+* Where can I get a compiled version of OpenSSL?
+
+Some applications that use OpenSSL are distributed in binary form.
+When using such an application, you don't need to install OpenSSL
+yourself; the application will include the required parts (e.g. DLLs).
+
+If you want to install OpenSSL on a Windows system and you don't have
+a C compiler, read the "Mingw32" section of INSTALL.W32 for information
+on how to obtain and install the free GNU C compiler.
+
+A number of Linux and *BSD distributions include OpenSSL.
+
+
+* Why aren't tools like 'autoconf' and 'libtool' used?
+
+autoconf will probably be used in future OpenSSL versions. If it was
+less Unix-centric, it might have been used much earlier.
+
+
+[LEGAL] =======================================================================
+
 * Do I need patent licenses to use OpenSSL?
 
 The patents section of the README file lists patents that may apply to
@@ -89,18 +135,26 @@ You can configure OpenSSL so as not to use RC5 and IDEA by using
  ./config no-rc5 no-idea
 
 
-* Is OpenSSL thread-safe?
+* Can I use OpenSSL with GPL software?
 
-Yes (with limitations: an SSL connection may not concurrently be used
-by multiple threads).  On Windows and many Unix systems, OpenSSL
-automatically uses the multi-threaded versions of the standard
-libraries.  If your platform is not one of these, consult the INSTALL
-file.
+On many systems including the major Linux and BSD distributions, yes (the
+GPL does not place restrictions on using libraries that are part of the
+normal operating system distribution).
 
-Multi-threaded applications must provide two callback functions to
-OpenSSL.  This is described in the threads(3) manpage.
+On other systems, the situation is less clear. Some GPL software copyright
+holders claim that you infringe on their rights if you use OpenSSL with
+their software on operating systems that don't normally include OpenSSL.
+
+If you develop open source software that uses OpenSSL, you may find it
+useful to choose an other license than the GPL, or state explicitely that
+"This program is released under the GPL with the additional exemption that
+compiling, linking, and/or using OpenSSL is allowed."  If you are using
+GPL software developed by others, you may want to ask the copyright holder
+for permission to use their software with OpenSSL.
 
 
+[USER] ========================================================================
+
 * Why do I get a "PRNG not seeded" error message?
 
 Cryptographic software needs a source of unpredictable data to work
@@ -108,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
@@ -117,146 +172,55 @@ 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
 adds a /dev/random device and make sure it gets used, usually through
 $RANDFILE.  There are probably similar patches for the other Solaris
 versions.  However, be warned that /dev/random is usually a blocking
-device, which may have som effects on OpenSSL.
-
-
-* Why does the linker complain about undefined symbols?
-
-Maybe the compilation was interrupted, and make doesn't notice that
-something is missing.  Run "make clean; make".
-
-If you used ./Configure instead of ./config, make sure that you
-selected the right target.  File formats may differ slightly between
-OS versions (for example sparcv8/sparcv9, or a.out/elf).
-
-In case you get errors about the following symbols, use the config
-option "no-asm", as described in INSTALL:
-
- BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt,
- CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt,
- RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words,
- bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4,
- bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3,
- des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3,
- des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order
-
-If none of these helps, you may want to try using the current snapshot.
-If the problem persists, please submit a bug report.
+device, which may have some effects on OpenSSL.
 
 
-* Where can I get a compiled version of OpenSSL?
+* Why do I get an "unable to write 'random state'" error message?
 
-Some applications that use OpenSSL are distributed in binary form.
-When using such an application, you don't need to install OpenSSL
-yourself; the application will include the required parts (e.g. DLLs).
 
-If you want to install OpenSSL on a Windows system and you don't have
-a C compiler, read the "Mingw32" section of INSTALL.W32 for information
-on how to obtain and install the free GNU C compiler.
-
-A number of Linux and *BSD distributions include OpenSSL.
-
-
-* I've compiled a program under Windows and it crashes: why?
-
-This is usually because you've missed the comment in INSTALL.W32. You
-must link with the multithreaded DLL version of the VC++ runtime library
-otherwise the conflict will cause a program to crash: typically on the
-first BIO related read or write operation.
-
-
-* How do I read or write a DER encoded buffer using the ASN1 functions?
-
-You have two options. You can either use a memory BIO in conjunction
-with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the
-i2d_XXX(), d2i_XXX() functions directly. Since these are often the
-cause of grief here are some code fragments using PKCS7 as an example:
-
-unsigned char *buf, *p;
-int len;
-
-len = i2d_PKCS7(p7, NULL);
-buf = OPENSSL_Malloc(len); /* or Malloc, error checking omitted */
-p = buf;
-i2d_PKCS7(p7, &p);
-
-At this point buf contains the len bytes of the DER encoding of
-p7.
-
-The opposite assumes we already have len bytes in buf:
-
-unsigned char *p;
-p = buf;
-p7 = d2i_PKCS7(NULL, &p, len);
-
-At this point p7 contains a valid PKCS7 structure of NULL if an error
-occurred. If an error occurred ERR_print_errors(bio) should give more
-information.
-
-The reason for the temporary variable 'p' is that the ASN1 functions
-increment the passed pointer so it is ready to read or write the next
-structure. This is often a cause of problems: without the temporary
-variable the buffer pointer is changed to point just after the data
-that has been read or written. This may well be uninitialized data
-and attempts to free the buffer will have unpredictable results
-because it no longer points to the same address.
-
-
-* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
-
-This usually happens when you try compiling something using the PKCS#12
-macros with a C++ compiler. There is hardly ever any need to use the
-PKCS#12 macros in a program, it is much easier to parse and create
-PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions
-documented in doc/openssl.txt and with examples in demos/pkcs12. The
-'pkcs12' application has to use the macros because it prints out 
-debugging information.
-
-
-* I've called <some function> and it fails, why?
-
-Before submitting a report or asking in one of the mailing lists, you
-should try to determine the cause. In particular, you should call
-ERR_print_errors() or ERR_print_errors_fp() after the failed call
-and see if the message helps. Note that the problem may occur earlier
-than you think -- you should check for errors after every call where
-it is possible, otherwise the actual problem may be hidden because
-some OpenSSL functions clear the error state.
-
-
-* I just get a load of numbers for the error output, what do they mean?
-
-The actual format is described in the ERR_print_errors() manual page.
-You should call the function ERR_load_crypto_strings() before hand and
-the message will be output in text form. If you can't do this (for example
-it is a pre-compiled binary) you can use the errstr utility on the error
-code itself (the hex digits after the second colon).
-
-
-* Why do I get errors about unknown algorithms?
-
-This can happen under several circumstances such as reading in an
-encrypted private key or attempting to decrypt a PKCS#12 file. The cause
-is forgetting to load OpenSSL's table of algorithms with
-OpenSSL_add_all_algorithms(). See the manual page for more information.
+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?
@@ -321,45 +285,61 @@ you do have to do this check the EXAMPLES sections of the rsa(1) and
 dsa(1) manual pages.
 
 
-* Why can't the OpenSSH configure script detect OpenSSL?
+* Why can't I use OpenSSL certificates with SSL client authentication?
 
-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:
+What will typically happen is that when a server requests authentication
+it will either not include your certificate or tell you that you have
+no client certificates (Netscape) or present you with an empty list box
+(MSIE). The reason for this is that when a server requests a client
+certificate it includes a list of CAs names which it will accept. Browsers
+will only let you select certificates from the list on the grounds that
+there is little point presenting a certificate which the server will
+reject.
+
+The solution is to add the relevant CA certificate to your servers "trusted
+CA list". How you do this depends on the server sofware in uses. You can
+print out the servers list of acceptable CAs using the OpenSSL s_client tool:
+
+openssl s_client -connect www.some.host:443 -prexit
+
+If your server only requests certificates on certain URLs then you may need
+to manually issue an HTTP GET command to get the list when s_client connects:
+
+GET /some/page/needing/a/certificate.html
+
+If your CA does not appear in the list then this confirms the problem.
 
------ 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 -----
+
+* Why does my browser give a warning about a mismatched hostname?
+
+Browsers expect the server's hostname to match the value in the commonName
+(CN) field of the certificate. If it does not then you get a warning.
+
+
+[BUILD] =======================================================================
+
+* Why does the linker complain about undefined symbols?
+
+Maybe the compilation was interrupted, and make doesn't notice that
+something is missing.  Run "make clean; make".
+
+If you used ./Configure instead of ./config, make sure that you
+selected the right target.  File formats may differ slightly between
+OS versions (for example sparcv8/sparcv9, or a.out/elf).
+
+In case you get errors about the following symbols, use the config
+option "no-asm", as described in INSTALL:
+
+ BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt,
+ CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt,
+ RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words,
+ bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4,
+ bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3,
+ des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3,
+ des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order
+
+If none of these helps, you may want to try using the current snapshot.
+If the problem persists, please submit a bug report.
 
 
 * Why does the OpenSSL test fail with "bc: command not found"?
@@ -370,12 +350,13 @@ tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor.
 
 * Why does the OpenSSL test fail with "bc: 1 no implemented"?
 
-On some SCO installations or versions, bc has a bug that gets triggered when
-you run the test suite (using "make test").  The message returned is "bc:
-1 not implemented".  The best way to deal with this is to find another
-implementation of bc and compile/install it.  For example, GNU bc (see
-http://www.gnu.org/software/software.html for download instructions) can
-be safely used.
+On some SCO installations or versions, bc has a bug that gets triggered
+when you run the test suite (using "make test").  The message returned is
+"bc: 1 not implemented".
+
+The best way to deal with this is to find another implementation of bc
+and compile/install it.  GNU bc (see http://www.gnu.org/software/software.html
+for download instructions) can be safely used, for example.
 
 
 * Why does the OpenSSL compilation fail on Alpha True64 Unix?
@@ -430,3 +411,149 @@ and then redo the compilation.  What you should really do is make sure
 '/usr/ccs/bin' is permanently in your $PATH, for example through your
 '.profile' (again, assuming you use a sh-compatible shell).
 
+
+* Why does the OpenSSL compilation fail on Win32 with VC++?
+
+Sometimes, you may get reports from VC++ command line (cl) that it
+can't find standard include files like stdio.h and other weirdnesses.
+One possible cause is that the environment isn't correctly set up.
+To solve that problem, one should run VCVARS32.BAT which is found in
+the 'bin' subdirectory of the VC++ installation directory (somewhere
+under 'Program Files').  This needs to be done prior to running NMAKE,
+and the changes are only valid for the current DOS session.
+
+
+[PROG] ========================================================================
+
+* Is OpenSSL thread-safe?
+
+Yes (with limitations: an SSL connection may not concurrently be used
+by multiple threads).  On Windows and many Unix systems, OpenSSL
+automatically uses the multi-threaded versions of the standard
+libraries.  If your platform is not one of these, consult the INSTALL
+file.
+
+Multi-threaded applications must provide two callback functions to
+OpenSSL.  This is described in the threads(3) manpage.
+
+
+* I've compiled a program under Windows and it crashes: why?
+
+This is usually because you've missed the comment in INSTALL.W32. You
+must link with the multithreaded DLL version of the VC++ runtime library
+otherwise the conflict will cause a program to crash: typically on the
+first BIO related read or write operation.
+
+
+* How do I read or write a DER encoded buffer using the ASN1 functions?
+
+You have two options. You can either use a memory BIO in conjunction
+with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the
+i2d_XXX(), d2i_XXX() functions directly. Since these are often the
+cause of grief here are some code fragments using PKCS7 as an example:
+
+unsigned char *buf, *p;
+int len;
+
+len = i2d_PKCS7(p7, NULL);
+buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
+p = buf;
+i2d_PKCS7(p7, &p);
+
+At this point buf contains the len bytes of the DER encoding of
+p7.
+
+The opposite assumes we already have len bytes in buf:
+
+unsigned char *p;
+p = buf;
+p7 = d2i_PKCS7(NULL, &p, len);
+
+At this point p7 contains a valid PKCS7 structure of NULL if an error
+occurred. If an error occurred ERR_print_errors(bio) should give more
+information.
+
+The reason for the temporary variable 'p' is that the ASN1 functions
+increment the passed pointer so it is ready to read or write the next
+structure. This is often a cause of problems: without the temporary
+variable the buffer pointer is changed to point just after the data
+that has been read or written. This may well be uninitialized data
+and attempts to free the buffer will have unpredictable results
+because it no longer points to the same address.
+
+
+* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
+
+This usually happens when you try compiling something using the PKCS#12
+macros with a C++ compiler. There is hardly ever any need to use the
+PKCS#12 macros in a program, it is much easier to parse and create
+PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions
+documented in doc/openssl.txt and with examples in demos/pkcs12. The
+'pkcs12' application has to use the macros because it prints out 
+debugging information.
+
+
+* I've called <some function> and it fails, why?
+
+Before submitting a report or asking in one of the mailing lists, you
+should try to determine the cause. In particular, you should call
+ERR_print_errors() or ERR_print_errors_fp() after the failed call
+and see if the message helps. Note that the problem may occur earlier
+than you think -- you should check for errors after every call where
+it is possible, otherwise the actual problem may be hidden because
+some OpenSSL functions clear the error state.
+
+
+* I just get a load of numbers for the error output, what do they mean?
+
+The actual format is described in the ERR_print_errors() manual page.
+You should call the function ERR_load_crypto_strings() before hand and
+the message will be output in text form. If you can't do this (for example
+it is a pre-compiled binary) you can use the errstr utility on the error
+code itself (the hex digits after the second colon).
+
+
+* Why do I get errors about unknown algorithms?
+
+This can happen under several circumstances such as reading in an
+encrypted private key or attempting to decrypt a PKCS#12 file. The cause
+is forgetting to load OpenSSL's table of algorithms with
+OpenSSL_add_all_algorithms(). See the manual page for more information.
+
+
+* Why can't the OpenSSH configure script detect OpenSSL?
+
+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?
+
+Yes; make sure to read the SSL_get_error(3) manual page!
+
+A pitfall to avoid: Don't assume that SSL_read() will just read from
+the underlying transport or that SSL_write() will just write to it --
+it is also possible that SSL_write() cannot do any useful work until
+there is data to read, or that SSL_read() cannot do anything until it
+is possible to send data.  One reason for this is that the peer may
+request a new TLS/SSL handshake at any time during the protocol,
+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.
+
+
+===============================================================================
+