FAQ revision 89837
1OpenSSL - Frequently Asked Questions 2-------------------------------------- 3 4[MISC] Miscellaneous questions 5 6* Which is the current version of OpenSSL? 7* Where is the documentation? 8* How can I contact the OpenSSL developers? 9* Where can I get a compiled version of OpenSSL? 10* Why aren't tools like 'autoconf' and 'libtool' used? 11* What is an 'engine' version? 12 13[LEGAL] Legal questions 14 15* Do I need patent licenses to use OpenSSL? 16* Can I use OpenSSL with GPL software? 17 18[USER] Questions on using the OpenSSL applications 19 20* Why do I get a "PRNG not seeded" error message? 21* Why do I get an "unable to write 'random state'" error message? 22* How do I create certificates or certificate requests? 23* Why can't I create certificate requests? 24* Why does <SSL program> fail with a certificate verify error? 25* Why can I only use weak ciphers when I connect to a server using OpenSSL? 26* How can I create DSA certificates? 27* Why can't I make an SSL connection using a DSA certificate? 28* How can I remove the passphrase on a private key? 29* Why can't I use OpenSSL certificates with SSL client authentication? 30* Why does my browser give a warning about a mismatched hostname? 31* How do I install a CA certificate into a browser? 32 33[BUILD] Questions about building and testing OpenSSL 34 35* Why does the linker complain about undefined symbols? 36* Why does the OpenSSL test fail with "bc: command not found"? 37* Why does the OpenSSL test fail with "bc: 1 no implemented"? 38* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 39* Why does the OpenSSL compilation fail with "ar: command not found"? 40* Why does the OpenSSL compilation fail on Win32 with VC++? 41 42[PROG] Questions about programming with OpenSSL 43 44* Is OpenSSL thread-safe? 45* I've compiled a program under Windows and it crashes: why? 46* How do I read or write a DER encoded buffer using the ASN1 functions? 47* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 48* I've called <some function> and it fails, why? 49* I just get a load of numbers for the error output, what do they mean? 50* Why do I get errors about unknown algorithms? 51* Why can't the OpenSSH configure script detect OpenSSL? 52* Can I use OpenSSL's SSL library with non-blocking I/O? 53* Why doesn't my server application receive a client certificate? 54 55=============================================================================== 56 57[MISC] ======================================================================== 58 59* Which is the current version of OpenSSL? 60 61The current version is available from <URL: http://www.openssl.org>. 62OpenSSL 0.9.6b was released on December 21st, 2001. 63 64In addition to the current stable release, you can also access daily 65snapshots of the OpenSSL development version at <URL: 66ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 67 68 69* Where is the documentation? 70 71OpenSSL is a library that provides cryptographic functionality to 72applications such as secure web servers. Be sure to read the 73documentation of the application you want to use. The INSTALL file 74explains how to install this library. 75 76OpenSSL includes a command line utility that can be used to perform a 77variety of cryptographic functions. It is described in the openssl(1) 78manpage. Documentation for developers is currently being written. A 79few manual pages already are available; overviews over libcrypto and 80libssl are given in the crypto(3) and ssl(3) manpages. 81 82The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 83different directory if you specified one as described in INSTALL). 84In addition, you can read the most current versions at 85<URL: http://www.openssl.org/docs/>. 86 87For information on parts of libcrypto that are not yet documented, you 88might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 89predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 90of this still applies to OpenSSL. 91 92There is some documentation about certificate extensions and PKCS#12 93in doc/openssl.txt 94 95The original SSLeay documentation is included in OpenSSL as 96doc/ssleay.txt. It may be useful when none of the other resources 97help, but please note that it reflects the obsolete version SSLeay 980.6.6. 99 100 101* How can I contact the OpenSSL developers? 102 103The README file describes how to submit bug reports and patches to 104OpenSSL. Information on the OpenSSL mailing lists is available from 105<URL: http://www.openssl.org>. 106 107 108* Where can I get a compiled version of OpenSSL? 109 110Some applications that use OpenSSL are distributed in binary form. 111When using such an application, you don't need to install OpenSSL 112yourself; the application will include the required parts (e.g. DLLs). 113 114If you want to install OpenSSL on a Windows system and you don't have 115a C compiler, read the "Mingw32" section of INSTALL.W32 for information 116on how to obtain and install the free GNU C compiler. 117 118A number of Linux and *BSD distributions include OpenSSL. 119 120 121* Why aren't tools like 'autoconf' and 'libtool' used? 122 123autoconf will probably be used in future OpenSSL versions. If it was 124less Unix-centric, it might have been used much earlier. 125 126* What is an 'engine' version? 127 128With version 0.9.6 OpenSSL was extended to interface to external crypto 129hardware. This was realized in a special release '0.9.6-engine'. With 130version 0.9.7 (not yet released) the changes were merged into the main 131development line, so that the special release is no longer necessary. 132 133[LEGAL] ======================================================================= 134 135* Do I need patent licenses to use OpenSSL? 136 137The patents section of the README file lists patents that may apply to 138you if you want to use OpenSSL. For information on intellectual 139property rights, please consult a lawyer. The OpenSSL team does not 140offer legal advice. 141 142You can configure OpenSSL so as not to use RC5 and IDEA by using 143 ./config no-rc5 no-idea 144 145 146* Can I use OpenSSL with GPL software? 147 148On many systems including the major Linux and BSD distributions, yes (the 149GPL does not place restrictions on using libraries that are part of the 150normal operating system distribution). 151 152On other systems, the situation is less clear. Some GPL software copyright 153holders claim that you infringe on their rights if you use OpenSSL with 154their software on operating systems that don't normally include OpenSSL. 155 156If you develop open source software that uses OpenSSL, you may find it 157useful to choose an other license than the GPL, or state explicitly that 158"This program is released under the GPL with the additional exemption that 159compiling, linking, and/or using OpenSSL is allowed." If you are using 160GPL software developed by others, you may want to ask the copyright holder 161for permission to use their software with OpenSSL. 162 163 164[USER] ======================================================================== 165 166* Why do I get a "PRNG not seeded" error message? 167 168Cryptographic software needs a source of unpredictable data to work 169correctly. Many open source operating systems provide a "randomness 170device" that serves this purpose. On other systems, applications have 171to call the RAND_add() or RAND_seed() function with appropriate data 172before generating keys or performing public key encryption. 173(These functions initialize the pseudo-random number generator, PRNG.) 174 175Some broken applications do not do this. As of version 0.9.5, the 176OpenSSL functions that need randomness report an error if the random 177number generator has not been seeded with at least 128 bits of 178randomness. If this error occurs, please contact the author of the 179application you are using. It is likely that it never worked 180correctly. OpenSSL 0.9.5 and later make the error visible by refusing 181to perform potentially insecure encryption. 182 183On systems without /dev/urandom and /dev/random, it is a good idea to 184use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 185details. Starting with version 0.9.7, OpenSSL will automatically look 186for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 187/etc/entropy. 188 189Most components of the openssl command line utility automatically try 190to seed the random number generator from a file. The name of the 191default seeding file is determined as follows: If environment variable 192RANDFILE is set, then it names the seeding file. Otherwise if 193environment variable HOME is set, then the seeding file is $HOME/.rnd. 194If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 195use file .rnd in the current directory while OpenSSL 0.9.6a uses no 196default seeding file at all. OpenSSL 0.9.6b and later will behave 197similarly to 0.9.6a, but will use a default of "C:\" for HOME on 198Windows systems if the environment variable has not been set. 199 200If the default seeding file does not exist or is too short, the "PRNG 201not seeded" error message may occur. 202 203The openssl command line utility will write back a new state to the 204default seeding file (and create this file if necessary) unless 205there was no sufficient seeding. 206 207Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 208Use the "-rand" option of the OpenSSL command line tools instead. 209The $RANDFILE environment variable and $HOME/.rnd are only used by the 210OpenSSL command line tools. Applications using the OpenSSL library 211provide their own configuration options to specify the entropy source, 212please check out the documentation coming the with application. 213 214For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested 215installing the SUNski package from Sun patch 105710-01 (Sparc) which 216adds a /dev/random device and make sure it gets used, usually through 217$RANDFILE. There are probably similar patches for the other Solaris 218versions. However, be warned that /dev/random is usually a blocking 219device, which may have some effects on OpenSSL. 220 221 222* Why do I get an "unable to write 'random state'" error message? 223 224 225Sometimes the openssl command line utility does not abort with 226a "PRNG not seeded" error message, but complains that it is 227"unable to write 'random state'". This message refers to the 228default seeding file (see previous answer). A possible reason 229is that no default filename is known because neither RANDFILE 230nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 231current directory in this case, but this has changed with 0.9.6a.) 232 233 234* How do I create certificates or certificate requests? 235 236Check out the CA.pl(1) manual page. This provides a simple wrapper round 237the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 238out the manual pages for the individual utilities and the certificate 239extensions documentation (currently in doc/openssl.txt). 240 241 242* Why can't I create certificate requests? 243 244You typically get the error: 245 246 unable to find 'distinguished_name' in config 247 problems making Certificate Request 248 249This is because it can't find the configuration file. Check out the 250DIAGNOSTICS section of req(1) for more information. 251 252 253* Why does <SSL program> fail with a certificate verify error? 254 255This problem is usually indicated by log messages saying something like 256"unable to get local issuer certificate" or "self signed certificate". 257When a certificate is verified its root CA must be "trusted" by OpenSSL 258this typically means that the CA certificate must be placed in a directory 259or file and the relevant program configured to read it. The OpenSSL program 260'verify' behaves in a similar way and issues similar error messages: check 261the verify(1) program manual page for more information. 262 263 264* Why can I only use weak ciphers when I connect to a server using OpenSSL? 265 266This is almost certainly because you are using an old "export grade" browser 267which only supports weak encryption. Upgrade your browser to support 128 bit 268ciphers. 269 270 271* How can I create DSA certificates? 272 273Check the CA.pl(1) manual page for a DSA certificate example. 274 275 276* Why can't I make an SSL connection to a server using a DSA certificate? 277 278Typically you'll see a message saying there are no shared ciphers when 279the same setup works fine with an RSA certificate. There are two possible 280causes. The client may not support connections to DSA servers most web 281browsers (including Netscape and MSIE) only support connections to servers 282supporting RSA cipher suites. The other cause is that a set of DH parameters 283has not been supplied to the server. DH parameters can be created with the 284dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 285check the source to s_server in apps/s_server.c for an example. 286 287 288* How can I remove the passphrase on a private key? 289 290Firstly you should be really *really* sure you want to do this. Leaving 291a private key unencrypted is a major security risk. If you decide that 292you do have to do this check the EXAMPLES sections of the rsa(1) and 293dsa(1) manual pages. 294 295 296* Why can't I use OpenSSL certificates with SSL client authentication? 297 298What will typically happen is that when a server requests authentication 299it will either not include your certificate or tell you that you have 300no client certificates (Netscape) or present you with an empty list box 301(MSIE). The reason for this is that when a server requests a client 302certificate it includes a list of CAs names which it will accept. Browsers 303will only let you select certificates from the list on the grounds that 304there is little point presenting a certificate which the server will 305reject. 306 307The solution is to add the relevant CA certificate to your servers "trusted 308CA list". How you do this depends on the server software in uses. You can 309print out the servers list of acceptable CAs using the OpenSSL s_client tool: 310 311openssl s_client -connect www.some.host:443 -prexit 312 313If your server only requests certificates on certain URLs then you may need 314to manually issue an HTTP GET command to get the list when s_client connects: 315 316GET /some/page/needing/a/certificate.html 317 318If your CA does not appear in the list then this confirms the problem. 319 320 321* Why does my browser give a warning about a mismatched hostname? 322 323Browsers expect the server's hostname to match the value in the commonName 324(CN) field of the certificate. If it does not then you get a warning. 325 326 327* How do I install a CA certificate into a browser? 328 329The usual way is to send the DER encoded certificate to the browser as 330MIME type application/x-x509-ca-cert, for example by clicking on an appropriate 331link. On MSIE certain extensions such as .der or .cacert may also work, or you 332can import the certificate using the certificate import wizard. 333 334You can convert a certificate to DER form using the command: 335 336openssl x509 -in ca.pem -outform DER -out ca.der 337 338Occasionally someone suggests using a command such as: 339 340openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 341 342DO NOT DO THIS! This command will give away your CAs private key and 343reduces its security to zero: allowing anyone to forge certificates in 344whatever name they choose. 345 346 347[BUILD] ======================================================================= 348 349* Why does the linker complain about undefined symbols? 350 351Maybe the compilation was interrupted, and make doesn't notice that 352something is missing. Run "make clean; make". 353 354If you used ./Configure instead of ./config, make sure that you 355selected the right target. File formats may differ slightly between 356OS versions (for example sparcv8/sparcv9, or a.out/elf). 357 358In case you get errors about the following symbols, use the config 359option "no-asm", as described in INSTALL: 360 361 BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 362 CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 363 RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 364 bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 365 bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 366 des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 367 des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 368 369If none of these helps, you may want to try using the current snapshot. 370If the problem persists, please submit a bug report. 371 372 373* Why does the OpenSSL test fail with "bc: command not found"? 374 375You didn't install "bc", the Unix calculator. If you want to run the 376tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 377 378 379* Why does the OpenSSL test fail with "bc: 1 no implemented"? 380 381On some SCO installations or versions, bc has a bug that gets triggered 382when you run the test suite (using "make test"). The message returned is 383"bc: 1 not implemented". 384 385The best way to deal with this is to find another implementation of bc 386and compile/install it. GNU bc (see http://www.gnu.org/software/software.html 387for download instructions) can be safely used, for example. 388 389 390* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 391 392On some Alpha installations running Tru64 Unix and Compaq C, the compilation 393of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 394memory to continue compilation.' As far as the tests have shown, this may be 395a compiler bug. What happens is that it eats up a lot of resident memory 396to build something, probably a table. The problem is clearly in the 397optimization code, because if one eliminates optimization completely (-O0), 398the compilation goes through (and the compiler consumes about 2MB of resident 399memory instead of 240MB or whatever one's limit is currently). 400 401There are three options to solve this problem: 402 4031. set your current data segment size soft limit higher. Experience shows 404that about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 405this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 406kbytes to set the limit to. 407 4082. If you have a hard limit that is lower than what you need and you can't 409get it changed, you can compile all of OpenSSL with -O0 as optimization 410level. This is however not a very nice thing to do for those who expect to 411get the best result from OpenSSL. A bit more complicated solution is the 412following: 413 414----- snip:start ----- 415 make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 416 sed -e 's/ -O[0-9] / -O0 /'`" 417 rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 418 make 419----- snip:end ----- 420 421This will only compile sha_dgst.c with -O0, the rest with the optimization 422level chosen by the configuration process. When the above is done, do the 423test and installation and you're set. 424 425 426* Why does the OpenSSL compilation fail with "ar: command not found"? 427 428Getting this message is quite usual on Solaris 2, because Sun has hidden 429away 'ar' and other development commands in directories that aren't in 430$PATH by default. One of those directories is '/usr/ccs/bin'. The 431quickest way to fix this is to do the following (it assumes you use sh 432or any sh-compatible shell): 433 434----- snip:start ----- 435 PATH=${PATH}:/usr/ccs/bin; export PATH 436----- snip:end ----- 437 438and then redo the compilation. What you should really do is make sure 439'/usr/ccs/bin' is permanently in your $PATH, for example through your 440'.profile' (again, assuming you use a sh-compatible shell). 441 442 443* Why does the OpenSSL compilation fail on Win32 with VC++? 444 445Sometimes, you may get reports from VC++ command line (cl) that it 446can't find standard include files like stdio.h and other weirdnesses. 447One possible cause is that the environment isn't correctly set up. 448To solve that problem, one should run VCVARS32.BAT which is found in 449the 'bin' subdirectory of the VC++ installation directory (somewhere 450under 'Program Files'). This needs to be done prior to running NMAKE, 451and the changes are only valid for the current DOS session. 452 453 454[PROG] ======================================================================== 455 456* Is OpenSSL thread-safe? 457 458Yes (with limitations: an SSL connection may not concurrently be used 459by multiple threads). On Windows and many Unix systems, OpenSSL 460automatically uses the multi-threaded versions of the standard 461libraries. If your platform is not one of these, consult the INSTALL 462file. 463 464Multi-threaded applications must provide two callback functions to 465OpenSSL. This is described in the threads(3) manpage. 466 467 468* I've compiled a program under Windows and it crashes: why? 469 470This is usually because you've missed the comment in INSTALL.W32. 471Your application must link against the same version of the Win32 472C-Runtime against which your openssl libraries were linked. The 473default version for OpenSSL is /MD - "Multithreaded DLL". 474 475If you are using Microsoft Visual C++'s IDE (Visual Studio), in 476many cases, your new project most likely defaulted to "Debug 477Singlethreaded" - /ML. This is NOT interchangeable with /MD and your 478program will crash, typically on the first BIO related read or write 479operation. 480 481For each of the six possible link stage configurations within Win32, 482your application must link against the same by which OpenSSL was 483built. If you are using MS Visual C++ (Studio) this can be changed 484by: 485 4861. Select Settings... from the Project Menu. 4872. Select the C/C++ Tab. 4883. Select "Code Generation from the "Category" drop down list box 4894. Select the Appropriate library (see table below) from the "Use 490 run-time library" drop down list box. Perform this step for both 491 your debug and release versions of your application (look at the 492 top left of the settings panel to change between the two) 493 494 Single Threaded /ML - MS VC++ often defaults to 495 this for the release 496 version of a new project. 497 Debug Single Threaded /MLd - MS VC++ often defaults to 498 this for the debug version 499 of a new project. 500 Multithreaded /MT 501 Debug Multithreaded /MTd 502 Multithreaded DLL /MD - OpenSSL defaults to this. 503 Debug Multithreaded DLL /MDd 504 505Note that debug and release libraries are NOT interchangeable. If you 506built OpenSSL with /MD your application must use /MD and cannot use /MDd. 507 508 509* How do I read or write a DER encoded buffer using the ASN1 functions? 510 511You have two options. You can either use a memory BIO in conjunction 512with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 513i2d_XXX(), d2i_XXX() functions directly. Since these are often the 514cause of grief here are some code fragments using PKCS7 as an example: 515 516unsigned char *buf, *p; 517int len; 518 519len = i2d_PKCS7(p7, NULL); 520buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 521p = buf; 522i2d_PKCS7(p7, &p); 523 524At this point buf contains the len bytes of the DER encoding of 525p7. 526 527The opposite assumes we already have len bytes in buf: 528 529unsigned char *p; 530p = buf; 531p7 = d2i_PKCS7(NULL, &p, len); 532 533At this point p7 contains a valid PKCS7 structure of NULL if an error 534occurred. If an error occurred ERR_print_errors(bio) should give more 535information. 536 537The reason for the temporary variable 'p' is that the ASN1 functions 538increment the passed pointer so it is ready to read or write the next 539structure. This is often a cause of problems: without the temporary 540variable the buffer pointer is changed to point just after the data 541that has been read or written. This may well be uninitialized data 542and attempts to free the buffer will have unpredictable results 543because it no longer points to the same address. 544 545 546* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 547 548This usually happens when you try compiling something using the PKCS#12 549macros with a C++ compiler. There is hardly ever any need to use the 550PKCS#12 macros in a program, it is much easier to parse and create 551PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 552documented in doc/openssl.txt and with examples in demos/pkcs12. The 553'pkcs12' application has to use the macros because it prints out 554debugging information. 555 556 557* I've called <some function> and it fails, why? 558 559Before submitting a report or asking in one of the mailing lists, you 560should try to determine the cause. In particular, you should call 561ERR_print_errors() or ERR_print_errors_fp() after the failed call 562and see if the message helps. Note that the problem may occur earlier 563than you think -- you should check for errors after every call where 564it is possible, otherwise the actual problem may be hidden because 565some OpenSSL functions clear the error state. 566 567 568* I just get a load of numbers for the error output, what do they mean? 569 570The actual format is described in the ERR_print_errors() manual page. 571You should call the function ERR_load_crypto_strings() before hand and 572the message will be output in text form. If you can't do this (for example 573it is a pre-compiled binary) you can use the errstr utility on the error 574code itself (the hex digits after the second colon). 575 576 577* Why do I get errors about unknown algorithms? 578 579This can happen under several circumstances such as reading in an 580encrypted private key or attempting to decrypt a PKCS#12 file. The cause 581is forgetting to load OpenSSL's table of algorithms with 582OpenSSL_add_all_algorithms(). See the manual page for more information. 583 584 585* Why can't the OpenSSH configure script detect OpenSSL? 586 587Several reasons for problems with the automatic detection exist. 588OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 589Sometimes the distribution has installed an older version in the system 590locations that is detected instead of a new one installed. The OpenSSL 591library might have been compiled for another CPU or another mode (32/64 bits). 592Permissions might be wrong. 593 594The general answer is to check the config.log file generated when running 595the OpenSSH configure script. It should contain the detailed information 596on why the OpenSSL library was not detected or considered incompatible. 597 598* Can I use OpenSSL's SSL library with non-blocking I/O? 599 600Yes; make sure to read the SSL_get_error(3) manual page! 601 602A pitfall to avoid: Don't assume that SSL_read() will just read from 603the underlying transport or that SSL_write() will just write to it -- 604it is also possible that SSL_write() cannot do any useful work until 605there is data to read, or that SSL_read() cannot do anything until it 606is possible to send data. One reason for this is that the peer may 607request a new TLS/SSL handshake at any time during the protocol, 608requiring a bi-directional message exchange; both SSL_read() and 609SSL_write() will try to continue any pending handshake. 610 611 612* Why doesn't my server application receive a client certificate? 613 614Due to the TLS protocol definition, a client will only send a certificate, 615if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 616SSL_CTX_set_verify() function to enable the use of client certificates. 617 618 619=============================================================================== 620 621