FAQ revision 59191
159191SkrisOpenSSL - Frequently Asked Questions 259191Skris-------------------------------------- 359191Skris 459191Skris* Which is the current version of OpenSSL? 559191Skris* Where is the documentation? 659191Skris* How can I contact the OpenSSL developers? 759191Skris* Do I need patent licenses to use OpenSSL? 859191Skris* Is OpenSSL thread-safe? 959191Skris* Why do I get a "PRNG not seeded" error message? 1059191Skris* Why does the linker complain about undefined symbols? 1159191Skris* Where can I get a compiled version of OpenSSL? 1259191Skris* I've compiled a program under Windows and it crashes: why? 1359191Skris* I've called <some function> and it fails, why? 1459191Skris* I just get a load of numbers for the error output, what do they mean? 1559191Skris* Why do I get errors about unknown algorithms? 1659191Skris* How do I create certificates or certificate requests? 1759191Skris* Why can't I create certificate requests? 1859191Skris* Why does <SSL program> fail with a certificate verify error? 1959191Skris* How can I create DSA certificates? 2059191Skris* Why can't I make an SSL connection using a DSA certificate? 2159191Skris* Why can't the OpenSSH configure script detect OpenSSL? 2259191Skris 2359191Skris 2459191Skris* Which is the current version of OpenSSL? 2559191Skris 2659191SkrisThe current version is available from <URL: http://www.openssl.org>. 2759191SkrisOpenSSL 0.9.5a was released on April 1st, 2000. 2859191Skris 2959191SkrisIn addition to the current stable release, you can also access daily 3059191Skrissnapshots of the OpenSSL development version at <URL: 3159191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 3259191Skris 3359191Skris 3459191Skris* Where is the documentation? 3559191Skris 3659191SkrisOpenSSL is a library that provides cryptographic functionality to 3759191Skrisapplications such as secure web servers. Be sure to read the 3859191Skrisdocumentation of the application you want to use. The INSTALL file 3959191Skrisexplains how to install this library. 4059191Skris 4159191SkrisOpenSSL includes a command line utility that can be used to perform a 4259191Skrisvariety of cryptographic functions. It is described in the openssl(1) 4359191Skrismanpage. Documentation for developers is currently being written. A 4459191Skrisfew manual pages already are available; overviews over libcrypto and 4559191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 4659191Skris 4759191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 4859191Skrisdifferent directory if you specified one as described in INSTALL). 4959191SkrisIn addition, you can read the most current versions at 5059191Skris<URL: http://www.openssl.org/docs/>. 5159191Skris 5259191SkrisFor information on parts of libcrypto that are not yet documented, you 5359191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 5459191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 5559191Skrisof this still applies to OpenSSL. 5659191Skris 5759191SkrisThere is some documentation about certificate extensions and PKCS#12 5859191Skrisin doc/openssl.txt 5959191Skris 6059191SkrisThe original SSLeay documentation is included in OpenSSL as 6159191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 6259191Skrishelp, but please note that it reflects the obsolete version SSLeay 6359191Skris0.6.6. 6459191Skris 6559191Skris 6659191Skris* How can I contact the OpenSSL developers? 6759191Skris 6859191SkrisThe README file describes how to submit bug reports and patches to 6959191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 7059191Skris<URL: http://www.openssl.org>. 7159191Skris 7259191Skris 7359191Skris* Do I need patent licenses to use OpenSSL? 7459191Skris 7559191SkrisThe patents section of the README file lists patents that may apply to 7659191Skrisyou if you want to use OpenSSL. For information on intellectual 7759191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 7859191Skrisoffer legal advice. 7959191Skris 8059191SkrisYou can configure OpenSSL so as not to use RC5 and IDEA by using 8159191Skris ./config no-rc5 no-idea 8259191Skris 8359191SkrisUntil the RSA patent expires, U.S. users may want to use 8459191Skris ./config no-rc5 no-idea no-rsa 8559191Skris 8659191SkrisPlease note that you will *not* be able to communicate with most of 8759191Skristhe popular web browsers without RSA support. 8859191Skris 8959191Skris 9059191Skris* Is OpenSSL thread-safe? 9159191Skris 9259191SkrisYes (with limitations: an SSL connection may not concurrently be used 9359191Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 9459191Skrisautomatically uses the multi-threaded versions of the standard 9559191Skrislibraries. If your platform is not one of these, consult the INSTALL 9659191Skrisfile. 9759191Skris 9859191SkrisMulti-threaded applications must provide two callback functions to 9959191SkrisOpenSSL. This is described in the threads(3) manpage. 10059191Skris 10159191Skris 10259191Skris* Why do I get a "PRNG not seeded" error message? 10359191Skris 10459191SkrisCryptographic software needs a source of unpredictable data to work 10559191Skriscorrectly. Many open source operating systems provide a "randomness 10659191Skrisdevice" that serves this purpose. On other systems, applications have 10759191Skristo call the RAND_add() or RAND_seed() function with appropriate data 10859191Skrisbefore generating keys or performing public key encryption. 10959191Skris 11059191SkrisSome broken applications do not do this. As of version 0.9.5, the 11159191SkrisOpenSSL functions that need randomness report an error if the random 11259191Skrisnumber generator has not been seeded with at least 128 bits of 11359191Skrisrandomness. If this error occurs, please contact the author of the 11459191Skrisapplication you are using. It is likely that it never worked 11559191Skriscorrectly. OpenSSL 0.9.5 and later make the error visible by refusing 11659191Skristo perform potentially insecure encryption. 11759191Skris 11859191SkrisOn systems without /dev/urandom, it is a good idea to use the Entropy 11959191SkrisGathering Demon; see the RAND_egd() manpage for details. 12059191Skris 12159191SkrisMost components of the openssl command line tool try to use the 12259191Skrisfile $HOME/.rnd (or $RANDFILE, if this environment variable is set) 12359191Skrisfor seeding the PRNG. If this file does not exist or is too short, 12459191Skristhe "PRNG not seeded" error message may occur. 12559191Skris 12659191Skris[Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version 12759191Skris0.9.5 does not do this and will fail on systems without /dev/urandom 12859191Skriswhen trying to password-encrypt an RSA key! This is a bug in the 12959191Skrislibrary; try a later version instead.] 13059191Skris 13159191Skris 13259191Skris* Why does the linker complain about undefined symbols? 13359191Skris 13459191SkrisMaybe the compilation was interrupted, and make doesn't notice that 13559191Skrissomething is missing. Run "make clean; make". 13659191Skris 13759191SkrisIf you used ./Configure instead of ./config, make sure that you 13859191Skrisselected the right target. File formats may differ slightly between 13959191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 14059191Skris 14159191SkrisIn case you get errors about the following symbols, use the config 14259191Skrisoption "no-asm", as described in INSTALL: 14359191Skris 14459191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 14559191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 14659191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 14759191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 14859191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 14959191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 15059191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 15159191Skris 15259191SkrisIf none of these helps, you may want to try using the current snapshot. 15359191SkrisIf the problem persists, please submit a bug report. 15459191Skris 15559191Skris 15659191Skris* Where can I get a compiled version of OpenSSL? 15759191Skris 15859191SkrisSome applications that use OpenSSL are distributed in binary form. 15959191SkrisWhen using such an application, you don't need to install OpenSSL 16059191Skrisyourself; the application will include the required parts (e.g. DLLs). 16159191Skris 16259191SkrisIf you want to install OpenSSL on a Windows system and you don't have 16359191Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 16459191Skrison how to obtain and install the free GNU C compiler. 16559191Skris 16659191SkrisA number of Linux and *BSD distributions include OpenSSL. 16759191Skris 16859191Skris 16959191Skris* I've compiled a program under Windows and it crashes: why? 17059191Skris 17159191SkrisThis is usually because you've missed the comment in INSTALL.W32. You 17259191Skrismust link with the multithreaded DLL version of the VC++ runtime library 17359191Skrisotherwise the conflict will cause a program to crash: typically on the 17459191Skrisfirst BIO related read or write operation. 17559191Skris 17659191Skris 17759191Skris* I've called <some function> and it fails, why? 17859191Skris 17959191SkrisBefore submitting a report or asking in one of the mailing lists you 18059191Skrisshould try to determine the cause. In particular you should call 18159191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 18259191Skrisand see if the message helps. 18359191Skris 18459191Skris 18559191Skris* I just get a load of numbers for the error output, what do they mean? 18659191Skris 18759191SkrisThe actual format is described in the ERR_print_errors() manual page. 18859191SkrisYou should call the function ERR_load_crypto_strings() before hand and 18959191Skristhe message will be output in text form. If you can't do this (for example 19059191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 19159191Skriscode itself (the hex digits after the second colon). 19259191Skris 19359191Skris 19459191Skris* Why do I get errors about unknown algorithms? 19559191Skris 19659191SkrisThis can happen under several circumstances such as reading in an 19759191Skrisencrypted private key or attempting to decrypt a PKCS#12 file. The cause 19859191Skrisis forgetting to load OpenSSL's table of algorithms with 19959191SkrisOpenSSL_add_all_algorithms(). See the manual page for more information. 20059191Skris 20159191Skris 20259191Skris* How do I create certificates or certificate requests? 20359191Skris 20459191SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 20559191Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 20659191Skrisout the manual pages for the individual utilities and the certificate 20759191Skrisextensions documentation (currently in doc/openssl.txt). 20859191Skris 20959191Skris 21059191Skris* Why can't I create certificate requests? 21159191Skris 21259191SkrisYou typically get the error: 21359191Skris 21459191Skris unable to find 'distinguished_name' in config 21559191Skris problems making Certificate Request 21659191Skris 21759191SkrisThis is because it can't find the configuration file. Check out the 21859191SkrisDIAGNOSTICS section of req(1) for more information. 21959191Skris 22059191Skris 22159191Skris* Why does <SSL program> fail with a certificate verify error? 22259191Skris 22359191SkrisThis problem is usually indicated by log messages saying something like 22459191Skris"unable to get local issuer certificate" or "self signed certificate". 22559191SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 22659191Skristhis typically means that the CA certificate must be placed in a directory 22759191Skrisor file and the relevant program configured to read it. The OpenSSL program 22859191Skris'verify' behaves in a similar way and issues similar error messages: check 22959191Skristhe verify(1) program manual page for more information. 23059191Skris 23159191Skris 23259191Skris* How can I create DSA certificates? 23359191Skris 23459191SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 23559191Skris 23659191Skris 23759191Skris* Why can't I make an SSL connection to a server using a DSA certificate? 23859191Skris 23959191SkrisTypically you'll see a message saying there are no shared ciphers when 24059191Skristhe same setup works fine with an RSA certificate. There are two possible 24159191Skriscauses. The client may not support connections to DSA servers most web 24259191Skrisbrowsers only support connections to servers supporting RSA cipher suites. 24359191SkrisThe other cause is that a set of DH parameters has not been supplied to 24459191Skristhe server. DH parameters can be created with the dhparam(1) command and 24559191Skrisloaded using the SSL_CTX_set_tmp_dh() for example: check the source to 24659191Skriss_server in apps/s_server.c for an example. 24759191Skris 24859191Skris 24959191Skris* Why can't the OpenSSH configure script detect OpenSSL? 25059191Skris 25159191SkrisThere is a problem with OpenSSH 1.2.2p1, in that the configure script 25259191Skriscan't find the installed OpenSSL libraries. The problem is actually 25359191Skrisa small glitch that is easily solved with the following patch to be 25459191Skrisapplied to the OpenSSH distribution: 25559191Skris 25659191Skris----- snip:start ----- 25759191Skris--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 25859191Skris+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 25959191Skris@@ -152,10 +152,10 @@ 26059191Skris AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) 26159191Skris 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 26259191Skris if test ! -z "$ssldir" ; then 26359191Skris- LIBS="$saved_LIBS -L$ssldir" 26459191Skris+ LIBS="$saved_LIBS -L$ssldir/lib" 26559191Skris CFLAGS="$CFLAGS -I$ssldir/include" 26659191Skris if test "x$need_dash_r" = "x1" ; then 26759191Skris- LIBS="$LIBS -R$ssldir" 26859191Skris+ LIBS="$LIBS -R$ssldir/lib" 26959191Skris fi 27059191Skris fi 27159191Skris LIBS="$LIBS -lcrypto" 27259191Skris--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 27359191Skris+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 27459191Skris@@ -1890,10 +1890,10 @@ 27559191Skris echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 27659191Skris 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 27759191Skris if test ! -z "$ssldir" ; then 27859191Skris- LIBS="$saved_LIBS -L$ssldir" 27959191Skris+ LIBS="$saved_LIBS -L$ssldir/lib" 28059191Skris CFLAGS="$CFLAGS -I$ssldir/include" 28159191Skris if test "x$need_dash_r" = "x1" ; then 28259191Skris- LIBS="$LIBS -R$ssldir" 28359191Skris+ LIBS="$LIBS -R$ssldir/lib" 28459191Skris fi 28559191Skris fi 28659191Skris LIBS="$LIBS -lcrypto" 28759191Skris----- snip:end ----- 288