X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=FAQ;h=4b54b51ac8d2ed856fb62a09a023a3e9e348260d;hp=f64e4ffdddc89a153438d5a6fd74cad1af7ec043;hb=e9ad0d2c31997643e1a7bcacddf8d15a930b5cb8;hpb=b364e5d27bb23433f5cbe3543add1ccdc0681006 diff --git a/FAQ b/FAQ index f64e4ffddd..4b54b51ac8 100644 --- a/FAQ +++ b/FAQ @@ -1,18 +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? -* I've called 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 fail with a certificate verify error? @@ -20,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 and I get errors why? +* I've called 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 . -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 . +* 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 @@ -86,24 +134,26 @@ offer legal advice. You can configure OpenSSL so as not to use RC5 and IDEA by using ./config no-rc5 no-idea -Until the RSA patent expires, U.S. users may want to use - ./config no-rc5 no-idea no-rsa -Please note that you will *not* be able to communicate with most of -the popular web browsers without RSA support. +* Can I use OpenSSL with GPL software? +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). -* Is OpenSSL thread-safe? +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. -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. +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. -Multi-threaded applications must provide two callback functions to -OpenSSL. This is described in the threads(3) manpage. +[USER] ======================================================================== * Why do I get a "PRNG not seeded" error message? @@ -112,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 @@ -121,98 +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 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". +device, which may have some effects on OpenSSL. -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. - - -* 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 do I get an "unable to write 'random state'" error message? -* 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. - - -* I've called 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? @@ -277,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. + + +* 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. ------ 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 ----- + +[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"? @@ -326,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? @@ -386,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 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 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. + + +=============================================================================== +