FAQ revision 68651
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? 1368651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 1468651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 1559191Skris* I've called <some function> and it fails, why? 1659191Skris* I just get a load of numbers for the error output, what do they mean? 1759191Skris* Why do I get errors about unknown algorithms? 1859191Skris* How do I create certificates or certificate requests? 1959191Skris* Why can't I create certificate requests? 2059191Skris* Why does <SSL program> fail with a certificate verify error? 2168651Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 2259191Skris* How can I create DSA certificates? 2359191Skris* Why can't I make an SSL connection using a DSA certificate? 2468651Skris* How can I remove the passphrase on a private key? 2559191Skris* Why can't the OpenSSH configure script detect OpenSSL? 2668651Skris* Why does the OpenSSL test fail with "bc: command not found"? 2768651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 2868651Skris* Why does the OpenSSL compilation fail on Alpha True64 Unix? 2968651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 3059191Skris 3159191Skris 3259191Skris* Which is the current version of OpenSSL? 3359191Skris 3459191SkrisThe current version is available from <URL: http://www.openssl.org>. 3568651SkrisOpenSSL 0.9.6 was released on September 24th, 2000. 3659191Skris 3759191SkrisIn addition to the current stable release, you can also access daily 3859191Skrissnapshots of the OpenSSL development version at <URL: 3959191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 4059191Skris 4159191Skris 4259191Skris* Where is the documentation? 4359191Skris 4459191SkrisOpenSSL is a library that provides cryptographic functionality to 4559191Skrisapplications such as secure web servers. Be sure to read the 4659191Skrisdocumentation of the application you want to use. The INSTALL file 4759191Skrisexplains how to install this library. 4859191Skris 4959191SkrisOpenSSL includes a command line utility that can be used to perform a 5059191Skrisvariety of cryptographic functions. It is described in the openssl(1) 5159191Skrismanpage. Documentation for developers is currently being written. A 5259191Skrisfew manual pages already are available; overviews over libcrypto and 5359191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 5459191Skris 5559191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 5659191Skrisdifferent directory if you specified one as described in INSTALL). 5759191SkrisIn addition, you can read the most current versions at 5859191Skris<URL: http://www.openssl.org/docs/>. 5959191Skris 6059191SkrisFor information on parts of libcrypto that are not yet documented, you 6159191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 6259191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 6359191Skrisof this still applies to OpenSSL. 6459191Skris 6559191SkrisThere is some documentation about certificate extensions and PKCS#12 6659191Skrisin doc/openssl.txt 6759191Skris 6859191SkrisThe original SSLeay documentation is included in OpenSSL as 6959191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 7059191Skrishelp, but please note that it reflects the obsolete version SSLeay 7159191Skris0.6.6. 7259191Skris 7359191Skris 7459191Skris* How can I contact the OpenSSL developers? 7559191Skris 7659191SkrisThe README file describes how to submit bug reports and patches to 7759191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 7859191Skris<URL: http://www.openssl.org>. 7959191Skris 8059191Skris 8159191Skris* Do I need patent licenses to use OpenSSL? 8259191Skris 8359191SkrisThe patents section of the README file lists patents that may apply to 8459191Skrisyou if you want to use OpenSSL. For information on intellectual 8559191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 8659191Skrisoffer legal advice. 8759191Skris 8859191SkrisYou can configure OpenSSL so as not to use RC5 and IDEA by using 8959191Skris ./config no-rc5 no-idea 9059191Skris 9159191Skris 9259191Skris* Is OpenSSL thread-safe? 9359191Skris 9459191SkrisYes (with limitations: an SSL connection may not concurrently be used 9559191Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 9659191Skrisautomatically uses the multi-threaded versions of the standard 9759191Skrislibraries. If your platform is not one of these, consult the INSTALL 9859191Skrisfile. 9959191Skris 10059191SkrisMulti-threaded applications must provide two callback functions to 10159191SkrisOpenSSL. This is described in the threads(3) manpage. 10259191Skris 10359191Skris 10459191Skris* Why do I get a "PRNG not seeded" error message? 10559191Skris 10659191SkrisCryptographic software needs a source of unpredictable data to work 10759191Skriscorrectly. Many open source operating systems provide a "randomness 10859191Skrisdevice" that serves this purpose. On other systems, applications have 10959191Skristo call the RAND_add() or RAND_seed() function with appropriate data 11059191Skrisbefore generating keys or performing public key encryption. 11159191Skris 11259191SkrisSome broken applications do not do this. As of version 0.9.5, the 11359191SkrisOpenSSL functions that need randomness report an error if the random 11459191Skrisnumber generator has not been seeded with at least 128 bits of 11559191Skrisrandomness. If this error occurs, please contact the author of the 11659191Skrisapplication you are using. It is likely that it never worked 11759191Skriscorrectly. OpenSSL 0.9.5 and later make the error visible by refusing 11859191Skristo perform potentially insecure encryption. 11959191Skris 12059191SkrisOn systems without /dev/urandom, it is a good idea to use the Entropy 12159191SkrisGathering Demon; see the RAND_egd() manpage for details. 12259191Skris 12359191SkrisMost components of the openssl command line tool try to use the 12459191Skrisfile $HOME/.rnd (or $RANDFILE, if this environment variable is set) 12559191Skrisfor seeding the PRNG. If this file does not exist or is too short, 12659191Skristhe "PRNG not seeded" error message may occur. 12759191Skris 12859191Skris[Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version 12959191Skris0.9.5 does not do this and will fail on systems without /dev/urandom 13059191Skriswhen trying to password-encrypt an RSA key! This is a bug in the 13159191Skrislibrary; try a later version instead.] 13259191Skris 13368651SkrisFor Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested 13468651Skrisinstalling the SUNski package from Sun patch 105710-01 (Sparc) which 13568651Skrisadds a /dev/random device and make sure it gets used, usually through 13668651Skris$RANDFILE. There are probably similar patches for the other Solaris 13768651Skrisversions. However, be warned that /dev/random is usually a blocking 13868651Skrisdevice, which may have some effects on OpenSSL. 13959191Skris 14068651Skris 14159191Skris* Why does the linker complain about undefined symbols? 14259191Skris 14359191SkrisMaybe the compilation was interrupted, and make doesn't notice that 14459191Skrissomething is missing. Run "make clean; make". 14559191Skris 14659191SkrisIf you used ./Configure instead of ./config, make sure that you 14759191Skrisselected the right target. File formats may differ slightly between 14859191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 14959191Skris 15059191SkrisIn case you get errors about the following symbols, use the config 15159191Skrisoption "no-asm", as described in INSTALL: 15259191Skris 15359191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 15459191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 15559191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 15659191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 15759191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 15859191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 15959191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 16059191Skris 16159191SkrisIf none of these helps, you may want to try using the current snapshot. 16259191SkrisIf the problem persists, please submit a bug report. 16359191Skris 16459191Skris 16559191Skris* Where can I get a compiled version of OpenSSL? 16659191Skris 16759191SkrisSome applications that use OpenSSL are distributed in binary form. 16859191SkrisWhen using such an application, you don't need to install OpenSSL 16959191Skrisyourself; the application will include the required parts (e.g. DLLs). 17059191Skris 17159191SkrisIf you want to install OpenSSL on a Windows system and you don't have 17259191Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 17359191Skrison how to obtain and install the free GNU C compiler. 17459191Skris 17559191SkrisA number of Linux and *BSD distributions include OpenSSL. 17659191Skris 17759191Skris 17859191Skris* I've compiled a program under Windows and it crashes: why? 17959191Skris 18059191SkrisThis is usually because you've missed the comment in INSTALL.W32. You 18159191Skrismust link with the multithreaded DLL version of the VC++ runtime library 18259191Skrisotherwise the conflict will cause a program to crash: typically on the 18359191Skrisfirst BIO related read or write operation. 18459191Skris 18559191Skris 18668651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 18768651Skris 18868651SkrisYou have two options. You can either use a memory BIO in conjunction 18968651Skriswith the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 19068651Skrisi2d_XXX(), d2i_XXX() functions directly. Since these are often the 19168651Skriscause of grief here are some code fragments using PKCS7 as an example: 19268651Skris 19368651Skrisunsigned char *buf, *p; 19468651Skrisint len; 19568651Skris 19668651Skrislen = i2d_PKCS7(p7, NULL); 19768651Skrisbuf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 19868651Skrisp = buf; 19968651Skrisi2d_PKCS7(p7, &p); 20068651Skris 20168651SkrisAt this point buf contains the len bytes of the DER encoding of 20268651Skrisp7. 20368651Skris 20468651SkrisThe opposite assumes we already have len bytes in buf: 20568651Skris 20668651Skrisunsigned char *p; 20768651Skrisp = buf; 20868651Skrisp7 = d2i_PKCS7(NULL, &p, len); 20968651Skris 21068651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 21168651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 21268651Skrisinformation. 21368651Skris 21468651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 21568651Skrisincrement the passed pointer so it is ready to read or write the next 21668651Skrisstructure. This is often a cause of problems: without the temporary 21768651Skrisvariable the buffer pointer is changed to point just after the data 21868651Skristhat has been read or written. This may well be uninitialized data 21968651Skrisand attempts to free the buffer will have unpredictable results 22068651Skrisbecause it no longer points to the same address. 22168651Skris 22268651Skris 22368651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 22468651Skris 22568651SkrisThis usually happens when you try compiling something using the PKCS#12 22668651Skrismacros with a C++ compiler. There is hardly ever any need to use the 22768651SkrisPKCS#12 macros in a program, it is much easier to parse and create 22868651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 22968651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 23068651Skris'pkcs12' application has to use the macros because it prints out 23168651Skrisdebugging information. 23268651Skris 23368651Skris 23459191Skris* I've called <some function> and it fails, why? 23559191Skris 23668651SkrisBefore submitting a report or asking in one of the mailing lists, you 23768651Skrisshould try to determine the cause. In particular, you should call 23859191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 23968651Skrisand see if the message helps. Note that the problem may occur earlier 24068651Skristhan you think -- you should check for errors after every call where 24168651Skrisit is possible, otherwise the actual problem may be hidden because 24268651Skrissome OpenSSL functions clear the error state. 24359191Skris 24459191Skris 24559191Skris* I just get a load of numbers for the error output, what do they mean? 24659191Skris 24759191SkrisThe actual format is described in the ERR_print_errors() manual page. 24859191SkrisYou should call the function ERR_load_crypto_strings() before hand and 24959191Skristhe message will be output in text form. If you can't do this (for example 25059191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 25159191Skriscode itself (the hex digits after the second colon). 25259191Skris 25359191Skris 25459191Skris* Why do I get errors about unknown algorithms? 25559191Skris 25659191SkrisThis can happen under several circumstances such as reading in an 25759191Skrisencrypted private key or attempting to decrypt a PKCS#12 file. The cause 25859191Skrisis forgetting to load OpenSSL's table of algorithms with 25959191SkrisOpenSSL_add_all_algorithms(). See the manual page for more information. 26059191Skris 26159191Skris 26259191Skris* How do I create certificates or certificate requests? 26359191Skris 26459191SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 26559191Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 26659191Skrisout the manual pages for the individual utilities and the certificate 26759191Skrisextensions documentation (currently in doc/openssl.txt). 26859191Skris 26959191Skris 27059191Skris* Why can't I create certificate requests? 27159191Skris 27259191SkrisYou typically get the error: 27359191Skris 27459191Skris unable to find 'distinguished_name' in config 27559191Skris problems making Certificate Request 27659191Skris 27759191SkrisThis is because it can't find the configuration file. Check out the 27859191SkrisDIAGNOSTICS section of req(1) for more information. 27959191Skris 28059191Skris 28159191Skris* Why does <SSL program> fail with a certificate verify error? 28259191Skris 28359191SkrisThis problem is usually indicated by log messages saying something like 28459191Skris"unable to get local issuer certificate" or "self signed certificate". 28559191SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 28659191Skristhis typically means that the CA certificate must be placed in a directory 28759191Skrisor file and the relevant program configured to read it. The OpenSSL program 28859191Skris'verify' behaves in a similar way and issues similar error messages: check 28959191Skristhe verify(1) program manual page for more information. 29059191Skris 29159191Skris 29268651Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 29368651Skris 29468651SkrisThis is almost certainly because you are using an old "export grade" browser 29568651Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 29668651Skrisciphers. 29768651Skris 29868651Skris 29959191Skris* How can I create DSA certificates? 30059191Skris 30159191SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 30259191Skris 30359191Skris 30459191Skris* Why can't I make an SSL connection to a server using a DSA certificate? 30559191Skris 30659191SkrisTypically you'll see a message saying there are no shared ciphers when 30759191Skristhe same setup works fine with an RSA certificate. There are two possible 30859191Skriscauses. The client may not support connections to DSA servers most web 30968651Skrisbrowsers (including Netscape and MSIE) only support connections to servers 31068651Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 31168651Skrishas not been supplied to the server. DH parameters can be created with the 31268651Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 31368651Skrischeck the source to s_server in apps/s_server.c for an example. 31459191Skris 31559191Skris 31668651Skris* How can I remove the passphrase on a private key? 31768651Skris 31868651SkrisFirstly you should be really *really* sure you want to do this. Leaving 31968651Skrisa private key unencrypted is a major security risk. If you decide that 32068651Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 32168651Skrisdsa(1) manual pages. 32268651Skris 32368651Skris 32459191Skris* Why can't the OpenSSH configure script detect OpenSSL? 32559191Skris 32659191SkrisThere is a problem with OpenSSH 1.2.2p1, in that the configure script 32759191Skriscan't find the installed OpenSSL libraries. The problem is actually 32859191Skrisa small glitch that is easily solved with the following patch to be 32959191Skrisapplied to the OpenSSH distribution: 33059191Skris 33159191Skris----- snip:start ----- 33259191Skris--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 33359191Skris+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 33459191Skris@@ -152,10 +152,10 @@ 33559191Skris AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) 33659191Skris 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 33759191Skris if test ! -z "$ssldir" ; then 33859191Skris- LIBS="$saved_LIBS -L$ssldir" 33959191Skris+ LIBS="$saved_LIBS -L$ssldir/lib" 34059191Skris CFLAGS="$CFLAGS -I$ssldir/include" 34159191Skris if test "x$need_dash_r" = "x1" ; then 34259191Skris- LIBS="$LIBS -R$ssldir" 34359191Skris+ LIBS="$LIBS -R$ssldir/lib" 34459191Skris fi 34559191Skris fi 34659191Skris LIBS="$LIBS -lcrypto" 34759191Skris--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 34859191Skris+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 34959191Skris@@ -1890,10 +1890,10 @@ 35059191Skris echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 35159191Skris 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 35259191Skris if test ! -z "$ssldir" ; then 35359191Skris- LIBS="$saved_LIBS -L$ssldir" 35459191Skris+ LIBS="$saved_LIBS -L$ssldir/lib" 35559191Skris CFLAGS="$CFLAGS -I$ssldir/include" 35659191Skris if test "x$need_dash_r" = "x1" ; then 35759191Skris- LIBS="$LIBS -R$ssldir" 35859191Skris+ LIBS="$LIBS -R$ssldir/lib" 35959191Skris fi 36059191Skris fi 36159191Skris LIBS="$LIBS -lcrypto" 36259191Skris----- snip:end ----- 36368651Skris 36468651Skris 36568651Skris* Why does the OpenSSL test fail with "bc: command not found"? 36668651Skris 36768651SkrisYou didn't install "bc", the Unix calculator. If you want to run the 36868651Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 36968651Skris 37068651Skris 37168651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 37268651Skris 37368651SkrisOn some SCO installations or versions, bc has a bug that gets triggered when 37468651Skrisyou run the test suite (using "make test"). The message returned is "bc: 37568651Skris1 not implemented". The best way to deal with this is to find another 37668651Skrisimplementation of bc and compile/install it. For example, GNU bc (see 37768651Skrishttp://www.gnu.org/software/software.html for download instructions) can 37868651Skrisbe safely used. 37968651Skris 38068651Skris 38168651Skris* Why does the OpenSSL compilation fail on Alpha True64 Unix? 38268651Skris 38368651SkrisOn some Alpha installations running True64 Unix and Compaq C, the compilation 38468651Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 38568651Skrismemory to continue compilation.' As far as the tests have shown, this may be 38668651Skrisa compiler bug. What happens is that it eats up a lot of resident memory 38768651Skristo build something, probably a table. The problem is clearly in the 38868651Skrisoptimization code, because if one eliminates optimization completely (-O0), 38968651Skristhe compilation goes through (and the compiler consumes about 2MB of resident 39068651Skrismemory instead of 240MB or whatever one's limit is currently). 39168651Skris 39268651SkrisThere are three options to solve this problem: 39368651Skris 39468651Skris1. set your current data segment size soft limit higher. Experience shows 39568651Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 39668651Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 39768651Skriskbytes to set the limit to. 39868651Skris 39968651Skris2. If you have a hard limit that is lower than what you need and you can't 40068651Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 40168651Skrislevel. This is however not a very nice thing to do for those who expect to 40268651Skrisget the best result from OpenSSL. A bit more complicated solution is the 40368651Skrisfollowing: 40468651Skris 40568651Skris----- snip:start ----- 40668651Skris make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 40768651Skris sed -e 's/ -O[0-9] / -O0 /'`" 40868651Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 40968651Skris make 41068651Skris----- snip:end ----- 41168651Skris 41268651SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 41368651Skrislevel chosen by the configuration process. When the above is done, do the 41468651Skristest and installation and you're set. 41568651Skris 41668651Skris 41768651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 41868651Skris 41968651SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 42068651Skrisaway 'ar' and other development commands in directories that aren't in 42168651Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 42268651Skrisquickest way to fix this is to do the following (it assumes you use sh 42368651Skrisor any sh-compatible shell): 42468651Skris 42568651Skris----- snip:start ----- 42668651Skris PATH=${PATH}:/usr/ccs/bin; export PATH 42768651Skris----- snip:end ----- 42868651Skris 42968651Skrisand then redo the compilation. What you should really do is make sure 43068651Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 43168651Skris'.profile' (again, assuming you use a sh-compatible shell). 43268651Skris 433