FAQ revision 100936
159191SkrisOpenSSL - Frequently Asked Questions 259191Skris-------------------------------------- 359191Skris 476866Skris[MISC] Miscellaneous questions 576866Skris 659191Skris* Which is the current version of OpenSSL? 759191Skris* Where is the documentation? 859191Skris* How can I contact the OpenSSL developers? 976866Skris* Where can I get a compiled version of OpenSSL? 1076866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 1189837Skris* What is an 'engine' version? 1276866Skris 1376866Skris[LEGAL] Legal questions 1476866Skris 1559191Skris* Do I need patent licenses to use OpenSSL? 1676866Skris* Can I use OpenSSL with GPL software? 1776866Skris 1876866Skris[USER] Questions on using the OpenSSL applications 1976866Skris 2059191Skris* Why do I get a "PRNG not seeded" error message? 2179998Skris* Why do I get an "unable to write 'random state'" error message? 2259191Skris* How do I create certificates or certificate requests? 2359191Skris* Why can't I create certificate requests? 2459191Skris* Why does <SSL program> fail with a certificate verify error? 2568651Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 2659191Skris* How can I create DSA certificates? 2759191Skris* Why can't I make an SSL connection using a DSA certificate? 2868651Skris* How can I remove the passphrase on a private key? 2976866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 3076866Skris* Why does my browser give a warning about a mismatched hostname? 3189837Skris* How do I install a CA certificate into a browser? 3276866Skris 3376866Skris[BUILD] Questions about building and testing OpenSSL 3476866Skris 3576866Skris* Why does the linker complain about undefined symbols? 3668651Skris* Why does the OpenSSL test fail with "bc: command not found"? 3768651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 3889837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 3968651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 4076866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 41100936Snectar* What is special about OpenSSL on Redhat? 42100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 4359191Skris 4476866Skris[PROG] Questions about programming with OpenSSL 4559191Skris 4676866Skris* Is OpenSSL thread-safe? 4776866Skris* I've compiled a program under Windows and it crashes: why? 4876866Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 4976866Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 5076866Skris* I've called <some function> and it fails, why? 5176866Skris* I just get a load of numbers for the error output, what do they mean? 5276866Skris* Why do I get errors about unknown algorithms? 5376866Skris* Why can't the OpenSSH configure script detect OpenSSL? 5476866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 5579998Skris* Why doesn't my server application receive a client certificate? 5676866Skris 5776866Skris=============================================================================== 5876866Skris 5976866Skris[MISC] ======================================================================== 6076866Skris 6159191Skris* Which is the current version of OpenSSL? 6259191Skris 6359191SkrisThe current version is available from <URL: http://www.openssl.org>. 64100936SnectarOpenSSL 0.9.6e was released on 30 May, 2002. 6559191Skris 6659191SkrisIn addition to the current stable release, you can also access daily 6759191Skrissnapshots of the OpenSSL development version at <URL: 6859191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 6959191Skris 7059191Skris 7159191Skris* Where is the documentation? 7259191Skris 7359191SkrisOpenSSL is a library that provides cryptographic functionality to 7459191Skrisapplications such as secure web servers. Be sure to read the 7559191Skrisdocumentation of the application you want to use. The INSTALL file 7659191Skrisexplains how to install this library. 7759191Skris 7859191SkrisOpenSSL includes a command line utility that can be used to perform a 7959191Skrisvariety of cryptographic functions. It is described in the openssl(1) 8059191Skrismanpage. Documentation for developers is currently being written. A 8159191Skrisfew manual pages already are available; overviews over libcrypto and 8259191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 8359191Skris 8459191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 8559191Skrisdifferent directory if you specified one as described in INSTALL). 8659191SkrisIn addition, you can read the most current versions at 8759191Skris<URL: http://www.openssl.org/docs/>. 8859191Skris 8959191SkrisFor information on parts of libcrypto that are not yet documented, you 9059191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 9159191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 9259191Skrisof this still applies to OpenSSL. 9359191Skris 9459191SkrisThere is some documentation about certificate extensions and PKCS#12 9559191Skrisin doc/openssl.txt 9659191Skris 9759191SkrisThe original SSLeay documentation is included in OpenSSL as 9859191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 9959191Skrishelp, but please note that it reflects the obsolete version SSLeay 10059191Skris0.6.6. 10159191Skris 10259191Skris 10359191Skris* How can I contact the OpenSSL developers? 10459191Skris 10559191SkrisThe README file describes how to submit bug reports and patches to 10659191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 10759191Skris<URL: http://www.openssl.org>. 10859191Skris 10959191Skris 11076866Skris* Where can I get a compiled version of OpenSSL? 11176866Skris 11276866SkrisSome applications that use OpenSSL are distributed in binary form. 11376866SkrisWhen using such an application, you don't need to install OpenSSL 11476866Skrisyourself; the application will include the required parts (e.g. DLLs). 11576866Skris 11676866SkrisIf you want to install OpenSSL on a Windows system and you don't have 11776866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 11876866Skrison how to obtain and install the free GNU C compiler. 11976866Skris 12076866SkrisA number of Linux and *BSD distributions include OpenSSL. 12176866Skris 12276866Skris 12376866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 12476866Skris 12576866Skrisautoconf will probably be used in future OpenSSL versions. If it was 12676866Skrisless Unix-centric, it might have been used much earlier. 12776866Skris 12889837Skris* What is an 'engine' version? 12976866Skris 13089837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 13189837Skrishardware. This was realized in a special release '0.9.6-engine'. With 13289837Skrisversion 0.9.7 (not yet released) the changes were merged into the main 13389837Skrisdevelopment line, so that the special release is no longer necessary. 13489837Skris 13576866Skris[LEGAL] ======================================================================= 13676866Skris 13759191Skris* Do I need patent licenses to use OpenSSL? 13859191Skris 13959191SkrisThe patents section of the README file lists patents that may apply to 14059191Skrisyou if you want to use OpenSSL. For information on intellectual 14159191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 14259191Skrisoffer legal advice. 14359191Skris 14459191SkrisYou can configure OpenSSL so as not to use RC5 and IDEA by using 14559191Skris ./config no-rc5 no-idea 14659191Skris 14759191Skris 14876866Skris* Can I use OpenSSL with GPL software? 14959191Skris 15076866SkrisOn many systems including the major Linux and BSD distributions, yes (the 15176866SkrisGPL does not place restrictions on using libraries that are part of the 15276866Skrisnormal operating system distribution). 15359191Skris 15476866SkrisOn other systems, the situation is less clear. Some GPL software copyright 15576866Skrisholders claim that you infringe on their rights if you use OpenSSL with 15676866Skristheir software on operating systems that don't normally include OpenSSL. 15759191Skris 15876866SkrisIf you develop open source software that uses OpenSSL, you may find it 15989837Skrisuseful to choose an other license than the GPL, or state explicitly that 16076866Skris"This program is released under the GPL with the additional exemption that 16176866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 16276866SkrisGPL software developed by others, you may want to ask the copyright holder 16376866Skrisfor permission to use their software with OpenSSL. 16459191Skris 16576866Skris 16676866Skris[USER] ======================================================================== 16776866Skris 16859191Skris* Why do I get a "PRNG not seeded" error message? 16959191Skris 17059191SkrisCryptographic software needs a source of unpredictable data to work 17159191Skriscorrectly. Many open source operating systems provide a "randomness 17259191Skrisdevice" that serves this purpose. On other systems, applications have 17359191Skristo call the RAND_add() or RAND_seed() function with appropriate data 17459191Skrisbefore generating keys or performing public key encryption. 17579998Skris(These functions initialize the pseudo-random number generator, PRNG.) 17659191Skris 17759191SkrisSome broken applications do not do this. As of version 0.9.5, the 17859191SkrisOpenSSL functions that need randomness report an error if the random 17959191Skrisnumber generator has not been seeded with at least 128 bits of 18059191Skrisrandomness. If this error occurs, please contact the author of the 18159191Skrisapplication you are using. It is likely that it never worked 18259191Skriscorrectly. OpenSSL 0.9.5 and later make the error visible by refusing 18359191Skristo perform potentially insecure encryption. 18459191Skris 18579998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 18679998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 18779998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 18879998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 18979998Skris/etc/entropy. 19059191Skris 19179998SkrisMost components of the openssl command line utility automatically try 19279998Skristo seed the random number generator from a file. The name of the 19379998Skrisdefault seeding file is determined as follows: If environment variable 19479998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 19579998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 19679998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 19779998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 19879998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 19989837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 20079998SkrisWindows systems if the environment variable has not been set. 20159191Skris 20279998SkrisIf the default seeding file does not exist or is too short, the "PRNG 20379998Skrisnot seeded" error message may occur. 20459191Skris 20579998SkrisThe openssl command line utility will write back a new state to the 20679998Skrisdefault seeding file (and create this file if necessary) unless 20779998Skristhere was no sufficient seeding. 20879998Skris 20979998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 21079998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 21179998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 21279998SkrisOpenSSL command line tools. Applications using the OpenSSL library 21379998Skrisprovide their own configuration options to specify the entropy source, 21479998Skrisplease check out the documentation coming the with application. 21579998Skris 21668651SkrisFor Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested 21768651Skrisinstalling the SUNski package from Sun patch 105710-01 (Sparc) which 21868651Skrisadds a /dev/random device and make sure it gets used, usually through 21968651Skris$RANDFILE. There are probably similar patches for the other Solaris 220100936Snectarversions. An official statement from Sun with respect to /dev/random 221100936Snectarsupport can be found at 222100936Snectar http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski 223100936SnectarHowever, be warned that /dev/random is usually a blocking device, which 224100936Snectarmay have some effects on OpenSSL. 22559191Skris 22668651Skris 22779998Skris* Why do I get an "unable to write 'random state'" error message? 22879998Skris 22979998Skris 23079998SkrisSometimes the openssl command line utility does not abort with 23179998Skrisa "PRNG not seeded" error message, but complains that it is 23279998Skris"unable to write 'random state'". This message refers to the 23379998Skrisdefault seeding file (see previous answer). A possible reason 23479998Skrisis that no default filename is known because neither RANDFILE 23579998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 23679998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 23779998Skris 23879998Skris 23976866Skris* How do I create certificates or certificate requests? 24076866Skris 24176866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 24276866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 24376866Skrisout the manual pages for the individual utilities and the certificate 24476866Skrisextensions documentation (currently in doc/openssl.txt). 24576866Skris 24676866Skris 24776866Skris* Why can't I create certificate requests? 24876866Skris 24976866SkrisYou typically get the error: 25076866Skris 25176866Skris unable to find 'distinguished_name' in config 25276866Skris problems making Certificate Request 25376866Skris 25476866SkrisThis is because it can't find the configuration file. Check out the 25576866SkrisDIAGNOSTICS section of req(1) for more information. 25676866Skris 25776866Skris 25876866Skris* Why does <SSL program> fail with a certificate verify error? 25976866Skris 26076866SkrisThis problem is usually indicated by log messages saying something like 26176866Skris"unable to get local issuer certificate" or "self signed certificate". 26276866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 26376866Skristhis typically means that the CA certificate must be placed in a directory 26476866Skrisor file and the relevant program configured to read it. The OpenSSL program 26576866Skris'verify' behaves in a similar way and issues similar error messages: check 26676866Skristhe verify(1) program manual page for more information. 26776866Skris 26876866Skris 26976866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 27076866Skris 27176866SkrisThis is almost certainly because you are using an old "export grade" browser 27276866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 27376866Skrisciphers. 27476866Skris 27576866Skris 27676866Skris* How can I create DSA certificates? 27776866Skris 27876866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 27976866Skris 28076866Skris 28176866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 28276866Skris 28376866SkrisTypically you'll see a message saying there are no shared ciphers when 28476866Skristhe same setup works fine with an RSA certificate. There are two possible 28576866Skriscauses. The client may not support connections to DSA servers most web 28676866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 28776866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 28876866Skrishas not been supplied to the server. DH parameters can be created with the 28976866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 29076866Skrischeck the source to s_server in apps/s_server.c for an example. 29176866Skris 29276866Skris 29376866Skris* How can I remove the passphrase on a private key? 29476866Skris 29576866SkrisFirstly you should be really *really* sure you want to do this. Leaving 29676866Skrisa private key unencrypted is a major security risk. If you decide that 29776866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 29876866Skrisdsa(1) manual pages. 29976866Skris 30076866Skris 30176866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 30276866Skris 30376866SkrisWhat will typically happen is that when a server requests authentication 30476866Skrisit will either not include your certificate or tell you that you have 30576866Skrisno client certificates (Netscape) or present you with an empty list box 30676866Skris(MSIE). The reason for this is that when a server requests a client 30776866Skriscertificate it includes a list of CAs names which it will accept. Browsers 30876866Skriswill only let you select certificates from the list on the grounds that 30976866Skristhere is little point presenting a certificate which the server will 31076866Skrisreject. 31176866Skris 31276866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 31389837SkrisCA list". How you do this depends on the server software in uses. You can 31476866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 31576866Skris 31676866Skrisopenssl s_client -connect www.some.host:443 -prexit 31776866Skris 31876866SkrisIf your server only requests certificates on certain URLs then you may need 31976866Skristo manually issue an HTTP GET command to get the list when s_client connects: 32076866Skris 32176866SkrisGET /some/page/needing/a/certificate.html 32276866Skris 32376866SkrisIf your CA does not appear in the list then this confirms the problem. 32476866Skris 32576866Skris 32676866Skris* Why does my browser give a warning about a mismatched hostname? 32776866Skris 32876866SkrisBrowsers expect the server's hostname to match the value in the commonName 32976866Skris(CN) field of the certificate. If it does not then you get a warning. 33076866Skris 33176866Skris 33289837Skris* How do I install a CA certificate into a browser? 33389837Skris 33489837SkrisThe usual way is to send the DER encoded certificate to the browser as 33589837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 33689837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 33789837Skriscan import the certificate using the certificate import wizard. 33889837Skris 33989837SkrisYou can convert a certificate to DER form using the command: 34089837Skris 34189837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 34289837Skris 34389837SkrisOccasionally someone suggests using a command such as: 34489837Skris 34589837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 34689837Skris 34789837SkrisDO NOT DO THIS! This command will give away your CAs private key and 34889837Skrisreduces its security to zero: allowing anyone to forge certificates in 34989837Skriswhatever name they choose. 35089837Skris 35189837Skris 35276866Skris[BUILD] ======================================================================= 35376866Skris 35459191Skris* Why does the linker complain about undefined symbols? 35559191Skris 35659191SkrisMaybe the compilation was interrupted, and make doesn't notice that 35759191Skrissomething is missing. Run "make clean; make". 35859191Skris 35959191SkrisIf you used ./Configure instead of ./config, make sure that you 36059191Skrisselected the right target. File formats may differ slightly between 36159191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 36259191Skris 36359191SkrisIn case you get errors about the following symbols, use the config 36459191Skrisoption "no-asm", as described in INSTALL: 36559191Skris 36659191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 36759191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 36859191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 36959191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 37059191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 37159191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 37259191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 37359191Skris 37459191SkrisIf none of these helps, you may want to try using the current snapshot. 37559191SkrisIf the problem persists, please submit a bug report. 37659191Skris 37759191Skris 37876866Skris* Why does the OpenSSL test fail with "bc: command not found"? 37959191Skris 38076866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 38176866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 38259191Skris 38359191Skris 38476866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 38559191Skris 38676866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 38776866Skriswhen you run the test suite (using "make test"). The message returned is 38876866Skris"bc: 1 not implemented". 38959191Skris 39076866SkrisThe best way to deal with this is to find another implementation of bc 39176866Skrisand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 39276866Skrisfor download instructions) can be safely used, for example. 39376866Skris 39476866Skris 39589837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 39676866Skris 39789837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 39876866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 39976866Skrismemory to continue compilation.' As far as the tests have shown, this may be 40076866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 40176866Skristo build something, probably a table. The problem is clearly in the 40276866Skrisoptimization code, because if one eliminates optimization completely (-O0), 40376866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 40476866Skrismemory instead of 240MB or whatever one's limit is currently). 40576866Skris 40676866SkrisThere are three options to solve this problem: 40776866Skris 40876866Skris1. set your current data segment size soft limit higher. Experience shows 40976866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 41076866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 41176866Skriskbytes to set the limit to. 41276866Skris 41376866Skris2. If you have a hard limit that is lower than what you need and you can't 41476866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 41576866Skrislevel. This is however not a very nice thing to do for those who expect to 41676866Skrisget the best result from OpenSSL. A bit more complicated solution is the 41776866Skrisfollowing: 41876866Skris 41976866Skris----- snip:start ----- 42076866Skris make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 42176866Skris sed -e 's/ -O[0-9] / -O0 /'`" 42276866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 42376866Skris make 42476866Skris----- snip:end ----- 42576866Skris 42676866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 42776866Skrislevel chosen by the configuration process. When the above is done, do the 42876866Skristest and installation and you're set. 42976866Skris 43076866Skris 43176866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 43276866Skris 43376866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 43476866Skrisaway 'ar' and other development commands in directories that aren't in 43576866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 43676866Skrisquickest way to fix this is to do the following (it assumes you use sh 43776866Skrisor any sh-compatible shell): 43876866Skris 43976866Skris----- snip:start ----- 44076866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 44176866Skris----- snip:end ----- 44276866Skris 44376866Skrisand then redo the compilation. What you should really do is make sure 44476866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 44576866Skris'.profile' (again, assuming you use a sh-compatible shell). 44676866Skris 44776866Skris 44876866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 44976866Skris 45076866SkrisSometimes, you may get reports from VC++ command line (cl) that it 45176866Skriscan't find standard include files like stdio.h and other weirdnesses. 45276866SkrisOne possible cause is that the environment isn't correctly set up. 45376866SkrisTo solve that problem, one should run VCVARS32.BAT which is found in 45476866Skristhe 'bin' subdirectory of the VC++ installation directory (somewhere 45576866Skrisunder 'Program Files'). This needs to be done prior to running NMAKE, 45676866Skrisand the changes are only valid for the current DOS session. 45776866Skris 45876866Skris 459100936Snectar* What is special about OpenSSL on Redhat? 460100936Snectar 461100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 462100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 463100936Snectaris disabled in this version. The same may apply to other Linux distributions. 464100936SnectarUsers may therefore wish to install more or all of the features left out. 465100936Snectar 466100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 467100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 468100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 469100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 470100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 471100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 472100936Snectar/lib/libcrypto.so.2 respectively). 473100936Snectar 474100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 475100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 476100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 477100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 478100936Snectaropenssl on each distribution never change the package version, only the 479100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 480100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 481100936Snectarrelevant updates in packages up to and including 0.9.6b. 482100936Snectar 483100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 484100936Snectarversion of Red Hat Linux. 485100936Snectar 486100936SnectarFYI: Patent numbers and expiry dates of US patents: 487100936SnectarMDC-2: 4,908,861 13/03/2007 488100936SnectarIDEA: 5,214,703 25/05/2010 489100936SnectarRC5: 5,724,428 03/03/2015 490100936Snectar 491100936Snectar 492100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 493100936Snectar 494100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 495100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 496100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 497100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 498100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 499100936Snectargo around and has linked the programs "openssl" and the test programs 500100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 501100936Snectarlibraries you just built. 502100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 503100936Snectarsolutions. 504100936Snectar 50576866Skris[PROG] ======================================================================== 50676866Skris 50776866Skris* Is OpenSSL thread-safe? 50876866Skris 50976866SkrisYes (with limitations: an SSL connection may not concurrently be used 51076866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 51176866Skrisautomatically uses the multi-threaded versions of the standard 51276866Skrislibraries. If your platform is not one of these, consult the INSTALL 51376866Skrisfile. 51476866Skris 51576866SkrisMulti-threaded applications must provide two callback functions to 51676866SkrisOpenSSL. This is described in the threads(3) manpage. 51776866Skris 51876866Skris 51959191Skris* I've compiled a program under Windows and it crashes: why? 52059191Skris 52189837SkrisThis is usually because you've missed the comment in INSTALL.W32. 52289837SkrisYour application must link against the same version of the Win32 52389837SkrisC-Runtime against which your openssl libraries were linked. The 52489837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 52559191Skris 52689837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 52789837Skrismany cases, your new project most likely defaulted to "Debug 52889837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 52989837Skrisprogram will crash, typically on the first BIO related read or write 53089837Skrisoperation. 53159191Skris 53289837SkrisFor each of the six possible link stage configurations within Win32, 53389837Skrisyour application must link against the same by which OpenSSL was 53489837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 53589837Skrisby: 53689837Skris 53789837Skris1. Select Settings... from the Project Menu. 53889837Skris2. Select the C/C++ Tab. 53989837Skris3. Select "Code Generation from the "Category" drop down list box 54089837Skris4. Select the Appropriate library (see table below) from the "Use 54189837Skris run-time library" drop down list box. Perform this step for both 54289837Skris your debug and release versions of your application (look at the 54389837Skris top left of the settings panel to change between the two) 54489837Skris 54589837Skris Single Threaded /ML - MS VC++ often defaults to 54689837Skris this for the release 54789837Skris version of a new project. 54889837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 54989837Skris this for the debug version 55089837Skris of a new project. 55189837Skris Multithreaded /MT 55289837Skris Debug Multithreaded /MTd 55389837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 55489837Skris Debug Multithreaded DLL /MDd 55589837Skris 55689837SkrisNote that debug and release libraries are NOT interchangeable. If you 55789837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 55889837Skris 55989837Skris 56068651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 56168651Skris 56268651SkrisYou have two options. You can either use a memory BIO in conjunction 56368651Skriswith the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 56468651Skrisi2d_XXX(), d2i_XXX() functions directly. Since these are often the 56568651Skriscause of grief here are some code fragments using PKCS7 as an example: 56668651Skris 56768651Skrisunsigned char *buf, *p; 56868651Skrisint len; 56968651Skris 57068651Skrislen = i2d_PKCS7(p7, NULL); 57168651Skrisbuf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 57268651Skrisp = buf; 57368651Skrisi2d_PKCS7(p7, &p); 57468651Skris 57568651SkrisAt this point buf contains the len bytes of the DER encoding of 57668651Skrisp7. 57768651Skris 57868651SkrisThe opposite assumes we already have len bytes in buf: 57968651Skris 58068651Skrisunsigned char *p; 58168651Skrisp = buf; 58268651Skrisp7 = d2i_PKCS7(NULL, &p, len); 58368651Skris 58468651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 58568651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 58668651Skrisinformation. 58768651Skris 58868651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 58968651Skrisincrement the passed pointer so it is ready to read or write the next 59068651Skrisstructure. This is often a cause of problems: without the temporary 59168651Skrisvariable the buffer pointer is changed to point just after the data 59268651Skristhat has been read or written. This may well be uninitialized data 59368651Skrisand attempts to free the buffer will have unpredictable results 59468651Skrisbecause it no longer points to the same address. 59568651Skris 59668651Skris 59768651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 59868651Skris 59968651SkrisThis usually happens when you try compiling something using the PKCS#12 60068651Skrismacros with a C++ compiler. There is hardly ever any need to use the 60168651SkrisPKCS#12 macros in a program, it is much easier to parse and create 60268651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 60368651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 60468651Skris'pkcs12' application has to use the macros because it prints out 60568651Skrisdebugging information. 60668651Skris 60768651Skris 60859191Skris* I've called <some function> and it fails, why? 60959191Skris 61068651SkrisBefore submitting a report or asking in one of the mailing lists, you 61168651Skrisshould try to determine the cause. In particular, you should call 61259191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 61368651Skrisand see if the message helps. Note that the problem may occur earlier 61468651Skristhan you think -- you should check for errors after every call where 61568651Skrisit is possible, otherwise the actual problem may be hidden because 61668651Skrissome OpenSSL functions clear the error state. 61759191Skris 61859191Skris 61959191Skris* I just get a load of numbers for the error output, what do they mean? 62059191Skris 62159191SkrisThe actual format is described in the ERR_print_errors() manual page. 62259191SkrisYou should call the function ERR_load_crypto_strings() before hand and 62359191Skristhe message will be output in text form. If you can't do this (for example 62459191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 62559191Skriscode itself (the hex digits after the second colon). 62659191Skris 62759191Skris 62859191Skris* Why do I get errors about unknown algorithms? 62959191Skris 63059191SkrisThis can happen under several circumstances such as reading in an 63159191Skrisencrypted private key or attempting to decrypt a PKCS#12 file. The cause 63259191Skrisis forgetting to load OpenSSL's table of algorithms with 63359191SkrisOpenSSL_add_all_algorithms(). See the manual page for more information. 63459191Skris 63559191Skris 63659191Skris* Why can't the OpenSSH configure script detect OpenSSL? 63759191Skris 63889837SkrisSeveral reasons for problems with the automatic detection exist. 63989837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 64089837SkrisSometimes the distribution has installed an older version in the system 64189837Skrislocations that is detected instead of a new one installed. The OpenSSL 64289837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 64389837SkrisPermissions might be wrong. 64459191Skris 64589837SkrisThe general answer is to check the config.log file generated when running 64689837Skristhe OpenSSH configure script. It should contain the detailed information 64789837Skrison why the OpenSSL library was not detected or considered incompatible. 64868651Skris 64976866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 65068651Skris 65176866SkrisYes; make sure to read the SSL_get_error(3) manual page! 65268651Skris 65376866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 65476866Skristhe underlying transport or that SSL_write() will just write to it -- 65576866Skrisit is also possible that SSL_write() cannot do any useful work until 65676866Skristhere is data to read, or that SSL_read() cannot do anything until it 65776866Skrisis possible to send data. One reason for this is that the peer may 65876866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 65976866Skrisrequiring a bi-directional message exchange; both SSL_read() and 66076866SkrisSSL_write() will try to continue any pending handshake. 66168651Skris 66268651Skris 66379998Skris* Why doesn't my server application receive a client certificate? 66479998Skris 66579998SkrisDue to the TLS protocol definition, a client will only send a certificate, 66689837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 66779998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 66879998Skris 66979998Skris 67076866Skris=============================================================================== 67168651Skris 672