| FAQ (79998) | FAQ (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? | 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? |
|
| 11 12[LEGAL] Legal questions 13 14* Do I need patent licenses to use OpenSSL? 15* Can I use OpenSSL with GPL software? 16 17[USER] Questions on using the OpenSSL applications 18 19* Why do I get a "PRNG not seeded" error message? 20* Why do I get an "unable to write 'random state'" error message? 21* How do I create certificates or certificate requests? 22* Why can't I create certificate requests? 23* Why does <SSL program> fail with a certificate verify error? 24* Why can I only use weak ciphers when I connect to a server using OpenSSL? 25* How can I create DSA certificates? 26* Why can't I make an SSL connection using a DSA certificate? 27* How can I remove the passphrase on a private key? 28* Why can't I use OpenSSL certificates with SSL client authentication? 29* Why does my browser give a warning about a mismatched hostname? | 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? |
|
| 30 31[BUILD] Questions about building and testing OpenSSL 32 33* Why does the linker complain about undefined symbols? 34* Why does the OpenSSL test fail with "bc: command not found"? 35* Why does the OpenSSL test fail with "bc: 1 no implemented"? | 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"? |
| 36* Why does the OpenSSL compilation fail on Alpha True64 Unix? | 38* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
| 37* Why does the OpenSSL compilation fail with "ar: command not found"? 38* Why does the OpenSSL compilation fail on Win32 with VC++? 39 40[PROG] Questions about programming with OpenSSL 41 42* Is OpenSSL thread-safe? 43* I've compiled a program under Windows and it crashes: why? 44* How do I read or write a DER encoded buffer using the ASN1 functions? --- 7 unchanged lines hidden (view full) --- 52 53=============================================================================== 54 55[MISC] ======================================================================== 56 57* Which is the current version of OpenSSL? 58 59The current version is available from <URL: http://www.openssl.org>. | 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? --- 7 unchanged lines hidden (view full) --- 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>. |
| 60OpenSSL 0.9.6b was released on July 9th, 2001. | 62OpenSSL 0.9.6b was released on December 21st, 2001. |
| 61 62In addition to the current stable release, you can also access daily 63snapshots of the OpenSSL development version at <URL: 64ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 65 66 67* Where is the documentation? 68 --- 47 unchanged lines hidden (view full) --- 116A number of Linux and *BSD distributions include OpenSSL. 117 118 119* Why aren't tools like 'autoconf' and 'libtool' used? 120 121autoconf will probably be used in future OpenSSL versions. If it was 122less Unix-centric, it might have been used much earlier. 123 | 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 --- 47 unchanged lines hidden (view full) --- 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? |
|
| 124 | 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 |
|
| 125[LEGAL] ======================================================================= 126 127* Do I need patent licenses to use OpenSSL? 128 129The patents section of the README file lists patents that may apply to 130you if you want to use OpenSSL. For information on intellectual 131property rights, please consult a lawyer. The OpenSSL team does not 132offer legal advice. --- 8 unchanged lines hidden (view full) --- 141GPL does not place restrictions on using libraries that are part of the 142normal operating system distribution). 143 144On other systems, the situation is less clear. Some GPL software copyright 145holders claim that you infringe on their rights if you use OpenSSL with 146their software on operating systems that don't normally include OpenSSL. 147 148If you develop open source software that uses OpenSSL, you may find it | 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. --- 8 unchanged lines hidden (view full) --- 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 |
| 149useful to choose an other license than the GPL, or state explicitely that | 157useful to choose an other license than the GPL, or state explicitly that |
| 150"This program is released under the GPL with the additional exemption that 151compiling, linking, and/or using OpenSSL is allowed." If you are using 152GPL software developed by others, you may want to ask the copyright holder 153for permission to use their software with OpenSSL. 154 155 156[USER] ======================================================================== 157 --- 23 unchanged lines hidden (view full) --- 181Most components of the openssl command line utility automatically try 182to seed the random number generator from a file. The name of the 183default seeding file is determined as follows: If environment variable 184RANDFILE is set, then it names the seeding file. Otherwise if 185environment variable HOME is set, then the seeding file is $HOME/.rnd. 186If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 187use file .rnd in the current directory while OpenSSL 0.9.6a uses no 188default seeding file at all. OpenSSL 0.9.6b and later will behave | 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 --- 23 unchanged lines hidden (view full) --- 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 |
| 189similarly to 0.9.6a, but will use a default of "C:" for HOME on | 197similarly to 0.9.6a, but will use a default of "C:\" for HOME on |
| 190Windows systems if the environment variable has not been set. 191 192If the default seeding file does not exist or is too short, the "PRNG 193not seeded" error message may occur. 194 195The openssl command line utility will write back a new state to the 196default seeding file (and create this file if necessary) unless 197there was no sufficient seeding. --- 94 unchanged lines hidden (view full) --- 292no client certificates (Netscape) or present you with an empty list box 293(MSIE). The reason for this is that when a server requests a client 294certificate it includes a list of CAs names which it will accept. Browsers 295will only let you select certificates from the list on the grounds that 296there is little point presenting a certificate which the server will 297reject. 298 299The solution is to add the relevant CA certificate to your servers "trusted | 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. --- 94 unchanged lines hidden (view full) --- 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 |
| 300CA list". How you do this depends on the server sofware in uses. You can | 308CA list". How you do this depends on the server software in uses. You can |
| 301print out the servers list of acceptable CAs using the OpenSSL s_client tool: 302 303openssl s_client -connect www.some.host:443 -prexit 304 305If your server only requests certificates on certain URLs then you may need 306to manually issue an HTTP GET command to get the list when s_client connects: 307 308GET /some/page/needing/a/certificate.html 309 310If your CA does not appear in the list then this confirms the problem. 311 312 313* Why does my browser give a warning about a mismatched hostname? 314 315Browsers expect the server's hostname to match the value in the commonName 316(CN) field of the certificate. If it does not then you get a warning. 317 318 | 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 |
|
| 319[BUILD] ======================================================================= 320 321* Why does the linker complain about undefined symbols? 322 323Maybe the compilation was interrupted, and make doesn't notice that 324something is missing. Run "make clean; make". 325 326If you used ./Configure instead of ./config, make sure that you --- 27 unchanged lines hidden (view full) --- 354when you run the test suite (using "make test"). The message returned is 355"bc: 1 not implemented". 356 357The best way to deal with this is to find another implementation of bc 358and compile/install it. GNU bc (see http://www.gnu.org/software/software.html 359for download instructions) can be safely used, for example. 360 361 | 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 --- 27 unchanged lines hidden (view full) --- 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 |
| 362* Why does the OpenSSL compilation fail on Alpha True64 Unix? | 390* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
| 363 | 391 |
| 364On some Alpha installations running True64 Unix and Compaq C, the compilation | 392On some Alpha installations running Tru64 Unix and Compaq C, the compilation |
| 365of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 366memory to continue compilation.' As far as the tests have shown, this may be 367a compiler bug. What happens is that it eats up a lot of resident memory 368to build something, probably a table. The problem is clearly in the 369optimization code, because if one eliminates optimization completely (-O0), 370the compilation goes through (and the compiler consumes about 2MB of resident 371memory instead of 240MB or whatever one's limit is currently). 372 --- 61 unchanged lines hidden (view full) --- 434file. 435 436Multi-threaded applications must provide two callback functions to 437OpenSSL. This is described in the threads(3) manpage. 438 439 440* I've compiled a program under Windows and it crashes: why? 441 | 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 --- 61 unchanged lines hidden (view full) --- 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 |
| 442This is usually because you've missed the comment in INSTALL.W32. You 443must link with the multithreaded DLL version of the VC++ runtime library 444otherwise the conflict will cause a program to crash: typically on the 445first BIO related read or write operation. | 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". |
| 446 | 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. |
|
| 447 | 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 |
|
| 448* How do I read or write a DER encoded buffer using the ASN1 functions? 449 450You have two options. You can either use a memory BIO in conjunction 451with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 452i2d_XXX(), d2i_XXX() functions directly. Since these are often the 453cause of grief here are some code fragments using PKCS7 as an example: 454 455unsigned char *buf, *p; --- 62 unchanged lines hidden (view full) --- 518This can happen under several circumstances such as reading in an 519encrypted private key or attempting to decrypt a PKCS#12 file. The cause 520is forgetting to load OpenSSL's table of algorithms with 521OpenSSL_add_all_algorithms(). See the manual page for more information. 522 523 524* Why can't the OpenSSH configure script detect OpenSSL? 525 | 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; --- 62 unchanged lines hidden (view full) --- 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 |
| 526There is a problem with OpenSSH 1.2.2p1, in that the configure script 527can't find the installed OpenSSL libraries. The problem is actually 528a small glitch that is easily solved with the following patch to be 529applied to the OpenSSH distribution: | 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. |
| 530 | 593 |
| 531----- snip:start ----- 532--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 533+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 534@@ -152,10 +152,10 @@ 535 AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) 536 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 537 if test ! -z "$ssldir" ; then 538- LIBS="$saved_LIBS -L$ssldir" 539+ LIBS="$saved_LIBS -L$ssldir/lib" 540 CFLAGS="$CFLAGS -I$ssldir/include" 541 if test "x$need_dash_r" = "x1" ; then 542- LIBS="$LIBS -R$ssldir" 543+ LIBS="$LIBS -R$ssldir/lib" 544 fi 545 fi 546 LIBS="$LIBS -lcrypto" 547--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 548+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 549@@ -1890,10 +1890,10 @@ 550 echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 551 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 552 if test ! -z "$ssldir" ; then 553- LIBS="$saved_LIBS -L$ssldir" 554+ LIBS="$saved_LIBS -L$ssldir/lib" 555 CFLAGS="$CFLAGS -I$ssldir/include" 556 if test "x$need_dash_r" = "x1" ; then 557- LIBS="$LIBS -R$ssldir" 558+ LIBS="$LIBS -R$ssldir/lib" 559 fi 560 fi 561 LIBS="$LIBS -lcrypto" 562----- snip:end ----- | 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. |
| 563 | 597 |
| 564 | |
| 565* Can I use OpenSSL's SSL library with non-blocking I/O? 566 567Yes; make sure to read the SSL_get_error(3) manual page! 568 569A pitfall to avoid: Don't assume that SSL_read() will just read from 570the underlying transport or that SSL_write() will just write to it -- 571it is also possible that SSL_write() cannot do any useful work until 572there is data to read, or that SSL_read() cannot do anything until it 573is possible to send data. One reason for this is that the peer may 574request a new TLS/SSL handshake at any time during the protocol, 575requiring a bi-directional message exchange; both SSL_read() and 576SSL_write() will try to continue any pending handshake. 577 578 579* Why doesn't my server application receive a client certificate? 580 581Due to the TLS protocol definition, a client will only send a certificate, | 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, |
| 582if explicitely asked by the server. Use the SSL_VERIFY_PEER flag of the | 615if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the |
| 583SSL_CTX_set_verify() function to enable the use of client certificates. 584 585 586=============================================================================== 587 | 616SSL_CTX_set_verify() function to enable the use of client certificates. 617 618 619=============================================================================== 620 |