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