FAQ revision 68651
1OpenSSL - Frequently Asked Questions 2-------------------------------------- 3 4* Which is the current version of OpenSSL? 5* Where is the documentation? 6* How can I contact the OpenSSL developers? 7* Do I need patent licenses to use OpenSSL? 8* Is OpenSSL thread-safe? 9* Why do I get a "PRNG not seeded" error message? 10* Why does the linker complain about undefined symbols? 11* Where can I get a compiled version of OpenSSL? 12* I've compiled a program under Windows and it crashes: why? 13* How do I read or write a DER encoded buffer using the ASN1 functions? 14* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 15* I've called <some function> and it fails, why? 16* I just get a load of numbers for the error output, what do they mean? 17* Why do I get errors about unknown algorithms? 18* How do I create certificates or certificate requests? 19* Why can't I create certificate requests? 20* Why does <SSL program> fail with a certificate verify error? 21* Why can I only use weak ciphers when I connect to a server using OpenSSL? 22* How can I create DSA certificates? 23* Why can't I make an SSL connection using a DSA certificate? 24* How can I remove the passphrase on a private key? 25* Why can't the OpenSSH configure script detect OpenSSL? 26* Why does the OpenSSL test fail with "bc: command not found"? 27* Why does the OpenSSL test fail with "bc: 1 no implemented"? 28* Why does the OpenSSL compilation fail on Alpha True64 Unix? 29* Why does the OpenSSL compilation fail with "ar: command not found"? 30 31 32* Which is the current version of OpenSSL? 33 34The current version is available from <URL: http://www.openssl.org>. 35OpenSSL 0.9.6 was released on September 24th, 2000. 36 37In addition to the current stable release, you can also access daily 38snapshots of the OpenSSL development version at <URL: 39ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 40 41 42* Where is the documentation? 43 44OpenSSL is a library that provides cryptographic functionality to 45applications such as secure web servers. Be sure to read the 46documentation of the application you want to use. The INSTALL file 47explains how to install this library. 48 49OpenSSL includes a command line utility that can be used to perform a 50variety of cryptographic functions. It is described in the openssl(1) 51manpage. Documentation for developers is currently being written. A 52few manual pages already are available; overviews over libcrypto and 53libssl are given in the crypto(3) and ssl(3) manpages. 54 55The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 56different directory if you specified one as described in INSTALL). 57In addition, you can read the most current versions at 58<URL: http://www.openssl.org/docs/>. 59 60For information on parts of libcrypto that are not yet documented, you 61might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 62predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 63of this still applies to OpenSSL. 64 65There is some documentation about certificate extensions and PKCS#12 66in doc/openssl.txt 67 68The original SSLeay documentation is included in OpenSSL as 69doc/ssleay.txt. It may be useful when none of the other resources 70help, but please note that it reflects the obsolete version SSLeay 710.6.6. 72 73 74* How can I contact the OpenSSL developers? 75 76The README file describes how to submit bug reports and patches to 77OpenSSL. Information on the OpenSSL mailing lists is available from 78<URL: http://www.openssl.org>. 79 80 81* Do I need patent licenses to use OpenSSL? 82 83The patents section of the README file lists patents that may apply to 84you if you want to use OpenSSL. For information on intellectual 85property rights, please consult a lawyer. The OpenSSL team does not 86offer legal advice. 87 88You can configure OpenSSL so as not to use RC5 and IDEA by using 89 ./config no-rc5 no-idea 90 91 92* Is OpenSSL thread-safe? 93 94Yes (with limitations: an SSL connection may not concurrently be used 95by multiple threads). On Windows and many Unix systems, OpenSSL 96automatically uses the multi-threaded versions of the standard 97libraries. If your platform is not one of these, consult the INSTALL 98file. 99 100Multi-threaded applications must provide two callback functions to 101OpenSSL. This is described in the threads(3) manpage. 102 103 104* Why do I get a "PRNG not seeded" error message? 105 106Cryptographic software needs a source of unpredictable data to work 107correctly. Many open source operating systems provide a "randomness 108device" that serves this purpose. On other systems, applications have 109to call the RAND_add() or RAND_seed() function with appropriate data 110before generating keys or performing public key encryption. 111 112Some broken applications do not do this. As of version 0.9.5, the 113OpenSSL functions that need randomness report an error if the random 114number generator has not been seeded with at least 128 bits of 115randomness. If this error occurs, please contact the author of the 116application you are using. It is likely that it never worked 117correctly. OpenSSL 0.9.5 and later make the error visible by refusing 118to perform potentially insecure encryption. 119 120On systems without /dev/urandom, it is a good idea to use the Entropy 121Gathering Demon; see the RAND_egd() manpage for details. 122 123Most components of the openssl command line tool try to use the 124file $HOME/.rnd (or $RANDFILE, if this environment variable is set) 125for seeding the PRNG. If this file does not exist or is too short, 126the "PRNG not seeded" error message may occur. 127 128[Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version 1290.9.5 does not do this and will fail on systems without /dev/urandom 130when trying to password-encrypt an RSA key! This is a bug in the 131library; try a later version instead.] 132 133For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested 134installing the SUNski package from Sun patch 105710-01 (Sparc) which 135adds a /dev/random device and make sure it gets used, usually through 136$RANDFILE. There are probably similar patches for the other Solaris 137versions. However, be warned that /dev/random is usually a blocking 138device, which may have some effects on OpenSSL. 139 140 141* Why does the linker complain about undefined symbols? 142 143Maybe the compilation was interrupted, and make doesn't notice that 144something is missing. Run "make clean; make". 145 146If you used ./Configure instead of ./config, make sure that you 147selected the right target. File formats may differ slightly between 148OS versions (for example sparcv8/sparcv9, or a.out/elf). 149 150In case you get errors about the following symbols, use the config 151option "no-asm", as described in INSTALL: 152 153 BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 154 CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 155 RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 156 bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 157 bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 158 des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 159 des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 160 161If none of these helps, you may want to try using the current snapshot. 162If the problem persists, please submit a bug report. 163 164 165* Where can I get a compiled version of OpenSSL? 166 167Some applications that use OpenSSL are distributed in binary form. 168When using such an application, you don't need to install OpenSSL 169yourself; the application will include the required parts (e.g. DLLs). 170 171If you want to install OpenSSL on a Windows system and you don't have 172a C compiler, read the "Mingw32" section of INSTALL.W32 for information 173on how to obtain and install the free GNU C compiler. 174 175A number of Linux and *BSD distributions include OpenSSL. 176 177 178* I've compiled a program under Windows and it crashes: why? 179 180This is usually because you've missed the comment in INSTALL.W32. You 181must link with the multithreaded DLL version of the VC++ runtime library 182otherwise the conflict will cause a program to crash: typically on the 183first BIO related read or write operation. 184 185 186* How do I read or write a DER encoded buffer using the ASN1 functions? 187 188You have two options. You can either use a memory BIO in conjunction 189with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 190i2d_XXX(), d2i_XXX() functions directly. Since these are often the 191cause of grief here are some code fragments using PKCS7 as an example: 192 193unsigned char *buf, *p; 194int len; 195 196len = i2d_PKCS7(p7, NULL); 197buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 198p = buf; 199i2d_PKCS7(p7, &p); 200 201At this point buf contains the len bytes of the DER encoding of 202p7. 203 204The opposite assumes we already have len bytes in buf: 205 206unsigned char *p; 207p = buf; 208p7 = d2i_PKCS7(NULL, &p, len); 209 210At this point p7 contains a valid PKCS7 structure of NULL if an error 211occurred. If an error occurred ERR_print_errors(bio) should give more 212information. 213 214The reason for the temporary variable 'p' is that the ASN1 functions 215increment the passed pointer so it is ready to read or write the next 216structure. This is often a cause of problems: without the temporary 217variable the buffer pointer is changed to point just after the data 218that has been read or written. This may well be uninitialized data 219and attempts to free the buffer will have unpredictable results 220because it no longer points to the same address. 221 222 223* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 224 225This usually happens when you try compiling something using the PKCS#12 226macros with a C++ compiler. There is hardly ever any need to use the 227PKCS#12 macros in a program, it is much easier to parse and create 228PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 229documented in doc/openssl.txt and with examples in demos/pkcs12. The 230'pkcs12' application has to use the macros because it prints out 231debugging information. 232 233 234* I've called <some function> and it fails, why? 235 236Before submitting a report or asking in one of the mailing lists, you 237should try to determine the cause. In particular, you should call 238ERR_print_errors() or ERR_print_errors_fp() after the failed call 239and see if the message helps. Note that the problem may occur earlier 240than you think -- you should check for errors after every call where 241it is possible, otherwise the actual problem may be hidden because 242some OpenSSL functions clear the error state. 243 244 245* I just get a load of numbers for the error output, what do they mean? 246 247The actual format is described in the ERR_print_errors() manual page. 248You should call the function ERR_load_crypto_strings() before hand and 249the message will be output in text form. If you can't do this (for example 250it is a pre-compiled binary) you can use the errstr utility on the error 251code itself (the hex digits after the second colon). 252 253 254* Why do I get errors about unknown algorithms? 255 256This can happen under several circumstances such as reading in an 257encrypted private key or attempting to decrypt a PKCS#12 file. The cause 258is forgetting to load OpenSSL's table of algorithms with 259OpenSSL_add_all_algorithms(). See the manual page for more information. 260 261 262* How do I create certificates or certificate requests? 263 264Check out the CA.pl(1) manual page. This provides a simple wrapper round 265the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 266out the manual pages for the individual utilities and the certificate 267extensions documentation (currently in doc/openssl.txt). 268 269 270* Why can't I create certificate requests? 271 272You typically get the error: 273 274 unable to find 'distinguished_name' in config 275 problems making Certificate Request 276 277This is because it can't find the configuration file. Check out the 278DIAGNOSTICS section of req(1) for more information. 279 280 281* Why does <SSL program> fail with a certificate verify error? 282 283This problem is usually indicated by log messages saying something like 284"unable to get local issuer certificate" or "self signed certificate". 285When a certificate is verified its root CA must be "trusted" by OpenSSL 286this typically means that the CA certificate must be placed in a directory 287or file and the relevant program configured to read it. The OpenSSL program 288'verify' behaves in a similar way and issues similar error messages: check 289the verify(1) program manual page for more information. 290 291 292* Why can I only use weak ciphers when I connect to a server using OpenSSL? 293 294This is almost certainly because you are using an old "export grade" browser 295which only supports weak encryption. Upgrade your browser to support 128 bit 296ciphers. 297 298 299* How can I create DSA certificates? 300 301Check the CA.pl(1) manual page for a DSA certificate example. 302 303 304* Why can't I make an SSL connection to a server using a DSA certificate? 305 306Typically you'll see a message saying there are no shared ciphers when 307the same setup works fine with an RSA certificate. There are two possible 308causes. The client may not support connections to DSA servers most web 309browsers (including Netscape and MSIE) only support connections to servers 310supporting RSA cipher suites. The other cause is that a set of DH parameters 311has not been supplied to the server. DH parameters can be created with the 312dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 313check the source to s_server in apps/s_server.c for an example. 314 315 316* How can I remove the passphrase on a private key? 317 318Firstly you should be really *really* sure you want to do this. Leaving 319a private key unencrypted is a major security risk. If you decide that 320you do have to do this check the EXAMPLES sections of the rsa(1) and 321dsa(1) manual pages. 322 323 324* Why can't the OpenSSH configure script detect OpenSSL? 325 326There is a problem with OpenSSH 1.2.2p1, in that the configure script 327can't find the installed OpenSSL libraries. The problem is actually 328a small glitch that is easily solved with the following patch to be 329applied to the OpenSSH distribution: 330 331----- snip:start ----- 332--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 333+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 334@@ -152,10 +152,10 @@ 335 AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) 336 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 337 if test ! -z "$ssldir" ; then 338- LIBS="$saved_LIBS -L$ssldir" 339+ LIBS="$saved_LIBS -L$ssldir/lib" 340 CFLAGS="$CFLAGS -I$ssldir/include" 341 if test "x$need_dash_r" = "x1" ; then 342- LIBS="$LIBS -R$ssldir" 343+ LIBS="$LIBS -R$ssldir/lib" 344 fi 345 fi 346 LIBS="$LIBS -lcrypto" 347--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 348+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 349@@ -1890,10 +1890,10 @@ 350 echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 351 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 352 if test ! -z "$ssldir" ; then 353- LIBS="$saved_LIBS -L$ssldir" 354+ LIBS="$saved_LIBS -L$ssldir/lib" 355 CFLAGS="$CFLAGS -I$ssldir/include" 356 if test "x$need_dash_r" = "x1" ; then 357- LIBS="$LIBS -R$ssldir" 358+ LIBS="$LIBS -R$ssldir/lib" 359 fi 360 fi 361 LIBS="$LIBS -lcrypto" 362----- snip:end ----- 363 364 365* Why does the OpenSSL test fail with "bc: command not found"? 366 367You didn't install "bc", the Unix calculator. If you want to run the 368tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 369 370 371* Why does the OpenSSL test fail with "bc: 1 no implemented"? 372 373On some SCO installations or versions, bc has a bug that gets triggered when 374you run the test suite (using "make test"). The message returned is "bc: 3751 not implemented". The best way to deal with this is to find another 376implementation of bc and compile/install it. For example, GNU bc (see 377http://www.gnu.org/software/software.html for download instructions) can 378be safely used. 379 380 381* Why does the OpenSSL compilation fail on Alpha True64 Unix? 382 383On some Alpha installations running True64 Unix and Compaq C, the compilation 384of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 385memory to continue compilation.' As far as the tests have shown, this may be 386a compiler bug. What happens is that it eats up a lot of resident memory 387to build something, probably a table. The problem is clearly in the 388optimization code, because if one eliminates optimization completely (-O0), 389the compilation goes through (and the compiler consumes about 2MB of resident 390memory instead of 240MB or whatever one's limit is currently). 391 392There are three options to solve this problem: 393 3941. set your current data segment size soft limit higher. Experience shows 395that about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 396this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 397kbytes to set the limit to. 398 3992. If you have a hard limit that is lower than what you need and you can't 400get it changed, you can compile all of OpenSSL with -O0 as optimization 401level. This is however not a very nice thing to do for those who expect to 402get the best result from OpenSSL. A bit more complicated solution is the 403following: 404 405----- snip:start ----- 406 make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 407 sed -e 's/ -O[0-9] / -O0 /'`" 408 rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 409 make 410----- snip:end ----- 411 412This will only compile sha_dgst.c with -O0, the rest with the optimization 413level chosen by the configuration process. When the above is done, do the 414test and installation and you're set. 415 416 417* Why does the OpenSSL compilation fail with "ar: command not found"? 418 419Getting this message is quite usual on Solaris 2, because Sun has hidden 420away 'ar' and other development commands in directories that aren't in 421$PATH by default. One of those directories is '/usr/ccs/bin'. The 422quickest way to fix this is to do the following (it assumes you use sh 423or any sh-compatible shell): 424 425----- snip:start ----- 426 PATH=${PATH}:/usr/ccs/bin; export PATH 427----- snip:end ----- 428 429and then redo the compilation. What you should really do is make sure 430'/usr/ccs/bin' is permanently in your $PATH, for example through your 431'.profile' (again, assuming you use a sh-compatible shell). 432 433