X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=FAQ;h=22c5cf7dc2f36cf7944e6ab5636b15f4b4f42047;hp=17dab12b3204e23757c860d7f2c02565e1ae5e49;hb=3984ef0b72831da8b3ece4745cac4f8575b19098;hpb=5789f8f780c21696c92e8138ad51afc53fa0d56d diff --git a/FAQ b/FAQ index 17dab12b32..22c5cf7dc2 100644 --- a/FAQ +++ b/FAQ @@ -1,370 +1,2 @@ -OpenSSL - Frequently Asked Questions --------------------------------------- - -* Which is the current version of OpenSSL? -* Where is the documentation? -* How can I contact the OpenSSL developers? -* Do I need patent licenses to use OpenSSL? -* Is OpenSSL thread-safe? -* 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? -* How do I create certificates or certificate requests? -* Why can't I create certificate requests? -* Why does fail with a certificate verify error? -* Why can I only use weak ciphers when I connect to a server using OpenSSL? -* 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 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? - - -* Which is the current version of OpenSSL? - -The current version is available from . -OpenSSL 0.9.5a was released on April 1st, 2000. - -In addition to the current stable release, you can also access daily -snapshots of the OpenSSL development version at , or get it by anonymous CVS access. - - -* Where is the documentation? - -OpenSSL is a library that provides cryptographic functionality to -applications such as secure web servers. Be sure to read the -documentation of the application you want to use. The INSTALL file -explains how to install this library. - -OpenSSL includes a command line utility that can be used to perform a -variety of cryptographic functions. It is described in the openssl(1) -manpage. Documentation for developers is currently being written. A -few manual pages already are available; overviews over libcrypto and -libssl are given in the crypto(3) and ssl(3) manpages. - -The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a -different directory if you specified one as described in INSTALL). -In addition, you can read the most current versions at -. - -For information on parts of libcrypto that are not yet documented, you -might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's -predecessor, at . Much -of this still applies to OpenSSL. - -There is some documentation about certificate extensions and PKCS#12 -in doc/openssl.txt - -The original SSLeay documentation is included in OpenSSL as -doc/ssleay.txt. It may be useful when none of the other resources -help, but please note that it reflects the obsolete version SSLeay -0.6.6. - - -* How can I contact the OpenSSL developers? - -The README file describes how to submit bug reports and patches to -OpenSSL. Information on the OpenSSL mailing lists is available from -. - - -* 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 - -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. - - -* 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. - - -* Why do I get a "PRNG not seeded" error message? - -Cryptographic software needs a source of unpredictable data to work -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. - -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 -number generator has not been seeded with at least 128 bits of -randomness. If this error occurs, please contact the author of the -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.] - -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". - -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. - - -* 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. - - -* 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 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 -can't find the installed OpenSSL libraries. The problem is actually -a small glitch that is easily solved with the following patch to be -applied to the OpenSSH distribution: - ------ snip:start ----- ---- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 -+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 -@@ -152,10 +152,10 @@ - AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) - for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do - if test ! -z "$ssldir" ; then -- LIBS="$saved_LIBS -L$ssldir" -+ LIBS="$saved_LIBS -L$ssldir/lib" - CFLAGS="$CFLAGS -I$ssldir/include" - if test "x$need_dash_r" = "x1" ; then -- LIBS="$LIBS -R$ssldir" -+ LIBS="$LIBS -R$ssldir/lib" - fi - fi - LIBS="$LIBS -lcrypto" ---- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 -+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 -@@ -1890,10 +1890,10 @@ - echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 - for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do - if test ! -z "$ssldir" ; then -- LIBS="$saved_LIBS -L$ssldir" -+ LIBS="$saved_LIBS -L$ssldir/lib" - CFLAGS="$CFLAGS -I$ssldir/include" - if test "x$need_dash_r" = "x1" ; then -- LIBS="$LIBS -R$ssldir" -+ LIBS="$LIBS -R$ssldir/lib" - fi - fi - LIBS="$LIBS -lcrypto" ------ snip:end ----- - - -* 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. - +The FAQ is now maintained on the web: + https://www.openssl.org/docs/faq.html