FAQ revision 215697
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? 34160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 35194206Ssimon* Why does OpenSSL set the authority key identifier extension incorrectly? 36194206Ssimon* How can I set up a bundle of commercial root CA certificates? 3776866Skris 3876866Skris[BUILD] Questions about building and testing OpenSSL 3976866Skris 4076866Skris* Why does the linker complain about undefined symbols? 4168651Skris* Why does the OpenSSL test fail with "bc: command not found"? 4268651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 43109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 4489837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 4568651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 4676866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 47100936Snectar* What is special about OpenSSL on Redhat? 48109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 49100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 50109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 51109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 52160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 53160814Ssimon* Why does compiler fail to compile sha512.c? 54160814Ssimon* Test suite still fails, what to do? 5559191Skris 5676866Skris[PROG] Questions about programming with OpenSSL 5759191Skris 5876866Skris* Is OpenSSL thread-safe? 5976866Skris* I've compiled a program under Windows and it crashes: why? 6076866Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 61142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 6276866Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 6376866Skris* I've called <some function> and it fails, why? 6476866Skris* I just get a load of numbers for the error output, what do they mean? 6576866Skris* Why do I get errors about unknown algorithms? 6676866Skris* Why can't the OpenSSH configure script detect OpenSSL? 6776866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 6879998Skris* Why doesn't my server application receive a client certificate? 69109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 70142425Snectar* I think I've detected a memory leak, is this a bug? 71194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 72194206Ssimon* Why doesn't a memory BIO work when a file does? 73215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 7476866Skris 7576866Skris=============================================================================== 7676866Skris 7776866Skris[MISC] ======================================================================== 7876866Skris 7959191Skris* Which is the current version of OpenSSL? 8059191Skris 8159191SkrisThe current version is available from <URL: http://www.openssl.org>. 82215697SsimonOpenSSL 1.0.0b was released on Nov 16th, 2010. 8359191Skris 8459191SkrisIn addition to the current stable release, you can also access daily 8559191Skrissnapshots of the OpenSSL development version at <URL: 8659191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 8759191Skris 8859191Skris 8959191Skris* Where is the documentation? 9059191Skris 9159191SkrisOpenSSL is a library that provides cryptographic functionality to 9259191Skrisapplications such as secure web servers. Be sure to read the 9359191Skrisdocumentation of the application you want to use. The INSTALL file 9459191Skrisexplains how to install this library. 9559191Skris 9659191SkrisOpenSSL includes a command line utility that can be used to perform a 9759191Skrisvariety of cryptographic functions. It is described in the openssl(1) 98215697Ssimonmanpage. Documentation for developers is currently being written. Many 99215697Ssimonmanual pages are available; overviews over libcrypto and 10059191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 10159191Skris 10259191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 10359191Skrisdifferent directory if you specified one as described in INSTALL). 10459191SkrisIn addition, you can read the most current versions at 105215697Ssimon<URL: http://www.openssl.org/docs/>. Note that the online documents refer 106215697Ssimonto the very latest development versions of OpenSSL and may include features 107215697Ssimonnot present in released versions. If in doubt refer to the documentation 108215697Ssimonthat came with the version of OpenSSL you are using. 10959191Skris 11059191SkrisFor information on parts of libcrypto that are not yet documented, you 11159191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 11259191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 11359191Skrisof this still applies to OpenSSL. 11459191Skris 11559191SkrisThere is some documentation about certificate extensions and PKCS#12 11659191Skrisin doc/openssl.txt 11759191Skris 11859191SkrisThe original SSLeay documentation is included in OpenSSL as 11959191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 12059191Skrishelp, but please note that it reflects the obsolete version SSLeay 12159191Skris0.6.6. 12259191Skris 12359191Skris 12459191Skris* How can I contact the OpenSSL developers? 12559191Skris 12659191SkrisThe README file describes how to submit bug reports and patches to 12759191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 12859191Skris<URL: http://www.openssl.org>. 12959191Skris 13059191Skris 13176866Skris* Where can I get a compiled version of OpenSSL? 13276866Skris 133127128SnectarYou can finder pointers to binary distributions in 134127128Snectarhttp://www.openssl.org/related/binaries.html . 135127128Snectar 13676866SkrisSome applications that use OpenSSL are distributed in binary form. 13776866SkrisWhen using such an application, you don't need to install OpenSSL 13876866Skrisyourself; the application will include the required parts (e.g. DLLs). 13976866Skris 140127128SnectarIf you want to build OpenSSL on a Windows system and you don't have 14176866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 14276866Skrison how to obtain and install the free GNU C compiler. 14376866Skris 14476866SkrisA number of Linux and *BSD distributions include OpenSSL. 14576866Skris 14676866Skris 14776866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 14876866Skris 14976866Skrisautoconf will probably be used in future OpenSSL versions. If it was 15076866Skrisless Unix-centric, it might have been used much earlier. 15176866Skris 15289837Skris* What is an 'engine' version? 15376866Skris 15489837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 15589837Skrishardware. This was realized in a special release '0.9.6-engine'. With 156160814Ssimonversion 0.9.7 the changes were merged into the main development line, 157160814Ssimonso that the special release is no longer necessary. 15889837Skris 159109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 160109998Smarkm 161109998SmarkmWe provide MD5 digests and ASC signatures of each tarball. 162109998SmarkmUse MD5 to check that a tarball from a mirror site is identical: 163109998Smarkm 164109998Smarkm md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 165109998Smarkm 166109998SmarkmYou can check authenticity using pgp or gpg. You need the OpenSSL team 167160814Ssimonmember public key used to sign it (download it from a key server, see a 168160814Ssimonlist of keys at <URL: http://www.openssl.org/about/>). Then 169109998Smarkmjust do: 170109998Smarkm 171109998Smarkm pgp TARBALL.asc 172109998Smarkm 17376866Skris[LEGAL] ======================================================================= 17476866Skris 17559191Skris* Do I need patent licenses to use OpenSSL? 17659191Skris 17759191SkrisThe patents section of the README file lists patents that may apply to 17859191Skrisyou if you want to use OpenSSL. For information on intellectual 17959191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 18059191Skrisoffer legal advice. 18159191Skris 182160814SsimonYou can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using 183160814Ssimon ./config no-idea no-mdc2 no-rc5 18459191Skris 18559191Skris 18676866Skris* Can I use OpenSSL with GPL software? 18759191Skris 18876866SkrisOn many systems including the major Linux and BSD distributions, yes (the 18976866SkrisGPL does not place restrictions on using libraries that are part of the 19076866Skrisnormal operating system distribution). 19159191Skris 19276866SkrisOn other systems, the situation is less clear. Some GPL software copyright 19376866Skrisholders claim that you infringe on their rights if you use OpenSSL with 19476866Skristheir software on operating systems that don't normally include OpenSSL. 19559191Skris 19676866SkrisIf you develop open source software that uses OpenSSL, you may find it 19789837Skrisuseful to choose an other license than the GPL, or state explicitly that 19876866Skris"This program is released under the GPL with the additional exemption that 19976866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 20076866SkrisGPL software developed by others, you may want to ask the copyright holder 20176866Skrisfor permission to use their software with OpenSSL. 20259191Skris 20376866Skris 20476866Skris[USER] ======================================================================== 20576866Skris 20659191Skris* Why do I get a "PRNG not seeded" error message? 20759191Skris 20859191SkrisCryptographic software needs a source of unpredictable data to work 20959191Skriscorrectly. Many open source operating systems provide a "randomness 210111147Snectardevice" (/dev/urandom or /dev/random) that serves this purpose. 211111147SnectarAll OpenSSL versions try to use /dev/urandom by default; starting with 212111147Snectarversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 213111147Snectaravailable. 21459191Skris 215111147SnectarOn other systems, applications have to call the RAND_add() or 216111147SnectarRAND_seed() function with appropriate data before generating keys or 217111147Snectarperforming public key encryption. (These functions initialize the 218111147Snectarpseudo-random number generator, PRNG.) Some broken applications do 219111147Snectarnot do this. As of version 0.9.5, the OpenSSL functions that need 220111147Snectarrandomness report an error if the random number generator has not been 221111147Snectarseeded with at least 128 bits of randomness. If this error occurs and 222111147Snectaris not discussed in the documentation of the application you are 223111147Snectarusing, please contact the author of that application; it is likely 224111147Snectarthat it never worked correctly. OpenSSL 0.9.5 and later make the 225111147Snectarerror visible by refusing to perform potentially insecure encryption. 22659191Skris 227111147SnectarIf you are using Solaris 8, you can add /dev/urandom and /dev/random 228111147Snectardevices by installing patch 112438 (Sparc) or 112439 (x86), which are 229111147Snectaravailable via the Patchfinder at <URL: http://sunsolve.sun.com> 230111147Snectar(Solaris 9 includes these devices by default). For /dev/random support 231111147Snectarfor earlier Solaris versions, see Sun's statement at 232111147Snectar<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 233111147Snectar(the SUNWski package is available in patch 105710). 234111147Snectar 23579998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 23679998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 23779998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 23879998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 23979998Skris/etc/entropy. 24059191Skris 24179998SkrisMost components of the openssl command line utility automatically try 24279998Skristo seed the random number generator from a file. The name of the 24379998Skrisdefault seeding file is determined as follows: If environment variable 24479998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 24579998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 24679998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 24779998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 24879998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 24989837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 25079998SkrisWindows systems if the environment variable has not been set. 25159191Skris 25279998SkrisIf the default seeding file does not exist or is too short, the "PRNG 25379998Skrisnot seeded" error message may occur. 25459191Skris 25579998SkrisThe openssl command line utility will write back a new state to the 25679998Skrisdefault seeding file (and create this file if necessary) unless 25779998Skristhere was no sufficient seeding. 25879998Skris 25979998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 26079998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 26179998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 26279998SkrisOpenSSL command line tools. Applications using the OpenSSL library 26379998Skrisprovide their own configuration options to specify the entropy source, 26479998Skrisplease check out the documentation coming the with application. 26579998Skris 26659191Skris 26779998Skris* Why do I get an "unable to write 'random state'" error message? 26879998Skris 26979998Skris 27079998SkrisSometimes the openssl command line utility does not abort with 27179998Skrisa "PRNG not seeded" error message, but complains that it is 27279998Skris"unable to write 'random state'". This message refers to the 27379998Skrisdefault seeding file (see previous answer). A possible reason 27479998Skrisis that no default filename is known because neither RANDFILE 27579998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 27679998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 27779998Skris 27879998Skris 27976866Skris* How do I create certificates or certificate requests? 28076866Skris 28176866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 28276866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 28376866Skrisout the manual pages for the individual utilities and the certificate 28476866Skrisextensions documentation (currently in doc/openssl.txt). 28576866Skris 28676866Skris 28776866Skris* Why can't I create certificate requests? 28876866Skris 28976866SkrisYou typically get the error: 29076866Skris 29176866Skris unable to find 'distinguished_name' in config 29276866Skris problems making Certificate Request 29376866Skris 29476866SkrisThis is because it can't find the configuration file. Check out the 29576866SkrisDIAGNOSTICS section of req(1) for more information. 29676866Skris 29776866Skris 29876866Skris* Why does <SSL program> fail with a certificate verify error? 29976866Skris 30076866SkrisThis problem is usually indicated by log messages saying something like 30176866Skris"unable to get local issuer certificate" or "self signed certificate". 30276866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 30376866Skristhis typically means that the CA certificate must be placed in a directory 30476866Skrisor file and the relevant program configured to read it. The OpenSSL program 30576866Skris'verify' behaves in a similar way and issues similar error messages: check 30676866Skristhe verify(1) program manual page for more information. 30776866Skris 30876866Skris 30976866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 31076866Skris 31176866SkrisThis is almost certainly because you are using an old "export grade" browser 31276866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 31376866Skrisciphers. 31476866Skris 31576866Skris 31676866Skris* How can I create DSA certificates? 31776866Skris 31876866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 31976866Skris 32076866Skris 32176866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 32276866Skris 32376866SkrisTypically you'll see a message saying there are no shared ciphers when 32476866Skristhe same setup works fine with an RSA certificate. There are two possible 32576866Skriscauses. The client may not support connections to DSA servers most web 32676866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 32776866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 32876866Skrishas not been supplied to the server. DH parameters can be created with the 32976866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 33076866Skrischeck the source to s_server in apps/s_server.c for an example. 33176866Skris 33276866Skris 33376866Skris* How can I remove the passphrase on a private key? 33476866Skris 33576866SkrisFirstly you should be really *really* sure you want to do this. Leaving 33676866Skrisa private key unencrypted is a major security risk. If you decide that 33776866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 33876866Skrisdsa(1) manual pages. 33976866Skris 34076866Skris 34176866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 34276866Skris 34376866SkrisWhat will typically happen is that when a server requests authentication 34476866Skrisit will either not include your certificate or tell you that you have 34576866Skrisno client certificates (Netscape) or present you with an empty list box 34676866Skris(MSIE). The reason for this is that when a server requests a client 34776866Skriscertificate it includes a list of CAs names which it will accept. Browsers 34876866Skriswill only let you select certificates from the list on the grounds that 34976866Skristhere is little point presenting a certificate which the server will 35076866Skrisreject. 35176866Skris 35276866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 35389837SkrisCA list". How you do this depends on the server software in uses. You can 35476866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 35576866Skris 35676866Skrisopenssl s_client -connect www.some.host:443 -prexit 35776866Skris 35876866SkrisIf your server only requests certificates on certain URLs then you may need 35976866Skristo manually issue an HTTP GET command to get the list when s_client connects: 36076866Skris 36176866SkrisGET /some/page/needing/a/certificate.html 36276866Skris 36376866SkrisIf your CA does not appear in the list then this confirms the problem. 36476866Skris 36576866Skris 36676866Skris* Why does my browser give a warning about a mismatched hostname? 36776866Skris 36876866SkrisBrowsers expect the server's hostname to match the value in the commonName 36976866Skris(CN) field of the certificate. If it does not then you get a warning. 37076866Skris 37176866Skris 37289837Skris* How do I install a CA certificate into a browser? 37389837Skris 37489837SkrisThe usual way is to send the DER encoded certificate to the browser as 37589837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 37689837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 37789837Skriscan import the certificate using the certificate import wizard. 37889837Skris 37989837SkrisYou can convert a certificate to DER form using the command: 38089837Skris 38189837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 38289837Skris 38389837SkrisOccasionally someone suggests using a command such as: 38489837Skris 38589837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 38689837Skris 38789837SkrisDO NOT DO THIS! This command will give away your CAs private key and 38889837Skrisreduces its security to zero: allowing anyone to forge certificates in 38989837Skriswhatever name they choose. 39089837Skris 391109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 39289837Skris 393109998SmarkmThe ways to print out the oneline format of the DN (Distinguished Name) have 394109998Smarkmbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 395109998Smarkminterface, the "-nameopt" option could be introduded. See the manual 396109998Smarkmpage of the "openssl x509" commandline tool for details. The old behaviour 397109998Smarkmhas however been left as default for the sake of compatibility. 398109998Smarkm 399160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 400160814Ssimon 401160814SsimonThe term "128 bit certificate" is a highly misleading marketing term. It does 402160814Ssimon*not* refer to the size of the public key in the certificate! A certificate 403160814Ssimoncontaining a 128 bit RSA key would have negligible security. 404160814Ssimon 405160814SsimonThere were various other names such as "magic certificates", "SGC 406160814Ssimoncertificates", "step up certificates" etc. 407160814Ssimon 408160814SsimonYou can't generally create such a certificate using OpenSSL but there is no 409160814Ssimonneed to any more. Nowadays web browsers using unrestricted strong encryption 410160814Ssimonare generally available. 411160814Ssimon 412194206SsimonWhen there were tight restrictions on the export of strong encryption 413160814Ssimonsoftware from the US only weak encryption algorithms could be freely exported 414160814Ssimon(initially 40 bit and then 56 bit). It was widely recognised that this was 415194206Ssimoninadequate. A relaxation of the rules allowed the use of strong encryption but 416160814Ssimononly to an authorised server. 417160814Ssimon 418160814SsimonTwo slighly different techniques were developed to support this, one used by 419160814SsimonNetscape was called "step up", the other used by MSIE was called "Server Gated 420160814SsimonCryptography" (SGC). When a browser initially connected to a server it would 421160814Ssimoncheck to see if the certificate contained certain extensions and was issued by 422160814Ssimonan authorised authority. If these test succeeded it would reconnect using 423160814Ssimonstrong encryption. 424160814Ssimon 425160814SsimonOnly certain (initially one) certificate authorities could issue the 426160814Ssimoncertificates and they generally cost more than ordinary certificates. 427160814Ssimon 428160814SsimonAlthough OpenSSL can create certificates containing the appropriate extensions 429160814Ssimonthe certificate would not come from a permitted authority and so would not 430160814Ssimonbe recognized. 431160814Ssimon 432160814SsimonThe export laws were later changed to allow almost unrestricted use of strong 433160814Ssimonencryption so these certificates are now obsolete. 434160814Ssimon 435160814Ssimon 436194206Ssimon* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? 437194206Ssimon 438194206SsimonIt doesn't: this extension is often the cause of confusion. 439194206Ssimon 440194206SsimonConsider a certificate chain A->B->C so that A signs B and B signs C. Suppose 441194206Ssimoncertificate C contains AKID. 442194206Ssimon 443194206SsimonThe purpose of this extension is to identify the authority certificate B. This 444194206Ssimoncan be done either by including the subject key identifier of B or its issuer 445194206Ssimonname and serial number. 446194206Ssimon 447194206SsimonIn this latter case because it is identifying certifcate B it must contain the 448194206Ssimonissuer name and serial number of B. 449194206Ssimon 450194206SsimonIt is often wrongly assumed that it should contain the subject name of B. If it 451194206Ssimondid this would be redundant information because it would duplicate the issuer 452194206Ssimonname of C. 453194206Ssimon 454194206Ssimon 455194206Ssimon* How can I set up a bundle of commercial root CA certificates? 456194206Ssimon 457194206SsimonThe OpenSSL software is shipped without any root CA certificate as the 458194206SsimonOpenSSL project does not have any policy on including or excluding 459194206Ssimonany specific CA and does not intend to set up such a policy. Deciding 460194206Ssimonabout which CAs to support is up to application developers or 461194206Ssimonadministrators. 462194206Ssimon 463194206SsimonOther projects do have other policies so you can for example extract the CA 464194206Ssimonbundle used by Mozilla and/or modssl as described in this article: 465194206Ssimon 466194206Ssimon http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html 467194206Ssimon 468194206Ssimon 46976866Skris[BUILD] ======================================================================= 47076866Skris 47159191Skris* Why does the linker complain about undefined symbols? 47259191Skris 47359191SkrisMaybe the compilation was interrupted, and make doesn't notice that 47459191Skrissomething is missing. Run "make clean; make". 47559191Skris 47659191SkrisIf you used ./Configure instead of ./config, make sure that you 47759191Skrisselected the right target. File formats may differ slightly between 47859191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 47959191Skris 48059191SkrisIn case you get errors about the following symbols, use the config 48159191Skrisoption "no-asm", as described in INSTALL: 48259191Skris 48359191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 48459191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 48559191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 48659191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 48759191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 48859191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 48959191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 49059191Skris 49159191SkrisIf none of these helps, you may want to try using the current snapshot. 49259191SkrisIf the problem persists, please submit a bug report. 49359191Skris 49459191Skris 49576866Skris* Why does the OpenSSL test fail with "bc: command not found"? 49659191Skris 49776866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 49876866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 49959191Skris 50059191Skris 50176866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 50259191Skris 50376866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 50476866Skriswhen you run the test suite (using "make test"). The message returned is 50576866Skris"bc: 1 not implemented". 50659191Skris 50776866SkrisThe best way to deal with this is to find another implementation of bc 50876866Skrisand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 50976866Skrisfor download instructions) can be safely used, for example. 51076866Skris 51176866Skris 512109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 513109998Smarkm 514109998SmarkmOn some DG/ux versions, bc seems to have a too small stack for calculations 515109998Smarkmthat the OpenSSL bntest throws at it. This gets triggered when you run the 516109998Smarkmtest suite (using "make test"). The message returned is "bc: stack empty". 517109998Smarkm 518109998SmarkmThe best way to deal with this is to find another implementation of bc 519109998Smarkmand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 520109998Smarkmfor download instructions) can be safely used, for example. 521109998Smarkm 522109998Smarkm 52389837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 52476866Skris 52589837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 52676866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 52776866Skrismemory to continue compilation.' As far as the tests have shown, this may be 52876866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 52976866Skristo build something, probably a table. The problem is clearly in the 53076866Skrisoptimization code, because if one eliminates optimization completely (-O0), 53176866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 53276866Skrismemory instead of 240MB or whatever one's limit is currently). 53376866Skris 53476866SkrisThere are three options to solve this problem: 53576866Skris 53676866Skris1. set your current data segment size soft limit higher. Experience shows 53776866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 53876866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 53976866Skriskbytes to set the limit to. 54076866Skris 54176866Skris2. If you have a hard limit that is lower than what you need and you can't 54276866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 54376866Skrislevel. This is however not a very nice thing to do for those who expect to 54476866Skrisget the best result from OpenSSL. A bit more complicated solution is the 54576866Skrisfollowing: 54676866Skris 54776866Skris----- snip:start ----- 548160814Ssimon make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 54976866Skris sed -e 's/ -O[0-9] / -O0 /'`" 55076866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 55176866Skris make 55276866Skris----- snip:end ----- 55376866Skris 55476866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 55576866Skrislevel chosen by the configuration process. When the above is done, do the 55676866Skristest and installation and you're set. 55776866Skris 558160814Ssimon3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 559160814Ssimonshould not be used and is not used in SSL/TLS nor any other recognized 560160814Ssimonprotocol in either case. 56176866Skris 562160814Ssimon 56376866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 56476866Skris 56576866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 56676866Skrisaway 'ar' and other development commands in directories that aren't in 56776866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 56876866Skrisquickest way to fix this is to do the following (it assumes you use sh 56976866Skrisor any sh-compatible shell): 57076866Skris 57176866Skris----- snip:start ----- 57276866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 57376866Skris----- snip:end ----- 57476866Skris 57576866Skrisand then redo the compilation. What you should really do is make sure 57676866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 57776866Skris'.profile' (again, assuming you use a sh-compatible shell). 57876866Skris 57976866Skris 58076866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 58176866Skris 58276866SkrisSometimes, you may get reports from VC++ command line (cl) that it 58376866Skriscan't find standard include files like stdio.h and other weirdnesses. 58476866SkrisOne possible cause is that the environment isn't correctly set up. 585111147SnectarTo solve that problem for VC++ versions up to 6, one should run 586111147SnectarVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 587111147Snectarinstallation directory (somewhere under 'Program Files'). For VC++ 588111147Snectarversion 7 (and up?), which is also called VS.NET, the file is called 589111147SnectarVSVARS32.BAT instead. 590111147SnectarThis needs to be done prior to running NMAKE, and the changes are only 591111147Snectarvalid for the current DOS session. 59276866Skris 59376866Skris 594100936Snectar* What is special about OpenSSL on Redhat? 595100936Snectar 596100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 597100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 598100936Snectaris disabled in this version. The same may apply to other Linux distributions. 599100936SnectarUsers may therefore wish to install more or all of the features left out. 600100936Snectar 601100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 602100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 603100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 604100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 605100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 606100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 607100936Snectar/lib/libcrypto.so.2 respectively). 608100936Snectar 609100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 610100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 611100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 612100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 613100936Snectaropenssl on each distribution never change the package version, only the 614100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 615100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 616100936Snectarrelevant updates in packages up to and including 0.9.6b. 617100936Snectar 618100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 619100936Snectarversion of Red Hat Linux. 620100936Snectar 621100936SnectarFYI: Patent numbers and expiry dates of US patents: 622100936SnectarMDC-2: 4,908,861 13/03/2007 623100936SnectarIDEA: 5,214,703 25/05/2010 624100936SnectarRC5: 5,724,428 03/03/2015 625100936Snectar 626100936Snectar 627109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 628109998Smarkm 629109998SmarkmIf the failure happens when trying to build the "openssl" binary, with 630109998Smarkma large number of undefined symbols, it's very probable that you have 631109998SmarkmOpenSSL 0.9.6b delivered with the operating system (you can find out by 632109998Smarkmrunning '/usr/bin/openssl version') and that you were trying to build 633109998SmarkmOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 634109998SmarkmMacOS X has a misfeature that's quite difficult to go around. 635109998SmarkmLook in the file PROBLEMS for a more detailed explanation and for possible 636109998Smarkmsolutions. 637109998Smarkm 638109998Smarkm 639100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 640100936Snectar 641100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 642100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 643100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 644100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 645100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 646100936Snectargo around and has linked the programs "openssl" and the test programs 647100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 648100936Snectarlibraries you just built. 649100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 650100936Snectarsolutions. 651100936Snectar 652109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 653109998Smarkm 654109998SmarkmFailure in BN_sqr test is most likely caused by a failure to configure the 655109998Smarkmtoolkit for current platform or lack of support for the platform in question. 656109998SmarkmRun './config -t' and './apps/openssl version -p'. Do these platform 657109998Smarkmidentifiers match? If they don't, then you most likely failed to run 658109998Smarkm./config and you're hereby advised to do so before filing a bug report. 659109998SmarkmIf ./config itself fails to run, then it's most likely problem with your 660109998Smarkmlocal environment and you should turn to your system administrator (or 661109998Smarkmsimilar). If identifiers match (and/or no alternative identifier is 662109998Smarkmsuggested by ./config script), then the platform is unsupported. There might 663109998Smarkmor might not be a workaround. Most notably on SPARC64 platforms with GNU 664109998SmarkmC compiler you should be able to produce a working build by running 665109998Smarkm'./config -m32'. I understand that -m32 might not be what you want/need, 666109998Smarkmbut the build should be operational. For further details turn to 667109998Smarkm<openssl-dev@openssl.org>. 668109998Smarkm 669109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 670109998Smarkm 671109998SmarkmAs of 0.9.7 assembler routines were overhauled for position independence 672109998Smarkmof the machine code, which is essential for shared library support. For 673109998Smarkmsome reason OpenBSD is equipped with an out-of-date GNU assembler which 674109998Smarkmfinds the new code offensive. To work around the problem, configure with 675111147Snectarno-asm (and sacrifice a great deal of performance) or patch your assembler 676111147Snectaraccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 677109998SmarkmFor your convenience a pre-compiled replacement binary is provided at 678111147Snectar<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 679111147SnectarReportedly elder *BSD a.out platforms also suffer from this problem and 680111147Snectarremedy should be same. Provided binary is statically linked and should be 681111147Snectarworking across wider range of *BSD branches, not just OpenBSD. 682109998Smarkm 683160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 684160814Ssimon 685160814SsimonIf the test program in question fails withs SIGILL, Illegal Instruction 686160814Ssimonexception, then you more than likely to run SSE2-capable CPU, such as 687160814SsimonIntel P4, under control of kernel which does not support SSE2 688160814Ssimoninstruction extentions. See accompanying INSTALL file and 689160814SsimonOPENSSL_ia32cap(3) documentation page for further information. 690160814Ssimon 691160814Ssimon* Why does compiler fail to compile sha512.c? 692160814Ssimon 693160814SsimonOpenSSL SHA-512 implementation depends on compiler support for 64-bit 694160814Ssimoninteger type. Few elder compilers [ULTRIX cc, SCO compiler to mention a 695160814Ssimoncouple] lack support for this and therefore are incapable of compiling 696160814Ssimonthe module in question. The recommendation is to disable SHA-512 by 697160814Ssimonadding no-sha512 to ./config [or ./Configure] command line. Another 698160814Ssimonpossible alternative might be to switch to GCC. 699160814Ssimon 700160814Ssimon* Test suite still fails, what to do? 701160814Ssimon 702160814SsimonAnother common reason for failure to complete some particular test is 703160814Ssimonsimply bad code generated by a buggy component in toolchain or deficiency 704160814Ssimonin run-time environment. There are few cases documented in PROBLEMS file, 705160814Ssimonconsult it for possible workaround before you beat the drum. Even if you 706160814Ssimondon't find solution or even mention there, do reserve for possibility of 707160814Ssimona compiler bug. Compiler bugs might appear in rather bizarre ways, they 708160814Ssimonnever make sense, and tend to emerge when you least expect them. In order 709160814Ssimonto identify one, drop optimization level, e.g. by editing CFLAG line in 710160814Ssimontop-level Makefile, recompile and re-run the test. 711160814Ssimon 71276866Skris[PROG] ======================================================================== 71376866Skris 71476866Skris* Is OpenSSL thread-safe? 71576866Skris 71676866SkrisYes (with limitations: an SSL connection may not concurrently be used 71776866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 71876866Skrisautomatically uses the multi-threaded versions of the standard 71976866Skrislibraries. If your platform is not one of these, consult the INSTALL 72076866Skrisfile. 72176866Skris 72276866SkrisMulti-threaded applications must provide two callback functions to 723162911SsimonOpenSSL by calling CRYPTO_set_locking_callback() and 724215697SsimonCRYPTO_set_id_callback(), for all versions of OpenSSL up to and 725215697Ssimonincluding 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback() 726215697Ssimonand associated APIs are deprecated by CRYPTO_THREADID_set_callback() 727215697Ssimonand friends. This is described in the threads(3) manpage. 72876866Skris 72959191Skris* I've compiled a program under Windows and it crashes: why? 73059191Skris 73189837SkrisThis is usually because you've missed the comment in INSTALL.W32. 73289837SkrisYour application must link against the same version of the Win32 73389837SkrisC-Runtime against which your openssl libraries were linked. The 73489837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 73559191Skris 73689837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 73789837Skrismany cases, your new project most likely defaulted to "Debug 73889837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 73989837Skrisprogram will crash, typically on the first BIO related read or write 74089837Skrisoperation. 74159191Skris 74289837SkrisFor each of the six possible link stage configurations within Win32, 74389837Skrisyour application must link against the same by which OpenSSL was 74489837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 74589837Skrisby: 74689837Skris 747160814Ssimon 1. Select Settings... from the Project Menu. 748160814Ssimon 2. Select the C/C++ Tab. 749160814Ssimon 3. Select "Code Generation from the "Category" drop down list box 750160814Ssimon 4. Select the Appropriate library (see table below) from the "Use 75189837Skris run-time library" drop down list box. Perform this step for both 75289837Skris your debug and release versions of your application (look at the 75389837Skris top left of the settings panel to change between the two) 75489837Skris 75589837Skris Single Threaded /ML - MS VC++ often defaults to 75689837Skris this for the release 75789837Skris version of a new project. 75889837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 75989837Skris this for the debug version 76089837Skris of a new project. 76189837Skris Multithreaded /MT 76289837Skris Debug Multithreaded /MTd 76389837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 76489837Skris Debug Multithreaded DLL /MDd 76589837Skris 76689837SkrisNote that debug and release libraries are NOT interchangeable. If you 76789837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 76889837Skris 769160814SsimonAs per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL 770160814Ssimon.DLLs compiled with some specific run-time option [we insist on the 771160814Ssimondefault /MD] can be deployed with application compiled with different 772160814Ssimonoption or even different compiler. But there is a catch! Instead of 773160814Ssimonre-compiling OpenSSL toolkit, as you would have to with prior versions, 774160814Ssimonyou have to compile small C snippet with compiler and/or options of 775160814Ssimonyour choice. The snippet gets installed as 776160814Ssimon<install-root>/include/openssl/applink.c and should be either added to 777160814Ssimonyour application project or simply #include-d in one [and only one] 778160814Ssimonof your application source files. Failure to link this shim module 779160814Ssimoninto your application manifests itself as fatal "no OPENSSL_Applink" 780160814Ssimonrun-time error. An explicit reminder is due that in this situation 781160814Ssimon[mixing compiler options] it is as important to add CRYPTO_malloc_init 782160814Ssimonprior first call to OpenSSL. 78389837Skris 78468651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 78568651Skris 78668651SkrisYou have two options. You can either use a memory BIO in conjunction 787160814Ssimonwith the i2d_*_bio() or d2i_*_bio() functions or you can use the 788160814Ssimoni2d_*(), d2i_*() functions directly. Since these are often the 78968651Skriscause of grief here are some code fragments using PKCS7 as an example: 79068651Skris 791160814Ssimon unsigned char *buf, *p; 792160814Ssimon int len; 79368651Skris 794160814Ssimon len = i2d_PKCS7(p7, NULL); 795160814Ssimon buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 796160814Ssimon p = buf; 797160814Ssimon i2d_PKCS7(p7, &p); 79868651Skris 79968651SkrisAt this point buf contains the len bytes of the DER encoding of 80068651Skrisp7. 80168651Skris 80268651SkrisThe opposite assumes we already have len bytes in buf: 80368651Skris 804160814Ssimon unsigned char *p; 805160814Ssimon p = buf; 806160814Ssimon p7 = d2i_PKCS7(NULL, &p, len); 80768651Skris 80868651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 80968651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 81068651Skrisinformation. 81168651Skris 81268651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 81368651Skrisincrement the passed pointer so it is ready to read or write the next 81468651Skrisstructure. This is often a cause of problems: without the temporary 81568651Skrisvariable the buffer pointer is changed to point just after the data 81668651Skristhat has been read or written. This may well be uninitialized data 81768651Skrisand attempts to free the buffer will have unpredictable results 81868651Skrisbecause it no longer points to the same address. 81968651Skris 82068651Skris 821142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 822142425Snectar 823142425SnectarThe short answer is yes, because DER is a special case of BER and OpenSSL 824142425SnectarASN1 decoders can process BER. 825142425Snectar 826142425SnectarThe longer answer is that ASN1 structures can be encoded in a number of 827142425Snectardifferent ways. One set of ways is the Basic Encoding Rules (BER) with various 828142425Snectarpermissible encodings. A restriction of BER is the Distinguished Encoding 829142425SnectarRules (DER): these uniquely specify how a given structure is encoded. 830142425Snectar 831142425SnectarTherefore, because DER is a special case of BER, DER is an acceptable encoding 832142425Snectarfor BER. 833142425Snectar 834142425Snectar 83568651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 83668651Skris 83768651SkrisThis usually happens when you try compiling something using the PKCS#12 83868651Skrismacros with a C++ compiler. There is hardly ever any need to use the 83968651SkrisPKCS#12 macros in a program, it is much easier to parse and create 84068651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 84168651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 84268651Skris'pkcs12' application has to use the macros because it prints out 84368651Skrisdebugging information. 84468651Skris 84568651Skris 84659191Skris* I've called <some function> and it fails, why? 84759191Skris 84868651SkrisBefore submitting a report or asking in one of the mailing lists, you 84968651Skrisshould try to determine the cause. In particular, you should call 85059191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 85168651Skrisand see if the message helps. Note that the problem may occur earlier 85268651Skristhan you think -- you should check for errors after every call where 85368651Skrisit is possible, otherwise the actual problem may be hidden because 85468651Skrissome OpenSSL functions clear the error state. 85559191Skris 85659191Skris 85759191Skris* I just get a load of numbers for the error output, what do they mean? 85859191Skris 85959191SkrisThe actual format is described in the ERR_print_errors() manual page. 86059191SkrisYou should call the function ERR_load_crypto_strings() before hand and 86159191Skristhe message will be output in text form. If you can't do this (for example 86259191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 86359191Skriscode itself (the hex digits after the second colon). 86459191Skris 86559191Skris 86659191Skris* Why do I get errors about unknown algorithms? 86759191Skris 868194206SsimonThe cause is forgetting to load OpenSSL's table of algorithms with 869194206SsimonOpenSSL_add_all_algorithms(). See the manual page for more information. This 870194206Ssimoncan cause several problems such as being unable to read in an encrypted 871194206SsimonPEM file, unable to decrypt a PKCS#12 file or signature failure when 872194206Ssimonverifying certificates. 87359191Skris 87459191Skris* Why can't the OpenSSH configure script detect OpenSSL? 87559191Skris 87689837SkrisSeveral reasons for problems with the automatic detection exist. 87789837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 87889837SkrisSometimes the distribution has installed an older version in the system 87989837Skrislocations that is detected instead of a new one installed. The OpenSSL 88089837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 88189837SkrisPermissions might be wrong. 88259191Skris 88389837SkrisThe general answer is to check the config.log file generated when running 88489837Skristhe OpenSSH configure script. It should contain the detailed information 88589837Skrison why the OpenSSL library was not detected or considered incompatible. 88668651Skris 887120631Snectar 88876866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 88968651Skris 89076866SkrisYes; make sure to read the SSL_get_error(3) manual page! 89168651Skris 89276866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 89376866Skristhe underlying transport or that SSL_write() will just write to it -- 89476866Skrisit is also possible that SSL_write() cannot do any useful work until 89576866Skristhere is data to read, or that SSL_read() cannot do anything until it 89676866Skrisis possible to send data. One reason for this is that the peer may 89776866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 89876866Skrisrequiring a bi-directional message exchange; both SSL_read() and 89976866SkrisSSL_write() will try to continue any pending handshake. 90068651Skris 90168651Skris 90279998Skris* Why doesn't my server application receive a client certificate? 90379998Skris 90479998SkrisDue to the TLS protocol definition, a client will only send a certificate, 90589837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 90679998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 90779998Skris 90879998Skris 909109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 910109998Smarkm 911109998SmarkmFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 912109998Smarkmversions, uniqueIdentifier was incorrectly used for X.509 certificates. 913109998SmarkmThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 914109998SmarkmChange your code to use the new name when compiling against OpenSSL 0.9.7. 915109998Smarkm 916109998Smarkm 917142425Snectar* I think I've detected a memory leak, is this a bug? 918142425Snectar 919142425SnectarIn most cases the cause of an apparent memory leak is an OpenSSL internal table 920142425Snectarthat is allocated when an application starts up. Since such tables do not grow 921142425Snectarin size over time they are harmless. 922142425Snectar 923142425SnectarThese internal tables can be freed up when an application closes using various 924160814Ssimonfunctions. Currently these include following: 925142425Snectar 926160814SsimonThread-local cleanup functions: 927142425Snectar 928160814Ssimon ERR_remove_state() 929160814Ssimon 930160814SsimonApplication-global cleanup functions that are aware of usage (and therefore 931160814Ssimonthread-safe): 932160814Ssimon 933160814Ssimon ENGINE_cleanup() and CONF_modules_unload() 934160814Ssimon 935160814Ssimon"Brutal" (thread-unsafe) Application-global cleanup functions: 936160814Ssimon 937160814Ssimon ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). 938160814Ssimon 939160814Ssimon 940194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 941194206Ssimon 942194206SsimonWhen OpenSSL's PRNG routines are called to generate random numbers the supplied 943194206Ssimonbuffer contents are mixed into the entropy pool: so it technically does not 944194206Ssimonmatter whether the buffer is initialized at this point or not. Valgrind (and 945194206Ssimonother test tools) will complain about this. When using Valgrind, make sure the 946194206SsimonOpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) 947194206Ssimonto get rid of these warnings. 948194206Ssimon 949194206Ssimon 950194206Ssimon* Why doesn't a memory BIO work when a file does? 951194206Ssimon 952194206SsimonThis can occur in several cases for example reading an S/MIME email message. 953194206SsimonThe reason is that a memory BIO can do one of two things when all the data 954194206Ssimonhas been read from it. 955194206Ssimon 956194206SsimonThe default behaviour is to indicate that no more data is available and that 957194206Ssimonthe call should be retried, this is to allow the application to fill up the BIO 958194206Ssimonagain if necessary. 959194206Ssimon 960194206SsimonAlternatively it can indicate that no more data is available and that EOF has 961194206Ssimonbeen reached. 962194206Ssimon 963194206SsimonIf a memory BIO is to behave in the same way as a file this second behaviour 964194206Ssimonis needed. This must be done by calling: 965194206Ssimon 966194206Ssimon BIO_set_mem_eof_return(bio, 0); 967194206Ssimon 968194206SsimonSee the manual pages for more details. 969194206Ssimon 970194206Ssimon 971215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 972215697Ssimon 973215697SsimonThese are defined and implemented by macros of the form: 974215697Ssimon 975215697Ssimon 976215697Ssimon DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) 977215697Ssimon 978215697SsimonThe implementation passes an ASN1 "template" defining the structure into an 979215697SsimonASN1 interpreter using generalised functions such as ASN1_item_d2i(). 980215697Ssimon 981215697Ssimon 98276866Skris=============================================================================== 983