diff options
-rw-r--r-- | CHANGES | 4 | ||||
-rw-r--r-- | FAQ | 420 |
2 files changed, 228 insertions, 196 deletions
@@ -3,6 +3,10 @@ Changes between 0.9.6 and 0.9.7 [xx XXX 2000] + *) Reformat the FAQ so the different questions and answers can be divided + i sections depending on the subject. + [Richard Levitte] + *) Have the zlib compression code load ZLIB.DLL dynamically under Windows. [Richard Levitte] @@ -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. +=============================================================================== |