FAQ revision 120631
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? 12109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 1376866Skris 1476866Skris[LEGAL] Legal questions 1576866Skris 1659191Skris* Do I need patent licenses to use OpenSSL? 1776866Skris* Can I use OpenSSL with GPL software? 1876866Skris 1976866Skris[USER] Questions on using the OpenSSL applications 2076866Skris 2159191Skris* Why do I get a "PRNG not seeded" error message? 2279998Skris* Why do I get an "unable to write 'random state'" error message? 2359191Skris* How do I create certificates or certificate requests? 2459191Skris* Why can't I create certificate requests? 2559191Skris* Why does <SSL program> fail with a certificate verify error? 2668651Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 2759191Skris* How can I create DSA certificates? 2859191Skris* Why can't I make an SSL connection using a DSA certificate? 2968651Skris* How can I remove the passphrase on a private key? 3076866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 3176866Skris* Why does my browser give a warning about a mismatched hostname? 3289837Skris* How do I install a CA certificate into a browser? 33109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 3476866Skris 3576866Skris[BUILD] Questions about building and testing OpenSSL 3676866Skris 3776866Skris* Why does the linker complain about undefined symbols? 3868651Skris* Why does the OpenSSL test fail with "bc: command not found"? 3968651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 40109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 4189837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 4268651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 4376866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 44100936Snectar* What is special about OpenSSL on Redhat? 45109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 46100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 47109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 48109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 4959191Skris 5076866Skris[PROG] Questions about programming with OpenSSL 5159191Skris 5276866Skris* Is OpenSSL thread-safe? 5376866Skris* I've compiled a program under Windows and it crashes: why? 5476866Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 5576866Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 5676866Skris* I've called <some function> and it fails, why? 5776866Skris* I just get a load of numbers for the error output, what do they mean? 5876866Skris* Why do I get errors about unknown algorithms? 5976866Skris* Why can't the OpenSSH configure script detect OpenSSL? 6076866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 6179998Skris* Why doesn't my server application receive a client certificate? 62109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 6376866Skris 6476866Skris=============================================================================== 6576866Skris 6676866Skris[MISC] ======================================================================== 6776866Skris 6859191Skris* Which is the current version of OpenSSL? 6959191Skris 7059191SkrisThe current version is available from <URL: http://www.openssl.org>. 71120631SnectarOpenSSL 0.9.7c was released on September 30, 2003. 7259191Skris 7359191SkrisIn addition to the current stable release, you can also access daily 7459191Skrissnapshots of the OpenSSL development version at <URL: 7559191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 7659191Skris 7759191Skris 7859191Skris* Where is the documentation? 7959191Skris 8059191SkrisOpenSSL is a library that provides cryptographic functionality to 8159191Skrisapplications such as secure web servers. Be sure to read the 8259191Skrisdocumentation of the application you want to use. The INSTALL file 8359191Skrisexplains how to install this library. 8459191Skris 8559191SkrisOpenSSL includes a command line utility that can be used to perform a 8659191Skrisvariety of cryptographic functions. It is described in the openssl(1) 8759191Skrismanpage. Documentation for developers is currently being written. A 8859191Skrisfew manual pages already are available; overviews over libcrypto and 8959191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 9059191Skris 9159191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 9259191Skrisdifferent directory if you specified one as described in INSTALL). 9359191SkrisIn addition, you can read the most current versions at 9459191Skris<URL: http://www.openssl.org/docs/>. 9559191Skris 9659191SkrisFor information on parts of libcrypto that are not yet documented, you 9759191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 9859191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 9959191Skrisof this still applies to OpenSSL. 10059191Skris 10159191SkrisThere is some documentation about certificate extensions and PKCS#12 10259191Skrisin doc/openssl.txt 10359191Skris 10459191SkrisThe original SSLeay documentation is included in OpenSSL as 10559191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 10659191Skrishelp, but please note that it reflects the obsolete version SSLeay 10759191Skris0.6.6. 10859191Skris 10959191Skris 11059191Skris* How can I contact the OpenSSL developers? 11159191Skris 11259191SkrisThe README file describes how to submit bug reports and patches to 11359191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 11459191Skris<URL: http://www.openssl.org>. 11559191Skris 11659191Skris 11776866Skris* Where can I get a compiled version of OpenSSL? 11876866Skris 11976866SkrisSome applications that use OpenSSL are distributed in binary form. 12076866SkrisWhen using such an application, you don't need to install OpenSSL 12176866Skrisyourself; the application will include the required parts (e.g. DLLs). 12276866Skris 12376866SkrisIf you want to install OpenSSL on a Windows system and you don't have 12476866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 12576866Skrison how to obtain and install the free GNU C compiler. 12676866Skris 12776866SkrisA number of Linux and *BSD distributions include OpenSSL. 12876866Skris 12976866Skris 13076866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 13176866Skris 13276866Skrisautoconf will probably be used in future OpenSSL versions. If it was 13376866Skrisless Unix-centric, it might have been used much earlier. 13476866Skris 13589837Skris* What is an 'engine' version? 13676866Skris 13789837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 13889837Skrishardware. This was realized in a special release '0.9.6-engine'. With 13989837Skrisversion 0.9.7 (not yet released) the changes were merged into the main 14089837Skrisdevelopment line, so that the special release is no longer necessary. 14189837Skris 142109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 143109998Smarkm 144109998SmarkmWe provide MD5 digests and ASC signatures of each tarball. 145109998SmarkmUse MD5 to check that a tarball from a mirror site is identical: 146109998Smarkm 147109998Smarkm md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 148109998Smarkm 149109998SmarkmYou can check authenticity using pgp or gpg. You need the OpenSSL team 150109998Smarkmmember public key used to sign it (download it from a key server). Then 151109998Smarkmjust do: 152109998Smarkm 153109998Smarkm pgp TARBALL.asc 154109998Smarkm 15576866Skris[LEGAL] ======================================================================= 15676866Skris 15759191Skris* Do I need patent licenses to use OpenSSL? 15859191Skris 15959191SkrisThe patents section of the README file lists patents that may apply to 16059191Skrisyou if you want to use OpenSSL. For information on intellectual 16159191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 16259191Skrisoffer legal advice. 16359191Skris 16459191SkrisYou can configure OpenSSL so as not to use RC5 and IDEA by using 16559191Skris ./config no-rc5 no-idea 16659191Skris 16759191Skris 16876866Skris* Can I use OpenSSL with GPL software? 16959191Skris 17076866SkrisOn many systems including the major Linux and BSD distributions, yes (the 17176866SkrisGPL does not place restrictions on using libraries that are part of the 17276866Skrisnormal operating system distribution). 17359191Skris 17476866SkrisOn other systems, the situation is less clear. Some GPL software copyright 17576866Skrisholders claim that you infringe on their rights if you use OpenSSL with 17676866Skristheir software on operating systems that don't normally include OpenSSL. 17759191Skris 17876866SkrisIf you develop open source software that uses OpenSSL, you may find it 17989837Skrisuseful to choose an other license than the GPL, or state explicitly that 18076866Skris"This program is released under the GPL with the additional exemption that 18176866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 18276866SkrisGPL software developed by others, you may want to ask the copyright holder 18376866Skrisfor permission to use their software with OpenSSL. 18459191Skris 18576866Skris 18676866Skris[USER] ======================================================================== 18776866Skris 18859191Skris* Why do I get a "PRNG not seeded" error message? 18959191Skris 19059191SkrisCryptographic software needs a source of unpredictable data to work 19159191Skriscorrectly. Many open source operating systems provide a "randomness 192111147Snectardevice" (/dev/urandom or /dev/random) that serves this purpose. 193111147SnectarAll OpenSSL versions try to use /dev/urandom by default; starting with 194111147Snectarversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 195111147Snectaravailable. 19659191Skris 197111147SnectarOn other systems, applications have to call the RAND_add() or 198111147SnectarRAND_seed() function with appropriate data before generating keys or 199111147Snectarperforming public key encryption. (These functions initialize the 200111147Snectarpseudo-random number generator, PRNG.) Some broken applications do 201111147Snectarnot do this. As of version 0.9.5, the OpenSSL functions that need 202111147Snectarrandomness report an error if the random number generator has not been 203111147Snectarseeded with at least 128 bits of randomness. If this error occurs and 204111147Snectaris not discussed in the documentation of the application you are 205111147Snectarusing, please contact the author of that application; it is likely 206111147Snectarthat it never worked correctly. OpenSSL 0.9.5 and later make the 207111147Snectarerror visible by refusing to perform potentially insecure encryption. 20859191Skris 209111147SnectarIf you are using Solaris 8, you can add /dev/urandom and /dev/random 210111147Snectardevices by installing patch 112438 (Sparc) or 112439 (x86), which are 211111147Snectaravailable via the Patchfinder at <URL: http://sunsolve.sun.com> 212111147Snectar(Solaris 9 includes these devices by default). For /dev/random support 213111147Snectarfor earlier Solaris versions, see Sun's statement at 214111147Snectar<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 215111147Snectar(the SUNWski package is available in patch 105710). 216111147Snectar 21779998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 21879998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 21979998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 22079998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 22179998Skris/etc/entropy. 22259191Skris 22379998SkrisMost components of the openssl command line utility automatically try 22479998Skristo seed the random number generator from a file. The name of the 22579998Skrisdefault seeding file is determined as follows: If environment variable 22679998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 22779998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 22879998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 22979998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 23079998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 23189837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 23279998SkrisWindows systems if the environment variable has not been set. 23359191Skris 23479998SkrisIf the default seeding file does not exist or is too short, the "PRNG 23579998Skrisnot seeded" error message may occur. 23659191Skris 23779998SkrisThe openssl command line utility will write back a new state to the 23879998Skrisdefault seeding file (and create this file if necessary) unless 23979998Skristhere was no sufficient seeding. 24079998Skris 24179998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 24279998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 24379998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 24479998SkrisOpenSSL command line tools. Applications using the OpenSSL library 24579998Skrisprovide their own configuration options to specify the entropy source, 24679998Skrisplease check out the documentation coming the with application. 24779998Skris 24859191Skris 24979998Skris* Why do I get an "unable to write 'random state'" error message? 25079998Skris 25179998Skris 25279998SkrisSometimes the openssl command line utility does not abort with 25379998Skrisa "PRNG not seeded" error message, but complains that it is 25479998Skris"unable to write 'random state'". This message refers to the 25579998Skrisdefault seeding file (see previous answer). A possible reason 25679998Skrisis that no default filename is known because neither RANDFILE 25779998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 25879998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 25979998Skris 26079998Skris 26176866Skris* How do I create certificates or certificate requests? 26276866Skris 26376866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 26476866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 26576866Skrisout the manual pages for the individual utilities and the certificate 26676866Skrisextensions documentation (currently in doc/openssl.txt). 26776866Skris 26876866Skris 26976866Skris* Why can't I create certificate requests? 27076866Skris 27176866SkrisYou typically get the error: 27276866Skris 27376866Skris unable to find 'distinguished_name' in config 27476866Skris problems making Certificate Request 27576866Skris 27676866SkrisThis is because it can't find the configuration file. Check out the 27776866SkrisDIAGNOSTICS section of req(1) for more information. 27876866Skris 27976866Skris 28076866Skris* Why does <SSL program> fail with a certificate verify error? 28176866Skris 28276866SkrisThis problem is usually indicated by log messages saying something like 28376866Skris"unable to get local issuer certificate" or "self signed certificate". 28476866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 28576866Skristhis typically means that the CA certificate must be placed in a directory 28676866Skrisor file and the relevant program configured to read it. The OpenSSL program 28776866Skris'verify' behaves in a similar way and issues similar error messages: check 28876866Skristhe verify(1) program manual page for more information. 28976866Skris 29076866Skris 29176866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 29276866Skris 29376866SkrisThis is almost certainly because you are using an old "export grade" browser 29476866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 29576866Skrisciphers. 29676866Skris 29776866Skris 29876866Skris* How can I create DSA certificates? 29976866Skris 30076866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 30176866Skris 30276866Skris 30376866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 30476866Skris 30576866SkrisTypically you'll see a message saying there are no shared ciphers when 30676866Skristhe same setup works fine with an RSA certificate. There are two possible 30776866Skriscauses. The client may not support connections to DSA servers most web 30876866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 30976866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 31076866Skrishas not been supplied to the server. DH parameters can be created with the 31176866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 31276866Skrischeck the source to s_server in apps/s_server.c for an example. 31376866Skris 31476866Skris 31576866Skris* How can I remove the passphrase on a private key? 31676866Skris 31776866SkrisFirstly you should be really *really* sure you want to do this. Leaving 31876866Skrisa private key unencrypted is a major security risk. If you decide that 31976866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 32076866Skrisdsa(1) manual pages. 32176866Skris 32276866Skris 32376866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 32476866Skris 32576866SkrisWhat will typically happen is that when a server requests authentication 32676866Skrisit will either not include your certificate or tell you that you have 32776866Skrisno client certificates (Netscape) or present you with an empty list box 32876866Skris(MSIE). The reason for this is that when a server requests a client 32976866Skriscertificate it includes a list of CAs names which it will accept. Browsers 33076866Skriswill only let you select certificates from the list on the grounds that 33176866Skristhere is little point presenting a certificate which the server will 33276866Skrisreject. 33376866Skris 33476866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 33589837SkrisCA list". How you do this depends on the server software in uses. You can 33676866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 33776866Skris 33876866Skrisopenssl s_client -connect www.some.host:443 -prexit 33976866Skris 34076866SkrisIf your server only requests certificates on certain URLs then you may need 34176866Skristo manually issue an HTTP GET command to get the list when s_client connects: 34276866Skris 34376866SkrisGET /some/page/needing/a/certificate.html 34476866Skris 34576866SkrisIf your CA does not appear in the list then this confirms the problem. 34676866Skris 34776866Skris 34876866Skris* Why does my browser give a warning about a mismatched hostname? 34976866Skris 35076866SkrisBrowsers expect the server's hostname to match the value in the commonName 35176866Skris(CN) field of the certificate. If it does not then you get a warning. 35276866Skris 35376866Skris 35489837Skris* How do I install a CA certificate into a browser? 35589837Skris 35689837SkrisThe usual way is to send the DER encoded certificate to the browser as 35789837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 35889837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 35989837Skriscan import the certificate using the certificate import wizard. 36089837Skris 36189837SkrisYou can convert a certificate to DER form using the command: 36289837Skris 36389837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 36489837Skris 36589837SkrisOccasionally someone suggests using a command such as: 36689837Skris 36789837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 36889837Skris 36989837SkrisDO NOT DO THIS! This command will give away your CAs private key and 37089837Skrisreduces its security to zero: allowing anyone to forge certificates in 37189837Skriswhatever name they choose. 37289837Skris 373109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 37489837Skris 375109998SmarkmThe ways to print out the oneline format of the DN (Distinguished Name) have 376109998Smarkmbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 377109998Smarkminterface, the "-nameopt" option could be introduded. See the manual 378109998Smarkmpage of the "openssl x509" commandline tool for details. The old behaviour 379109998Smarkmhas however been left as default for the sake of compatibility. 380109998Smarkm 38176866Skris[BUILD] ======================================================================= 38276866Skris 38359191Skris* Why does the linker complain about undefined symbols? 38459191Skris 38559191SkrisMaybe the compilation was interrupted, and make doesn't notice that 38659191Skrissomething is missing. Run "make clean; make". 38759191Skris 38859191SkrisIf you used ./Configure instead of ./config, make sure that you 38959191Skrisselected the right target. File formats may differ slightly between 39059191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 39159191Skris 39259191SkrisIn case you get errors about the following symbols, use the config 39359191Skrisoption "no-asm", as described in INSTALL: 39459191Skris 39559191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 39659191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 39759191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 39859191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 39959191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 40059191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 40159191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 40259191Skris 40359191SkrisIf none of these helps, you may want to try using the current snapshot. 40459191SkrisIf the problem persists, please submit a bug report. 40559191Skris 40659191Skris 40776866Skris* Why does the OpenSSL test fail with "bc: command not found"? 40859191Skris 40976866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 41076866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 41159191Skris 41259191Skris 41376866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 41459191Skris 41576866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 41676866Skriswhen you run the test suite (using "make test"). The message returned is 41776866Skris"bc: 1 not implemented". 41859191Skris 41976866SkrisThe best way to deal with this is to find another implementation of bc 42076866Skrisand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 42176866Skrisfor download instructions) can be safely used, for example. 42276866Skris 42376866Skris 424109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 425109998Smarkm 426109998SmarkmOn some DG/ux versions, bc seems to have a too small stack for calculations 427109998Smarkmthat the OpenSSL bntest throws at it. This gets triggered when you run the 428109998Smarkmtest suite (using "make test"). The message returned is "bc: stack empty". 429109998Smarkm 430109998SmarkmThe best way to deal with this is to find another implementation of bc 431109998Smarkmand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 432109998Smarkmfor download instructions) can be safely used, for example. 433109998Smarkm 434109998Smarkm 43589837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 43676866Skris 43789837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 43876866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 43976866Skrismemory to continue compilation.' As far as the tests have shown, this may be 44076866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 44176866Skristo build something, probably a table. The problem is clearly in the 44276866Skrisoptimization code, because if one eliminates optimization completely (-O0), 44376866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 44476866Skrismemory instead of 240MB or whatever one's limit is currently). 44576866Skris 44676866SkrisThere are three options to solve this problem: 44776866Skris 44876866Skris1. set your current data segment size soft limit higher. Experience shows 44976866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 45076866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 45176866Skriskbytes to set the limit to. 45276866Skris 45376866Skris2. If you have a hard limit that is lower than what you need and you can't 45476866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 45576866Skrislevel. This is however not a very nice thing to do for those who expect to 45676866Skrisget the best result from OpenSSL. A bit more complicated solution is the 45776866Skrisfollowing: 45876866Skris 45976866Skris----- snip:start ----- 46076866Skris make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 46176866Skris sed -e 's/ -O[0-9] / -O0 /'`" 46276866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 46376866Skris make 46476866Skris----- snip:end ----- 46576866Skris 46676866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 46776866Skrislevel chosen by the configuration process. When the above is done, do the 46876866Skristest and installation and you're set. 46976866Skris 47076866Skris 47176866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 47276866Skris 47376866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 47476866Skrisaway 'ar' and other development commands in directories that aren't in 47576866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 47676866Skrisquickest way to fix this is to do the following (it assumes you use sh 47776866Skrisor any sh-compatible shell): 47876866Skris 47976866Skris----- snip:start ----- 48076866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 48176866Skris----- snip:end ----- 48276866Skris 48376866Skrisand then redo the compilation. What you should really do is make sure 48476866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 48576866Skris'.profile' (again, assuming you use a sh-compatible shell). 48676866Skris 48776866Skris 48876866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 48976866Skris 49076866SkrisSometimes, you may get reports from VC++ command line (cl) that it 49176866Skriscan't find standard include files like stdio.h and other weirdnesses. 49276866SkrisOne possible cause is that the environment isn't correctly set up. 493111147SnectarTo solve that problem for VC++ versions up to 6, one should run 494111147SnectarVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 495111147Snectarinstallation directory (somewhere under 'Program Files'). For VC++ 496111147Snectarversion 7 (and up?), which is also called VS.NET, the file is called 497111147SnectarVSVARS32.BAT instead. 498111147SnectarThis needs to be done prior to running NMAKE, and the changes are only 499111147Snectarvalid for the current DOS session. 50076866Skris 50176866Skris 502100936Snectar* What is special about OpenSSL on Redhat? 503100936Snectar 504100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 505100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 506100936Snectaris disabled in this version. The same may apply to other Linux distributions. 507100936SnectarUsers may therefore wish to install more or all of the features left out. 508100936Snectar 509100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 510100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 511100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 512100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 513100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 514100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 515100936Snectar/lib/libcrypto.so.2 respectively). 516100936Snectar 517100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 518100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 519100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 520100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 521100936Snectaropenssl on each distribution never change the package version, only the 522100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 523100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 524100936Snectarrelevant updates in packages up to and including 0.9.6b. 525100936Snectar 526100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 527100936Snectarversion of Red Hat Linux. 528100936Snectar 529100936SnectarFYI: Patent numbers and expiry dates of US patents: 530100936SnectarMDC-2: 4,908,861 13/03/2007 531100936SnectarIDEA: 5,214,703 25/05/2010 532100936SnectarRC5: 5,724,428 03/03/2015 533100936Snectar 534100936Snectar 535109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 536109998Smarkm 537109998SmarkmIf the failure happens when trying to build the "openssl" binary, with 538109998Smarkma large number of undefined symbols, it's very probable that you have 539109998SmarkmOpenSSL 0.9.6b delivered with the operating system (you can find out by 540109998Smarkmrunning '/usr/bin/openssl version') and that you were trying to build 541109998SmarkmOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 542109998SmarkmMacOS X has a misfeature that's quite difficult to go around. 543109998SmarkmLook in the file PROBLEMS for a more detailed explanation and for possible 544109998Smarkmsolutions. 545109998Smarkm 546109998Smarkm 547100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 548100936Snectar 549100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 550100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 551100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 552100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 553100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 554100936Snectargo around and has linked the programs "openssl" and the test programs 555100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 556100936Snectarlibraries you just built. 557100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 558100936Snectarsolutions. 559100936Snectar 560109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 561109998Smarkm 562109998SmarkmFailure in BN_sqr test is most likely caused by a failure to configure the 563109998Smarkmtoolkit for current platform or lack of support for the platform in question. 564109998SmarkmRun './config -t' and './apps/openssl version -p'. Do these platform 565109998Smarkmidentifiers match? If they don't, then you most likely failed to run 566109998Smarkm./config and you're hereby advised to do so before filing a bug report. 567109998SmarkmIf ./config itself fails to run, then it's most likely problem with your 568109998Smarkmlocal environment and you should turn to your system administrator (or 569109998Smarkmsimilar). If identifiers match (and/or no alternative identifier is 570109998Smarkmsuggested by ./config script), then the platform is unsupported. There might 571109998Smarkmor might not be a workaround. Most notably on SPARC64 platforms with GNU 572109998SmarkmC compiler you should be able to produce a working build by running 573109998Smarkm'./config -m32'. I understand that -m32 might not be what you want/need, 574109998Smarkmbut the build should be operational. For further details turn to 575109998Smarkm<openssl-dev@openssl.org>. 576109998Smarkm 577109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 578109998Smarkm 579109998SmarkmAs of 0.9.7 assembler routines were overhauled for position independence 580109998Smarkmof the machine code, which is essential for shared library support. For 581109998Smarkmsome reason OpenBSD is equipped with an out-of-date GNU assembler which 582109998Smarkmfinds the new code offensive. To work around the problem, configure with 583111147Snectarno-asm (and sacrifice a great deal of performance) or patch your assembler 584111147Snectaraccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 585109998SmarkmFor your convenience a pre-compiled replacement binary is provided at 586111147Snectar<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 587111147SnectarReportedly elder *BSD a.out platforms also suffer from this problem and 588111147Snectarremedy should be same. Provided binary is statically linked and should be 589111147Snectarworking across wider range of *BSD branches, not just OpenBSD. 590109998Smarkm 59176866Skris[PROG] ======================================================================== 59276866Skris 59376866Skris* Is OpenSSL thread-safe? 59476866Skris 59576866SkrisYes (with limitations: an SSL connection may not concurrently be used 59676866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 59776866Skrisautomatically uses the multi-threaded versions of the standard 59876866Skrislibraries. If your platform is not one of these, consult the INSTALL 59976866Skrisfile. 60076866Skris 60176866SkrisMulti-threaded applications must provide two callback functions to 60276866SkrisOpenSSL. This is described in the threads(3) manpage. 60376866Skris 60476866Skris 60559191Skris* I've compiled a program under Windows and it crashes: why? 60659191Skris 60789837SkrisThis is usually because you've missed the comment in INSTALL.W32. 60889837SkrisYour application must link against the same version of the Win32 60989837SkrisC-Runtime against which your openssl libraries were linked. The 61089837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 61159191Skris 61289837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 61389837Skrismany cases, your new project most likely defaulted to "Debug 61489837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 61589837Skrisprogram will crash, typically on the first BIO related read or write 61689837Skrisoperation. 61759191Skris 61889837SkrisFor each of the six possible link stage configurations within Win32, 61989837Skrisyour application must link against the same by which OpenSSL was 62089837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 62189837Skrisby: 62289837Skris 62389837Skris1. Select Settings... from the Project Menu. 62489837Skris2. Select the C/C++ Tab. 62589837Skris3. Select "Code Generation from the "Category" drop down list box 62689837Skris4. Select the Appropriate library (see table below) from the "Use 62789837Skris run-time library" drop down list box. Perform this step for both 62889837Skris your debug and release versions of your application (look at the 62989837Skris top left of the settings panel to change between the two) 63089837Skris 63189837Skris Single Threaded /ML - MS VC++ often defaults to 63289837Skris this for the release 63389837Skris version of a new project. 63489837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 63589837Skris this for the debug version 63689837Skris of a new project. 63789837Skris Multithreaded /MT 63889837Skris Debug Multithreaded /MTd 63989837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 64089837Skris Debug Multithreaded DLL /MDd 64189837Skris 64289837SkrisNote that debug and release libraries are NOT interchangeable. If you 64389837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 64489837Skris 64589837Skris 64668651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 64768651Skris 64868651SkrisYou have two options. You can either use a memory BIO in conjunction 64968651Skriswith the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 65068651Skrisi2d_XXX(), d2i_XXX() functions directly. Since these are often the 65168651Skriscause of grief here are some code fragments using PKCS7 as an example: 65268651Skris 65368651Skrisunsigned char *buf, *p; 65468651Skrisint len; 65568651Skris 65668651Skrislen = i2d_PKCS7(p7, NULL); 65768651Skrisbuf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 65868651Skrisp = buf; 65968651Skrisi2d_PKCS7(p7, &p); 66068651Skris 66168651SkrisAt this point buf contains the len bytes of the DER encoding of 66268651Skrisp7. 66368651Skris 66468651SkrisThe opposite assumes we already have len bytes in buf: 66568651Skris 66668651Skrisunsigned char *p; 66768651Skrisp = buf; 66868651Skrisp7 = d2i_PKCS7(NULL, &p, len); 66968651Skris 67068651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 67168651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 67268651Skrisinformation. 67368651Skris 67468651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 67568651Skrisincrement the passed pointer so it is ready to read or write the next 67668651Skrisstructure. This is often a cause of problems: without the temporary 67768651Skrisvariable the buffer pointer is changed to point just after the data 67868651Skristhat has been read or written. This may well be uninitialized data 67968651Skrisand attempts to free the buffer will have unpredictable results 68068651Skrisbecause it no longer points to the same address. 68168651Skris 68268651Skris 68368651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 68468651Skris 68568651SkrisThis usually happens when you try compiling something using the PKCS#12 68668651Skrismacros with a C++ compiler. There is hardly ever any need to use the 68768651SkrisPKCS#12 macros in a program, it is much easier to parse and create 68868651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 68968651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 69068651Skris'pkcs12' application has to use the macros because it prints out 69168651Skrisdebugging information. 69268651Skris 69368651Skris 69459191Skris* I've called <some function> and it fails, why? 69559191Skris 69668651SkrisBefore submitting a report or asking in one of the mailing lists, you 69768651Skrisshould try to determine the cause. In particular, you should call 69859191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 69968651Skrisand see if the message helps. Note that the problem may occur earlier 70068651Skristhan you think -- you should check for errors after every call where 70168651Skrisit is possible, otherwise the actual problem may be hidden because 70268651Skrissome OpenSSL functions clear the error state. 70359191Skris 70459191Skris 70559191Skris* I just get a load of numbers for the error output, what do they mean? 70659191Skris 70759191SkrisThe actual format is described in the ERR_print_errors() manual page. 70859191SkrisYou should call the function ERR_load_crypto_strings() before hand and 70959191Skristhe message will be output in text form. If you can't do this (for example 71059191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 71159191Skriscode itself (the hex digits after the second colon). 71259191Skris 71359191Skris 71459191Skris* Why do I get errors about unknown algorithms? 71559191Skris 71659191SkrisThis can happen under several circumstances such as reading in an 71759191Skrisencrypted private key or attempting to decrypt a PKCS#12 file. The cause 71859191Skrisis forgetting to load OpenSSL's table of algorithms with 71959191SkrisOpenSSL_add_all_algorithms(). See the manual page for more information. 72059191Skris 72159191Skris 72259191Skris* Why can't the OpenSSH configure script detect OpenSSL? 72359191Skris 72489837SkrisSeveral reasons for problems with the automatic detection exist. 72589837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 72689837SkrisSometimes the distribution has installed an older version in the system 72789837Skrislocations that is detected instead of a new one installed. The OpenSSL 72889837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 72989837SkrisPermissions might be wrong. 73059191Skris 73189837SkrisThe general answer is to check the config.log file generated when running 73289837Skristhe OpenSSH configure script. It should contain the detailed information 73389837Skrison why the OpenSSL library was not detected or considered incompatible. 73468651Skris 735120631Snectar 73676866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 73768651Skris 73876866SkrisYes; make sure to read the SSL_get_error(3) manual page! 73968651Skris 74076866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 74176866Skristhe underlying transport or that SSL_write() will just write to it -- 74276866Skrisit is also possible that SSL_write() cannot do any useful work until 74376866Skristhere is data to read, or that SSL_read() cannot do anything until it 74476866Skrisis possible to send data. One reason for this is that the peer may 74576866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 74676866Skrisrequiring a bi-directional message exchange; both SSL_read() and 74776866SkrisSSL_write() will try to continue any pending handshake. 74868651Skris 74968651Skris 75079998Skris* Why doesn't my server application receive a client certificate? 75179998Skris 75279998SkrisDue to the TLS protocol definition, a client will only send a certificate, 75389837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 75479998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 75579998Skris 75679998Skris 757109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 758109998Smarkm 759109998SmarkmFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 760109998Smarkmversions, uniqueIdentifier was incorrectly used for X.509 certificates. 761109998SmarkmThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 762109998SmarkmChange your code to use the new name when compiling against OpenSSL 0.9.7. 763109998Smarkm 764109998Smarkm 76576866Skris=============================================================================== 76668651Skris 767