New format for the FAQ. We now have different sections for different

types of questions.  Hopefully, that'll make them easier to spot, and
specially, easier to refer to.

1 files changed, 224 insertions, 196 deletions

diff --git a/FAQ b/FAQ
index ecce985a44..b6fd981ce0 100644
--- a/FAQ
+++ b/FAQ
@@ -1,21 +1,21 @@
 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's SSL library with non-blocking I/O?
+
+[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?
 * 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?
@@ -23,14 +23,31 @@ 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?
+
+[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++?
-* Why aren't tools like 'autoconf' and 'libtool' used?
 
+[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?
+
+===============================================================================
+
+[MISC] ========================================================================
 
 * Which is the current version of OpenSSL?
 
@@ -81,42 +98,48 @@ OpenSSL.  Information on the OpenSSL mailing lists is available from
 <URL: http://www.openssl.org>.
 
 
-* Do I need patent licenses to use OpenSSL?
+* Where can I get a compiled version of OpenSSL?
 
-The patents section of the README file lists patents that may apply to
-you if you want to use OpenSSL.  For information on intellectual
-property rights, please consult a lawyer.  The OpenSSL team does not
-offer legal advice.
+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).
 
-You can configure OpenSSL so as not to use RC5 and IDEA by using
- ./config no-rc5 no-idea
+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.
 
-* 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.
+* Why aren't tools like 'autoconf' and 'libtool' used?
 
-Multi-threaded applications must provide two callback functions to
-OpenSSL.  This is described in the threads(3) manpage.
+autoconf is a nice tool, but is unfortunately very Unix-centric.
+Although one can come up with solution to have ports keep in track,
+there's also some work needed for that, and can be quite painful at
+times.  If there was a 'autoconf'-like tool that generated perl
+scripts or something similarly general, it would probably be used
+in OpenSSL 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.
 
-* Can I use OpenSSL's SSL library with non-blocking I/O?
 
-Yes; make sure to read the SSL_get_error(3) manual page!
+[LEGAL] =======================================================================
 
-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.
+* Do I need patent licenses to use OpenSSL?
 
+The patents section of the README file lists patents that may apply to
+you if you want to use OpenSSL.  For information on intellectual
+property rights, please consult a lawyer.  The OpenSSL team does not
+offer legal advice.
+
+You can configure OpenSSL so as not to use RC5 and IDEA by using
+ ./config no-rc5 no-idea
+
+
+[USER] ========================================================================
 
 * Why do I get a "PRNG not seeded" error message?
 
@@ -155,6 +178,70 @@ versions.  However, be warned that /dev/random is usually a blocking
 device, which may have some effects on OpenSSL.
 
 
+* How do I create certificates or certificate requests?
+
+Check out the CA.pl(1) manual page. This provides a simple wrapper round
+the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
+out the manual pages for the individual utilities and the certificate
+extensions documentation (currently in doc/openssl.txt).
+
+
+* Why can't I create certificate requests?
+
+You typically get the error:
+
+	unable to find 'distinguished_name' in config
+	problems making Certificate Request
+
+This is because it can't find the configuration file. Check out the
+DIAGNOSTICS section of req(1) for more information.
+
+
+* Why does <SSL program> fail with a certificate verify error?
+
+This problem is usually indicated by log messages saying something like
+"unable to get local issuer certificate" or "self signed certificate".
+When a certificate is verified its root CA must be "trusted" by OpenSSL
+this typically means that the CA certificate must be placed in a directory
+or file and the relevant program configured to read it. The OpenSSL program
+'verify' behaves in a similar way and issues similar error messages: check
+the verify(1) program manual page for more information.
+
+
+* Why can I only use weak ciphers when I connect to a server using OpenSSL?
+
+This is almost certainly because you are using an old "export grade" browser
+which only supports weak encryption. Upgrade your browser to support 128 bit
+ciphers.
+
+
+* How can I create DSA certificates?
+
+Check the CA.pl(1) manual page for a DSA certificate example.
+
+
+* Why can't I make an SSL connection to a server using a DSA certificate?
+
+Typically you'll see a message saying there are no shared ciphers when
+the same setup works fine with an RSA certificate. There are two possible
+causes. The client may not support connections to DSA servers most web
+browsers (including Netscape and MSIE) only support connections to servers
+supporting RSA cipher suites. The other cause is that a set of DH parameters
+has not been supplied to the server. DH parameters can be created with the
+dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example:
+check the source to s_server in apps/s_server.c for an example.
+
+
+* How can I remove the passphrase on a private key?
+
+Firstly you should be really *really* sure you want to do this. Leaving
+a private key unencrypted is a major security risk. If you decide that
+you do have to do this check the EXAMPLES sections of the rsa(1) and
+dsa(1) manual pages.
+
+
+[BUILD] =======================================================================
+
 * Why does the linker complain about undefined symbols?
 
 Maybe the compilation was interrupted, and make doesn't notice that
@@ -179,17 +266,98 @@ If none of these helps, you may want to try using the current snapshot.
 If the problem persists, please submit a bug report.
 
 
-* Where can I get a compiled version of OpenSSL?
+* Why does the OpenSSL test fail with "bc: command not found"?
 
-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).
+You didn't install "bc", the Unix calculator.  If you want to run the
+tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor.
 
-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 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.
+
+
+* Why does the OpenSSL compilation fail on Alpha True64 Unix?
+
+On some Alpha installations running True64 Unix and Compaq C, the compilation
+of crypto/sha/sha_dgst.c fails with the message 'Fatal:  Insufficient virtual
+memory to continue compilation.'  As far as the tests have shown, this may be
+a compiler bug.  What happens is that it eats up a lot of resident memory
+to build something, probably a table.  The problem is clearly in the
+optimization code, because if one eliminates optimization completely (-O0),
+the compilation goes through (and the compiler consumes about 2MB of resident
+memory instead of 240MB or whatever one's limit is currently).
+
+There are three options to solve this problem:
+
+1. set your current data segment size soft limit higher.  Experience shows
+that about 241000 kbytes seems to be enough on an AlphaServer DS10.  You do
+this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
+kbytes to set the limit to.
+
+2. If you have a hard limit that is lower than what you need and you can't
+get it changed, you can compile all of OpenSSL with -O0 as optimization
+level.  This is however not a very nice thing to do for those who expect to
+get the best result from OpenSSL.  A bit more complicated solution is the
+following:
+
+----- snip:start -----
+  make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
+       sed -e 's/ -O[0-9] / -O0 /'`"
+  rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'`
+  make
+----- snip:end -----
+
+This will only compile sha_dgst.c with -O0, the rest with the optimization
+level chosen by the configuration process.  When the above is done, do the
+test and installation and you're set.
+
+
+* Why does the OpenSSL compilation fail with "ar: command not found"?
+
+Getting this message is quite usual on Solaris 2, because Sun has hidden
+away 'ar' and other development commands in directories that aren't in
+$PATH by default.  One of those directories is '/usr/ccs/bin'.  The
+quickest way to fix this is to do the following (it assumes you use sh
+or any sh-compatible shell):
+
+----- snip:start -----
+  PATH=${PATH}:/usr/ccs/bin; export PATH
+----- snip:end -----
+
+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?
@@ -276,68 +444,6 @@ is forgetting to load OpenSSL's table of algorithms with
 OpenSSL_add_all_algorithms(). See the manual page for more information.
 
 
-* How do I create certificates or certificate requests?
-
-Check out the CA.pl(1) manual page. This provides a simple wrapper round
-the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
-out the manual pages for the individual utilities and the certificate
-extensions documentation (currently in doc/openssl.txt).
-
-
-* Why can't I create certificate requests?
-
-You typically get the error:
-
-	unable to find 'distinguished_name' in config
-	problems making Certificate Request
-
-This is because it can't find the configuration file. Check out the
-DIAGNOSTICS section of req(1) for more information.
-
-
-* Why does <SSL program> fail with a certificate verify error?
-
-This problem is usually indicated by log messages saying something like
-"unable to get local issuer certificate" or "self signed certificate".
-When a certificate is verified its root CA must be "trusted" by OpenSSL
-this typically means that the CA certificate must be placed in a directory
-or file and the relevant program configured to read it. The OpenSSL program
-'verify' behaves in a similar way and issues similar error messages: check
-the verify(1) program manual page for more information.
-
-
-* Why can I only use weak ciphers when I connect to a server using OpenSSL?
-
-This is almost certainly because you are using an old "export grade" browser
-which only supports weak encryption. Upgrade your browser to support 128 bit
-ciphers.
-
-
-* How can I create DSA certificates?
-
-Check the CA.pl(1) manual page for a DSA certificate example.
-
-
-* Why can't I make an SSL connection to a server using a DSA certificate?
-
-Typically you'll see a message saying there are no shared ciphers when
-the same setup works fine with an RSA certificate. There are two possible
-causes. The client may not support connections to DSA servers most web
-browsers (including Netscape and MSIE) only support connections to servers
-supporting RSA cipher suites. The other cause is that a set of DH parameters
-has not been supplied to the server. DH parameters can be created with the
-dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example:
-check the source to s_server in apps/s_server.c for an example.
-
-
-* How can I remove the passphrase on a private key?
-
-Firstly you should be really *really* sure you want to do this. Leaving
-a private key unencrypted is a major security risk. If you decide that
-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?
 
 There is a problem with OpenSSH 1.2.2p1, in that the configure script
@@ -379,97 +485,19 @@ applied to the OpenSSH distribution:
 ----- snip:end -----
 
 
-* Why does the OpenSSL test fail with "bc: command not found"?
-
-You didn't install "bc", the Unix calculator.  If you want to run the
-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.
-
-
-* Why does the OpenSSL compilation fail on Alpha True64 Unix?
-
-On some Alpha installations running True64 Unix and Compaq C, the compilation
-of crypto/sha/sha_dgst.c fails with the message 'Fatal:  Insufficient virtual
-memory to continue compilation.'  As far as the tests have shown, this may be
-a compiler bug.  What happens is that it eats up a lot of resident memory
-to build something, probably a table.  The problem is clearly in the
-optimization code, because if one eliminates optimization completely (-O0),
-the compilation goes through (and the compiler consumes about 2MB of resident
-memory instead of 240MB or whatever one's limit is currently).
-
-There are three options to solve this problem:
-
-1. set your current data segment size soft limit higher.  Experience shows
-that about 241000 kbytes seems to be enough on an AlphaServer DS10.  You do
-this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
-kbytes to set the limit to.
-
-2. If you have a hard limit that is lower than what you need and you can't
-get it changed, you can compile all of OpenSSL with -O0 as optimization
-level.  This is however not a very nice thing to do for those who expect to
-get the best result from OpenSSL.  A bit more complicated solution is the
-following:
-
------ snip:start -----
-  make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
-       sed -e 's/ -O[0-9] / -O0 /'`"
-  rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'`
-  make
------ snip:end -----
-
-This will only compile sha_dgst.c with -O0, the rest with the optimization
-level chosen by the configuration process.  When the above is done, do the
-test and installation and you're set.
-
-
-* Why does the OpenSSL compilation fail with "ar: command not found"?
-
-Getting this message is quite usual on Solaris 2, because Sun has hidden
-away 'ar' and other development commands in directories that aren't in
-$PATH by default.  One of those directories is '/usr/ccs/bin'.  The
-quickest way to fix this is to do the following (it assumes you use sh
-or any sh-compatible shell):
-
------ snip:start -----
-  PATH=${PATH}:/usr/ccs/bin; export PATH
------ snip:end -----
-
-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.
+* Can I use OpenSSL's SSL library with non-blocking I/O?
 
+Yes; make sure to read the SSL_get_error(3) manual page!
 
-* Why aren't tools like 'autoconf' and 'libtool' used?
+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.
 
-autoconf is a nice tool, but is unfortunately very Unix-centric.
-Although one can come up with solution to have ports keep in track,
-there's also some work needed for that, and can be quite painful at
-times.  If there was a 'autoconf'-like tool that generated perl
-scripts or something similarly general, it would probably be used
-in OpenSSL 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.
+===============================================================================