diff options
Diffstat (limited to 'crypto/openssl/FAQ')
| -rw-r--r-- | crypto/openssl/FAQ | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/crypto/openssl/FAQ b/crypto/openssl/FAQ new file mode 100644 index 0000000000000..7a27c147a475c --- /dev/null +++ b/crypto/openssl/FAQ @@ -0,0 +1,287 @@ +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 <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? +* How can I create DSA certificates? +* Why can't I make an SSL connection using a DSA certificate? +* Why can't the OpenSSH configure script detect OpenSSL? + + +* 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. + +In addition to the current stable release, you can also access daily +snapshots of the OpenSSL development version at <URL: +ftp://ftp.openssl.org/snapshot/>, 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 +<URL: http://www.openssl.org/docs/>. + +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 <URL: http://www.columbia.edu/~ariel/ssleay/>. 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 +<URL: http://www.openssl.org>. + + +* 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.] + + +* 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 <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. + + +* 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 <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. + + +* 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 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. + + +* 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 ----- |