FAQ revision 216166
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? 55216166Ssimon* I think I've found a bug, what should I do? 56216166Ssimon* I'm SURE I've found a bug, how do I report it? 57216166Ssimon* I've found a security issue, how do I report it? 5859191Skris 5976866Skris[PROG] Questions about programming with OpenSSL 6059191Skris 6176866Skris* Is OpenSSL thread-safe? 6276866Skris* I've compiled a program under Windows and it crashes: why? 6376866Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 64142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 6576866Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 6676866Skris* I've called <some function> and it fails, why? 6776866Skris* I just get a load of numbers for the error output, what do they mean? 6876866Skris* Why do I get errors about unknown algorithms? 6976866Skris* Why can't the OpenSSH configure script detect OpenSSL? 7076866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 7179998Skris* Why doesn't my server application receive a client certificate? 72109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 73142425Snectar* I think I've detected a memory leak, is this a bug? 74194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 75194206Ssimon* Why doesn't a memory BIO work when a file does? 76215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 7776866Skris 7876866Skris=============================================================================== 7976866Skris 8076866Skris[MISC] ======================================================================== 8176866Skris 8259191Skris* Which is the current version of OpenSSL? 8359191Skris 8459191SkrisThe current version is available from <URL: http://www.openssl.org>. 85216166SsimonOpenSSL 1.0.0c was released on Dec 2nd, 2010. 8659191Skris 8759191SkrisIn addition to the current stable release, you can also access daily 8859191Skrissnapshots of the OpenSSL development version at <URL: 8959191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 9059191Skris 9159191Skris 9259191Skris* Where is the documentation? 9359191Skris 9459191SkrisOpenSSL is a library that provides cryptographic functionality to 9559191Skrisapplications such as secure web servers. Be sure to read the 9659191Skrisdocumentation of the application you want to use. The INSTALL file 9759191Skrisexplains how to install this library. 9859191Skris 9959191SkrisOpenSSL includes a command line utility that can be used to perform a 10059191Skrisvariety of cryptographic functions. It is described in the openssl(1) 101215697Ssimonmanpage. Documentation for developers is currently being written. Many 102215697Ssimonmanual pages are available; overviews over libcrypto and 10359191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 10459191Skris 10559191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 10659191Skrisdifferent directory if you specified one as described in INSTALL). 10759191SkrisIn addition, you can read the most current versions at 108215697Ssimon<URL: http://www.openssl.org/docs/>. Note that the online documents refer 109215697Ssimonto the very latest development versions of OpenSSL and may include features 110215697Ssimonnot present in released versions. If in doubt refer to the documentation 111215697Ssimonthat came with the version of OpenSSL you are using. 11259191Skris 11359191SkrisFor information on parts of libcrypto that are not yet documented, you 11459191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 11559191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 11659191Skrisof this still applies to OpenSSL. 11759191Skris 11859191SkrisThere is some documentation about certificate extensions and PKCS#12 11959191Skrisin doc/openssl.txt 12059191Skris 12159191SkrisThe original SSLeay documentation is included in OpenSSL as 12259191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 12359191Skrishelp, but please note that it reflects the obsolete version SSLeay 12459191Skris0.6.6. 12559191Skris 12659191Skris 12759191Skris* How can I contact the OpenSSL developers? 12859191Skris 12959191SkrisThe README file describes how to submit bug reports and patches to 13059191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 13159191Skris<URL: http://www.openssl.org>. 13259191Skris 13359191Skris 13476866Skris* Where can I get a compiled version of OpenSSL? 13576866Skris 136127128SnectarYou can finder pointers to binary distributions in 137216166Ssimon<URL: http://www.openssl.org/related/binaries.html> . 138127128Snectar 13976866SkrisSome applications that use OpenSSL are distributed in binary form. 14076866SkrisWhen using such an application, you don't need to install OpenSSL 14176866Skrisyourself; the application will include the required parts (e.g. DLLs). 14276866Skris 143127128SnectarIf you want to build OpenSSL on a Windows system and you don't have 14476866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 14576866Skrison how to obtain and install the free GNU C compiler. 14676866Skris 14776866SkrisA number of Linux and *BSD distributions include OpenSSL. 14876866Skris 14976866Skris 15076866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 15176866Skris 15276866Skrisautoconf will probably be used in future OpenSSL versions. If it was 15376866Skrisless Unix-centric, it might have been used much earlier. 15476866Skris 15589837Skris* What is an 'engine' version? 15676866Skris 15789837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 15889837Skrishardware. This was realized in a special release '0.9.6-engine'. With 159160814Ssimonversion 0.9.7 the changes were merged into the main development line, 160160814Ssimonso that the special release is no longer necessary. 16189837Skris 162109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 163109998Smarkm 164109998SmarkmWe provide MD5 digests and ASC signatures of each tarball. 165109998SmarkmUse MD5 to check that a tarball from a mirror site is identical: 166109998Smarkm 167109998Smarkm md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 168109998Smarkm 169109998SmarkmYou can check authenticity using pgp or gpg. You need the OpenSSL team 170160814Ssimonmember public key used to sign it (download it from a key server, see a 171160814Ssimonlist of keys at <URL: http://www.openssl.org/about/>). Then 172109998Smarkmjust do: 173109998Smarkm 174109998Smarkm pgp TARBALL.asc 175109998Smarkm 17676866Skris[LEGAL] ======================================================================= 17776866Skris 17859191Skris* Do I need patent licenses to use OpenSSL? 17959191Skris 18059191SkrisThe patents section of the README file lists patents that may apply to 18159191Skrisyou if you want to use OpenSSL. For information on intellectual 18259191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 18359191Skrisoffer legal advice. 18459191Skris 185160814SsimonYou can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using 186160814Ssimon ./config no-idea no-mdc2 no-rc5 18759191Skris 18859191Skris 18976866Skris* Can I use OpenSSL with GPL software? 19059191Skris 19176866SkrisOn many systems including the major Linux and BSD distributions, yes (the 19276866SkrisGPL does not place restrictions on using libraries that are part of the 19376866Skrisnormal operating system distribution). 19459191Skris 19576866SkrisOn other systems, the situation is less clear. Some GPL software copyright 19676866Skrisholders claim that you infringe on their rights if you use OpenSSL with 19776866Skristheir software on operating systems that don't normally include OpenSSL. 19859191Skris 19976866SkrisIf you develop open source software that uses OpenSSL, you may find it 20089837Skrisuseful to choose an other license than the GPL, or state explicitly that 20176866Skris"This program is released under the GPL with the additional exemption that 20276866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 20376866SkrisGPL software developed by others, you may want to ask the copyright holder 20476866Skrisfor permission to use their software with OpenSSL. 20559191Skris 20676866Skris 20776866Skris[USER] ======================================================================== 20876866Skris 20959191Skris* Why do I get a "PRNG not seeded" error message? 21059191Skris 21159191SkrisCryptographic software needs a source of unpredictable data to work 21259191Skriscorrectly. Many open source operating systems provide a "randomness 213111147Snectardevice" (/dev/urandom or /dev/random) that serves this purpose. 214111147SnectarAll OpenSSL versions try to use /dev/urandom by default; starting with 215111147Snectarversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 216111147Snectaravailable. 21759191Skris 218111147SnectarOn other systems, applications have to call the RAND_add() or 219111147SnectarRAND_seed() function with appropriate data before generating keys or 220111147Snectarperforming public key encryption. (These functions initialize the 221111147Snectarpseudo-random number generator, PRNG.) Some broken applications do 222111147Snectarnot do this. As of version 0.9.5, the OpenSSL functions that need 223111147Snectarrandomness report an error if the random number generator has not been 224111147Snectarseeded with at least 128 bits of randomness. If this error occurs and 225111147Snectaris not discussed in the documentation of the application you are 226111147Snectarusing, please contact the author of that application; it is likely 227111147Snectarthat it never worked correctly. OpenSSL 0.9.5 and later make the 228111147Snectarerror visible by refusing to perform potentially insecure encryption. 22959191Skris 230111147SnectarIf you are using Solaris 8, you can add /dev/urandom and /dev/random 231111147Snectardevices by installing patch 112438 (Sparc) or 112439 (x86), which are 232111147Snectaravailable via the Patchfinder at <URL: http://sunsolve.sun.com> 233111147Snectar(Solaris 9 includes these devices by default). For /dev/random support 234111147Snectarfor earlier Solaris versions, see Sun's statement at 235111147Snectar<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 236111147Snectar(the SUNWski package is available in patch 105710). 237111147Snectar 23879998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 23979998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 24079998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 24179998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 24279998Skris/etc/entropy. 24359191Skris 24479998SkrisMost components of the openssl command line utility automatically try 24579998Skristo seed the random number generator from a file. The name of the 24679998Skrisdefault seeding file is determined as follows: If environment variable 24779998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 24879998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 24979998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 25079998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 25179998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 25289837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 25379998SkrisWindows systems if the environment variable has not been set. 25459191Skris 25579998SkrisIf the default seeding file does not exist or is too short, the "PRNG 25679998Skrisnot seeded" error message may occur. 25759191Skris 25879998SkrisThe openssl command line utility will write back a new state to the 25979998Skrisdefault seeding file (and create this file if necessary) unless 26079998Skristhere was no sufficient seeding. 26179998Skris 26279998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 26379998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 26479998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 26579998SkrisOpenSSL command line tools. Applications using the OpenSSL library 26679998Skrisprovide their own configuration options to specify the entropy source, 26779998Skrisplease check out the documentation coming the with application. 26879998Skris 26959191Skris 27079998Skris* Why do I get an "unable to write 'random state'" error message? 27179998Skris 27279998Skris 27379998SkrisSometimes the openssl command line utility does not abort with 27479998Skrisa "PRNG not seeded" error message, but complains that it is 27579998Skris"unable to write 'random state'". This message refers to the 27679998Skrisdefault seeding file (see previous answer). A possible reason 27779998Skrisis that no default filename is known because neither RANDFILE 27879998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 27979998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 28079998Skris 28179998Skris 28276866Skris* How do I create certificates or certificate requests? 28376866Skris 28476866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 28576866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 28676866Skrisout the manual pages for the individual utilities and the certificate 28776866Skrisextensions documentation (currently in doc/openssl.txt). 28876866Skris 28976866Skris 29076866Skris* Why can't I create certificate requests? 29176866Skris 29276866SkrisYou typically get the error: 29376866Skris 29476866Skris unable to find 'distinguished_name' in config 29576866Skris problems making Certificate Request 29676866Skris 29776866SkrisThis is because it can't find the configuration file. Check out the 29876866SkrisDIAGNOSTICS section of req(1) for more information. 29976866Skris 30076866Skris 30176866Skris* Why does <SSL program> fail with a certificate verify error? 30276866Skris 30376866SkrisThis problem is usually indicated by log messages saying something like 30476866Skris"unable to get local issuer certificate" or "self signed certificate". 30576866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 30676866Skristhis typically means that the CA certificate must be placed in a directory 30776866Skrisor file and the relevant program configured to read it. The OpenSSL program 30876866Skris'verify' behaves in a similar way and issues similar error messages: check 30976866Skristhe verify(1) program manual page for more information. 31076866Skris 31176866Skris 31276866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 31376866Skris 31476866SkrisThis is almost certainly because you are using an old "export grade" browser 31576866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 31676866Skrisciphers. 31776866Skris 31876866Skris 31976866Skris* How can I create DSA certificates? 32076866Skris 32176866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 32276866Skris 32376866Skris 32476866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 32576866Skris 32676866SkrisTypically you'll see a message saying there are no shared ciphers when 32776866Skristhe same setup works fine with an RSA certificate. There are two possible 32876866Skriscauses. The client may not support connections to DSA servers most web 32976866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 33076866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 33176866Skrishas not been supplied to the server. DH parameters can be created with the 33276866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 33376866Skrischeck the source to s_server in apps/s_server.c for an example. 33476866Skris 33576866Skris 33676866Skris* How can I remove the passphrase on a private key? 33776866Skris 33876866SkrisFirstly you should be really *really* sure you want to do this. Leaving 33976866Skrisa private key unencrypted is a major security risk. If you decide that 34076866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 34176866Skrisdsa(1) manual pages. 34276866Skris 34376866Skris 34476866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 34576866Skris 34676866SkrisWhat will typically happen is that when a server requests authentication 34776866Skrisit will either not include your certificate or tell you that you have 34876866Skrisno client certificates (Netscape) or present you with an empty list box 34976866Skris(MSIE). The reason for this is that when a server requests a client 35076866Skriscertificate it includes a list of CAs names which it will accept. Browsers 35176866Skriswill only let you select certificates from the list on the grounds that 35276866Skristhere is little point presenting a certificate which the server will 35376866Skrisreject. 35476866Skris 35576866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 35689837SkrisCA list". How you do this depends on the server software in uses. You can 35776866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 35876866Skris 35976866Skrisopenssl s_client -connect www.some.host:443 -prexit 36076866Skris 36176866SkrisIf your server only requests certificates on certain URLs then you may need 36276866Skristo manually issue an HTTP GET command to get the list when s_client connects: 36376866Skris 36476866SkrisGET /some/page/needing/a/certificate.html 36576866Skris 36676866SkrisIf your CA does not appear in the list then this confirms the problem. 36776866Skris 36876866Skris 36976866Skris* Why does my browser give a warning about a mismatched hostname? 37076866Skris 37176866SkrisBrowsers expect the server's hostname to match the value in the commonName 37276866Skris(CN) field of the certificate. If it does not then you get a warning. 37376866Skris 37476866Skris 37589837Skris* How do I install a CA certificate into a browser? 37689837Skris 37789837SkrisThe usual way is to send the DER encoded certificate to the browser as 37889837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 37989837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 38089837Skriscan import the certificate using the certificate import wizard. 38189837Skris 38289837SkrisYou can convert a certificate to DER form using the command: 38389837Skris 38489837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 38589837Skris 38689837SkrisOccasionally someone suggests using a command such as: 38789837Skris 38889837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 38989837Skris 39089837SkrisDO NOT DO THIS! This command will give away your CAs private key and 39189837Skrisreduces its security to zero: allowing anyone to forge certificates in 39289837Skriswhatever name they choose. 39389837Skris 394109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 39589837Skris 396109998SmarkmThe ways to print out the oneline format of the DN (Distinguished Name) have 397109998Smarkmbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 398109998Smarkminterface, the "-nameopt" option could be introduded. See the manual 399109998Smarkmpage of the "openssl x509" commandline tool for details. The old behaviour 400109998Smarkmhas however been left as default for the sake of compatibility. 401109998Smarkm 402160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 403160814Ssimon 404160814SsimonThe term "128 bit certificate" is a highly misleading marketing term. It does 405160814Ssimon*not* refer to the size of the public key in the certificate! A certificate 406160814Ssimoncontaining a 128 bit RSA key would have negligible security. 407160814Ssimon 408160814SsimonThere were various other names such as "magic certificates", "SGC 409160814Ssimoncertificates", "step up certificates" etc. 410160814Ssimon 411160814SsimonYou can't generally create such a certificate using OpenSSL but there is no 412160814Ssimonneed to any more. Nowadays web browsers using unrestricted strong encryption 413160814Ssimonare generally available. 414160814Ssimon 415194206SsimonWhen there were tight restrictions on the export of strong encryption 416160814Ssimonsoftware from the US only weak encryption algorithms could be freely exported 417160814Ssimon(initially 40 bit and then 56 bit). It was widely recognised that this was 418194206Ssimoninadequate. A relaxation of the rules allowed the use of strong encryption but 419160814Ssimononly to an authorised server. 420160814Ssimon 421160814SsimonTwo slighly different techniques were developed to support this, one used by 422160814SsimonNetscape was called "step up", the other used by MSIE was called "Server Gated 423160814SsimonCryptography" (SGC). When a browser initially connected to a server it would 424160814Ssimoncheck to see if the certificate contained certain extensions and was issued by 425160814Ssimonan authorised authority. If these test succeeded it would reconnect using 426160814Ssimonstrong encryption. 427160814Ssimon 428160814SsimonOnly certain (initially one) certificate authorities could issue the 429160814Ssimoncertificates and they generally cost more than ordinary certificates. 430160814Ssimon 431160814SsimonAlthough OpenSSL can create certificates containing the appropriate extensions 432160814Ssimonthe certificate would not come from a permitted authority and so would not 433160814Ssimonbe recognized. 434160814Ssimon 435160814SsimonThe export laws were later changed to allow almost unrestricted use of strong 436160814Ssimonencryption so these certificates are now obsolete. 437160814Ssimon 438160814Ssimon 439194206Ssimon* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? 440194206Ssimon 441194206SsimonIt doesn't: this extension is often the cause of confusion. 442194206Ssimon 443194206SsimonConsider a certificate chain A->B->C so that A signs B and B signs C. Suppose 444194206Ssimoncertificate C contains AKID. 445194206Ssimon 446194206SsimonThe purpose of this extension is to identify the authority certificate B. This 447194206Ssimoncan be done either by including the subject key identifier of B or its issuer 448194206Ssimonname and serial number. 449194206Ssimon 450194206SsimonIn this latter case because it is identifying certifcate B it must contain the 451194206Ssimonissuer name and serial number of B. 452194206Ssimon 453194206SsimonIt is often wrongly assumed that it should contain the subject name of B. If it 454194206Ssimondid this would be redundant information because it would duplicate the issuer 455194206Ssimonname of C. 456194206Ssimon 457194206Ssimon 458194206Ssimon* How can I set up a bundle of commercial root CA certificates? 459194206Ssimon 460194206SsimonThe OpenSSL software is shipped without any root CA certificate as the 461194206SsimonOpenSSL project does not have any policy on including or excluding 462194206Ssimonany specific CA and does not intend to set up such a policy. Deciding 463194206Ssimonabout which CAs to support is up to application developers or 464194206Ssimonadministrators. 465194206Ssimon 466194206SsimonOther projects do have other policies so you can for example extract the CA 467194206Ssimonbundle used by Mozilla and/or modssl as described in this article: 468194206Ssimon 469216166Ssimon <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html> 470194206Ssimon 471194206Ssimon 47276866Skris[BUILD] ======================================================================= 47376866Skris 47459191Skris* Why does the linker complain about undefined symbols? 47559191Skris 47659191SkrisMaybe the compilation was interrupted, and make doesn't notice that 47759191Skrissomething is missing. Run "make clean; make". 47859191Skris 47959191SkrisIf you used ./Configure instead of ./config, make sure that you 48059191Skrisselected the right target. File formats may differ slightly between 48159191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 48259191Skris 48359191SkrisIn case you get errors about the following symbols, use the config 48459191Skrisoption "no-asm", as described in INSTALL: 48559191Skris 48659191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 48759191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 48859191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 48959191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 49059191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 49159191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 49259191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 49359191Skris 49459191SkrisIf none of these helps, you may want to try using the current snapshot. 49559191SkrisIf the problem persists, please submit a bug report. 49659191Skris 49759191Skris 49876866Skris* Why does the OpenSSL test fail with "bc: command not found"? 49959191Skris 50076866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 50176866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 50259191Skris 50359191Skris 50476866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 50559191Skris 50676866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 50776866Skriswhen you run the test suite (using "make test"). The message returned is 50876866Skris"bc: 1 not implemented". 50959191Skris 51076866SkrisThe best way to deal with this is to find another implementation of bc 511216166Ssimonand compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 51276866Skrisfor download instructions) can be safely used, for example. 51376866Skris 51476866Skris 515109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 516109998Smarkm 517109998SmarkmOn some DG/ux versions, bc seems to have a too small stack for calculations 518109998Smarkmthat the OpenSSL bntest throws at it. This gets triggered when you run the 519109998Smarkmtest suite (using "make test"). The message returned is "bc: stack empty". 520109998Smarkm 521109998SmarkmThe best way to deal with this is to find another implementation of bc 522216166Ssimonand compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 523109998Smarkmfor download instructions) can be safely used, for example. 524109998Smarkm 525109998Smarkm 52689837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 52776866Skris 52889837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 52976866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 53076866Skrismemory to continue compilation.' As far as the tests have shown, this may be 53176866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 53276866Skristo build something, probably a table. The problem is clearly in the 53376866Skrisoptimization code, because if one eliminates optimization completely (-O0), 53476866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 53576866Skrismemory instead of 240MB or whatever one's limit is currently). 53676866Skris 53776866SkrisThere are three options to solve this problem: 53876866Skris 53976866Skris1. set your current data segment size soft limit higher. Experience shows 54076866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 54176866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 54276866Skriskbytes to set the limit to. 54376866Skris 54476866Skris2. If you have a hard limit that is lower than what you need and you can't 54576866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 54676866Skrislevel. This is however not a very nice thing to do for those who expect to 54776866Skrisget the best result from OpenSSL. A bit more complicated solution is the 54876866Skrisfollowing: 54976866Skris 55076866Skris----- snip:start ----- 551160814Ssimon make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 55276866Skris sed -e 's/ -O[0-9] / -O0 /'`" 55376866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 55476866Skris make 55576866Skris----- snip:end ----- 55676866Skris 55776866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 55876866Skrislevel chosen by the configuration process. When the above is done, do the 55976866Skristest and installation and you're set. 56076866Skris 561160814Ssimon3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 562160814Ssimonshould not be used and is not used in SSL/TLS nor any other recognized 563160814Ssimonprotocol in either case. 56476866Skris 565160814Ssimon 56676866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 56776866Skris 56876866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 56976866Skrisaway 'ar' and other development commands in directories that aren't in 57076866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 57176866Skrisquickest way to fix this is to do the following (it assumes you use sh 57276866Skrisor any sh-compatible shell): 57376866Skris 57476866Skris----- snip:start ----- 57576866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 57676866Skris----- snip:end ----- 57776866Skris 57876866Skrisand then redo the compilation. What you should really do is make sure 57976866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 58076866Skris'.profile' (again, assuming you use a sh-compatible shell). 58176866Skris 58276866Skris 58376866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 58476866Skris 58576866SkrisSometimes, you may get reports from VC++ command line (cl) that it 58676866Skriscan't find standard include files like stdio.h and other weirdnesses. 58776866SkrisOne possible cause is that the environment isn't correctly set up. 588111147SnectarTo solve that problem for VC++ versions up to 6, one should run 589111147SnectarVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 590111147Snectarinstallation directory (somewhere under 'Program Files'). For VC++ 591111147Snectarversion 7 (and up?), which is also called VS.NET, the file is called 592111147SnectarVSVARS32.BAT instead. 593111147SnectarThis needs to be done prior to running NMAKE, and the changes are only 594111147Snectarvalid for the current DOS session. 59576866Skris 59676866Skris 597100936Snectar* What is special about OpenSSL on Redhat? 598100936Snectar 599100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 600100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 601100936Snectaris disabled in this version. The same may apply to other Linux distributions. 602100936SnectarUsers may therefore wish to install more or all of the features left out. 603100936Snectar 604100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 605100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 606100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 607100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 608100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 609100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 610100936Snectar/lib/libcrypto.so.2 respectively). 611100936Snectar 612100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 613100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 614100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 615100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 616100936Snectaropenssl on each distribution never change the package version, only the 617100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 618100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 619100936Snectarrelevant updates in packages up to and including 0.9.6b. 620100936Snectar 621100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 622100936Snectarversion of Red Hat Linux. 623100936Snectar 624100936SnectarFYI: Patent numbers and expiry dates of US patents: 625100936SnectarMDC-2: 4,908,861 13/03/2007 626100936SnectarIDEA: 5,214,703 25/05/2010 627100936SnectarRC5: 5,724,428 03/03/2015 628100936Snectar 629100936Snectar 630109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 631109998Smarkm 632109998SmarkmIf the failure happens when trying to build the "openssl" binary, with 633109998Smarkma large number of undefined symbols, it's very probable that you have 634109998SmarkmOpenSSL 0.9.6b delivered with the operating system (you can find out by 635109998Smarkmrunning '/usr/bin/openssl version') and that you were trying to build 636109998SmarkmOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 637109998SmarkmMacOS X has a misfeature that's quite difficult to go around. 638109998SmarkmLook in the file PROBLEMS for a more detailed explanation and for possible 639109998Smarkmsolutions. 640109998Smarkm 641109998Smarkm 642100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 643100936Snectar 644100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 645100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 646100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 647100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 648100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 649100936Snectargo around and has linked the programs "openssl" and the test programs 650100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 651100936Snectarlibraries you just built. 652100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 653100936Snectarsolutions. 654100936Snectar 655109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 656109998Smarkm 657109998SmarkmFailure in BN_sqr test is most likely caused by a failure to configure the 658109998Smarkmtoolkit for current platform or lack of support for the platform in question. 659109998SmarkmRun './config -t' and './apps/openssl version -p'. Do these platform 660109998Smarkmidentifiers match? If they don't, then you most likely failed to run 661109998Smarkm./config and you're hereby advised to do so before filing a bug report. 662109998SmarkmIf ./config itself fails to run, then it's most likely problem with your 663109998Smarkmlocal environment and you should turn to your system administrator (or 664109998Smarkmsimilar). If identifiers match (and/or no alternative identifier is 665109998Smarkmsuggested by ./config script), then the platform is unsupported. There might 666109998Smarkmor might not be a workaround. Most notably on SPARC64 platforms with GNU 667109998SmarkmC compiler you should be able to produce a working build by running 668109998Smarkm'./config -m32'. I understand that -m32 might not be what you want/need, 669109998Smarkmbut the build should be operational. For further details turn to 670109998Smarkm<openssl-dev@openssl.org>. 671109998Smarkm 672109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 673109998Smarkm 674109998SmarkmAs of 0.9.7 assembler routines were overhauled for position independence 675109998Smarkmof the machine code, which is essential for shared library support. For 676109998Smarkmsome reason OpenBSD is equipped with an out-of-date GNU assembler which 677109998Smarkmfinds the new code offensive. To work around the problem, configure with 678111147Snectarno-asm (and sacrifice a great deal of performance) or patch your assembler 679111147Snectaraccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 680109998SmarkmFor your convenience a pre-compiled replacement binary is provided at 681111147Snectar<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 682111147SnectarReportedly elder *BSD a.out platforms also suffer from this problem and 683111147Snectarremedy should be same. Provided binary is statically linked and should be 684111147Snectarworking across wider range of *BSD branches, not just OpenBSD. 685109998Smarkm 686160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 687160814Ssimon 688160814SsimonIf the test program in question fails withs SIGILL, Illegal Instruction 689160814Ssimonexception, then you more than likely to run SSE2-capable CPU, such as 690160814SsimonIntel P4, under control of kernel which does not support SSE2 691160814Ssimoninstruction extentions. See accompanying INSTALL file and 692160814SsimonOPENSSL_ia32cap(3) documentation page for further information. 693160814Ssimon 694160814Ssimon* Why does compiler fail to compile sha512.c? 695160814Ssimon 696160814SsimonOpenSSL SHA-512 implementation depends on compiler support for 64-bit 697160814Ssimoninteger type. Few elder compilers [ULTRIX cc, SCO compiler to mention a 698160814Ssimoncouple] lack support for this and therefore are incapable of compiling 699160814Ssimonthe module in question. The recommendation is to disable SHA-512 by 700160814Ssimonadding no-sha512 to ./config [or ./Configure] command line. Another 701160814Ssimonpossible alternative might be to switch to GCC. 702160814Ssimon 703160814Ssimon* Test suite still fails, what to do? 704160814Ssimon 705160814SsimonAnother common reason for failure to complete some particular test is 706160814Ssimonsimply bad code generated by a buggy component in toolchain or deficiency 707160814Ssimonin run-time environment. There are few cases documented in PROBLEMS file, 708160814Ssimonconsult it for possible workaround before you beat the drum. Even if you 709160814Ssimondon't find solution or even mention there, do reserve for possibility of 710160814Ssimona compiler bug. Compiler bugs might appear in rather bizarre ways, they 711160814Ssimonnever make sense, and tend to emerge when you least expect them. In order 712160814Ssimonto identify one, drop optimization level, e.g. by editing CFLAG line in 713160814Ssimontop-level Makefile, recompile and re-run the test. 714160814Ssimon 715216166Ssimon* I think I've found a bug, what should I do? 716216166Ssimon 717216166SsimonIf you are a new user then it is quite likely you haven't found a bug and 718216166Ssimonsomething is happening you aren't familiar with. Check this FAQ, the associated 719216166Ssimondocumentation and the mailing lists for similar queries. If you are still 720216166Ssimonunsure whether it is a bug or not submit a query to the openssl-users mailing 721216166Ssimonlist. 722216166Ssimon 723216166Ssimon 724216166Ssimon* I'm SURE I've found a bug, how do I report it? 725216166Ssimon 726216166SsimonBug reports with no security implications should be sent to the request 727216166Ssimontracker. This can be done by mailing the report to <rt@openssl.org> (or its 728216166Ssimonalias <openssl-bugs@openssl.org>), please note that messages sent to the 729216166Ssimonrequest tracker also appear in the public openssl-dev mailing list. 730216166Ssimon 731216166SsimonThe report should be in plain text. Any patches should be sent as 732216166Ssimonplain text attachments because some mailers corrupt patches sent inline. 733216166SsimonIf your issue affects multiple versions of OpenSSL check any patches apply 734216166Ssimoncleanly and, if possible include patches to each affected version. 735216166Ssimon 736216166SsimonThe report should be given a meaningful subject line briefly summarising the 737216166Ssimonissue. Just "bug in OpenSSL" or "bug in OpenSSL 0.9.8n" is not very helpful. 738216166Ssimon 739216166SsimonBy sending reports to the request tracker the bug can then be given a priority 740216166Ssimonand assigned to the appropriate maintainer. The history of discussions can be 741216166Ssimonaccessed and if the issue has been addressed or a reason why not. If patches 742216166Ssimonare only sent to openssl-dev they can be mislaid if a team member has to 743216166Ssimonwade through months of old messages to review the discussion. 744216166Ssimon 745216166SsimonSee also <URL: http://www.openssl.org/support/rt.html> 746216166Ssimon 747216166Ssimon 748216166Ssimon* I've found a security issue, how do I report it? 749216166Ssimon 750216166SsimonIf you think your bug has security implications then please send it to 751216166Ssimonopenssl-security@openssl.org if you don't get a prompt reply at least 752216166Ssimonacknowledging receipt then resend or mail it directly to one of the 753216166Ssimonmore active team members (e.g. Steve). 754216166Ssimon 75576866Skris[PROG] ======================================================================== 75676866Skris 75776866Skris* Is OpenSSL thread-safe? 75876866Skris 75976866SkrisYes (with limitations: an SSL connection may not concurrently be used 76076866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 76176866Skrisautomatically uses the multi-threaded versions of the standard 76276866Skrislibraries. If your platform is not one of these, consult the INSTALL 76376866Skrisfile. 76476866Skris 76576866SkrisMulti-threaded applications must provide two callback functions to 766162911SsimonOpenSSL by calling CRYPTO_set_locking_callback() and 767215697SsimonCRYPTO_set_id_callback(), for all versions of OpenSSL up to and 768215697Ssimonincluding 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback() 769215697Ssimonand associated APIs are deprecated by CRYPTO_THREADID_set_callback() 770215697Ssimonand friends. This is described in the threads(3) manpage. 77176866Skris 77259191Skris* I've compiled a program under Windows and it crashes: why? 77359191Skris 77489837SkrisThis is usually because you've missed the comment in INSTALL.W32. 77589837SkrisYour application must link against the same version of the Win32 77689837SkrisC-Runtime against which your openssl libraries were linked. The 77789837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 77859191Skris 77989837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 78089837Skrismany cases, your new project most likely defaulted to "Debug 78189837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 78289837Skrisprogram will crash, typically on the first BIO related read or write 78389837Skrisoperation. 78459191Skris 78589837SkrisFor each of the six possible link stage configurations within Win32, 78689837Skrisyour application must link against the same by which OpenSSL was 78789837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 78889837Skrisby: 78989837Skris 790160814Ssimon 1. Select Settings... from the Project Menu. 791160814Ssimon 2. Select the C/C++ Tab. 792160814Ssimon 3. Select "Code Generation from the "Category" drop down list box 793160814Ssimon 4. Select the Appropriate library (see table below) from the "Use 79489837Skris run-time library" drop down list box. Perform this step for both 79589837Skris your debug and release versions of your application (look at the 79689837Skris top left of the settings panel to change between the two) 79789837Skris 79889837Skris Single Threaded /ML - MS VC++ often defaults to 79989837Skris this for the release 80089837Skris version of a new project. 80189837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 80289837Skris this for the debug version 80389837Skris of a new project. 80489837Skris Multithreaded /MT 80589837Skris Debug Multithreaded /MTd 80689837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 80789837Skris Debug Multithreaded DLL /MDd 80889837Skris 80989837SkrisNote that debug and release libraries are NOT interchangeable. If you 81089837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 81189837Skris 812160814SsimonAs per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL 813160814Ssimon.DLLs compiled with some specific run-time option [we insist on the 814160814Ssimondefault /MD] can be deployed with application compiled with different 815160814Ssimonoption or even different compiler. But there is a catch! Instead of 816160814Ssimonre-compiling OpenSSL toolkit, as you would have to with prior versions, 817160814Ssimonyou have to compile small C snippet with compiler and/or options of 818160814Ssimonyour choice. The snippet gets installed as 819160814Ssimon<install-root>/include/openssl/applink.c and should be either added to 820160814Ssimonyour application project or simply #include-d in one [and only one] 821160814Ssimonof your application source files. Failure to link this shim module 822160814Ssimoninto your application manifests itself as fatal "no OPENSSL_Applink" 823160814Ssimonrun-time error. An explicit reminder is due that in this situation 824160814Ssimon[mixing compiler options] it is as important to add CRYPTO_malloc_init 825160814Ssimonprior first call to OpenSSL. 82689837Skris 82768651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 82868651Skris 82968651SkrisYou have two options. You can either use a memory BIO in conjunction 830160814Ssimonwith the i2d_*_bio() or d2i_*_bio() functions or you can use the 831160814Ssimoni2d_*(), d2i_*() functions directly. Since these are often the 83268651Skriscause of grief here are some code fragments using PKCS7 as an example: 83368651Skris 834160814Ssimon unsigned char *buf, *p; 835160814Ssimon int len; 83668651Skris 837160814Ssimon len = i2d_PKCS7(p7, NULL); 838160814Ssimon buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 839160814Ssimon p = buf; 840160814Ssimon i2d_PKCS7(p7, &p); 84168651Skris 84268651SkrisAt this point buf contains the len bytes of the DER encoding of 84368651Skrisp7. 84468651Skris 84568651SkrisThe opposite assumes we already have len bytes in buf: 84668651Skris 847160814Ssimon unsigned char *p; 848160814Ssimon p = buf; 849160814Ssimon p7 = d2i_PKCS7(NULL, &p, len); 85068651Skris 85168651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 85268651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 85368651Skrisinformation. 85468651Skris 85568651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 85668651Skrisincrement the passed pointer so it is ready to read or write the next 85768651Skrisstructure. This is often a cause of problems: without the temporary 85868651Skrisvariable the buffer pointer is changed to point just after the data 85968651Skristhat has been read or written. This may well be uninitialized data 86068651Skrisand attempts to free the buffer will have unpredictable results 86168651Skrisbecause it no longer points to the same address. 86268651Skris 86368651Skris 864142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 865142425Snectar 866142425SnectarThe short answer is yes, because DER is a special case of BER and OpenSSL 867142425SnectarASN1 decoders can process BER. 868142425Snectar 869142425SnectarThe longer answer is that ASN1 structures can be encoded in a number of 870142425Snectardifferent ways. One set of ways is the Basic Encoding Rules (BER) with various 871142425Snectarpermissible encodings. A restriction of BER is the Distinguished Encoding 872142425SnectarRules (DER): these uniquely specify how a given structure is encoded. 873142425Snectar 874142425SnectarTherefore, because DER is a special case of BER, DER is an acceptable encoding 875142425Snectarfor BER. 876142425Snectar 877142425Snectar 87868651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 87968651Skris 88068651SkrisThis usually happens when you try compiling something using the PKCS#12 88168651Skrismacros with a C++ compiler. There is hardly ever any need to use the 88268651SkrisPKCS#12 macros in a program, it is much easier to parse and create 88368651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 88468651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 88568651Skris'pkcs12' application has to use the macros because it prints out 88668651Skrisdebugging information. 88768651Skris 88868651Skris 88959191Skris* I've called <some function> and it fails, why? 89059191Skris 89168651SkrisBefore submitting a report or asking in one of the mailing lists, you 89268651Skrisshould try to determine the cause. In particular, you should call 89359191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 89468651Skrisand see if the message helps. Note that the problem may occur earlier 89568651Skristhan you think -- you should check for errors after every call where 89668651Skrisit is possible, otherwise the actual problem may be hidden because 89768651Skrissome OpenSSL functions clear the error state. 89859191Skris 89959191Skris 90059191Skris* I just get a load of numbers for the error output, what do they mean? 90159191Skris 90259191SkrisThe actual format is described in the ERR_print_errors() manual page. 90359191SkrisYou should call the function ERR_load_crypto_strings() before hand and 90459191Skristhe message will be output in text form. If you can't do this (for example 90559191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 90659191Skriscode itself (the hex digits after the second colon). 90759191Skris 90859191Skris 90959191Skris* Why do I get errors about unknown algorithms? 91059191Skris 911194206SsimonThe cause is forgetting to load OpenSSL's table of algorithms with 912194206SsimonOpenSSL_add_all_algorithms(). See the manual page for more information. This 913194206Ssimoncan cause several problems such as being unable to read in an encrypted 914194206SsimonPEM file, unable to decrypt a PKCS#12 file or signature failure when 915194206Ssimonverifying certificates. 91659191Skris 91759191Skris* Why can't the OpenSSH configure script detect OpenSSL? 91859191Skris 91989837SkrisSeveral reasons for problems with the automatic detection exist. 92089837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 92189837SkrisSometimes the distribution has installed an older version in the system 92289837Skrislocations that is detected instead of a new one installed. The OpenSSL 92389837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 92489837SkrisPermissions might be wrong. 92559191Skris 92689837SkrisThe general answer is to check the config.log file generated when running 92789837Skristhe OpenSSH configure script. It should contain the detailed information 92889837Skrison why the OpenSSL library was not detected or considered incompatible. 92968651Skris 930120631Snectar 93176866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 93268651Skris 93376866SkrisYes; make sure to read the SSL_get_error(3) manual page! 93468651Skris 93576866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 93676866Skristhe underlying transport or that SSL_write() will just write to it -- 93776866Skrisit is also possible that SSL_write() cannot do any useful work until 93876866Skristhere is data to read, or that SSL_read() cannot do anything until it 93976866Skrisis possible to send data. One reason for this is that the peer may 94076866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 94176866Skrisrequiring a bi-directional message exchange; both SSL_read() and 94276866SkrisSSL_write() will try to continue any pending handshake. 94368651Skris 94468651Skris 94579998Skris* Why doesn't my server application receive a client certificate? 94679998Skris 94779998SkrisDue to the TLS protocol definition, a client will only send a certificate, 94889837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 94979998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 95079998Skris 95179998Skris 952109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 953109998Smarkm 954109998SmarkmFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 955109998Smarkmversions, uniqueIdentifier was incorrectly used for X.509 certificates. 956109998SmarkmThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 957109998SmarkmChange your code to use the new name when compiling against OpenSSL 0.9.7. 958109998Smarkm 959109998Smarkm 960142425Snectar* I think I've detected a memory leak, is this a bug? 961142425Snectar 962142425SnectarIn most cases the cause of an apparent memory leak is an OpenSSL internal table 963142425Snectarthat is allocated when an application starts up. Since such tables do not grow 964142425Snectarin size over time they are harmless. 965142425Snectar 966142425SnectarThese internal tables can be freed up when an application closes using various 967160814Ssimonfunctions. Currently these include following: 968142425Snectar 969160814SsimonThread-local cleanup functions: 970142425Snectar 971160814Ssimon ERR_remove_state() 972160814Ssimon 973160814SsimonApplication-global cleanup functions that are aware of usage (and therefore 974160814Ssimonthread-safe): 975160814Ssimon 976160814Ssimon ENGINE_cleanup() and CONF_modules_unload() 977160814Ssimon 978160814Ssimon"Brutal" (thread-unsafe) Application-global cleanup functions: 979160814Ssimon 980160814Ssimon ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). 981160814Ssimon 982160814Ssimon 983194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 984194206Ssimon 985194206SsimonWhen OpenSSL's PRNG routines are called to generate random numbers the supplied 986194206Ssimonbuffer contents are mixed into the entropy pool: so it technically does not 987194206Ssimonmatter whether the buffer is initialized at this point or not. Valgrind (and 988194206Ssimonother test tools) will complain about this. When using Valgrind, make sure the 989194206SsimonOpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) 990194206Ssimonto get rid of these warnings. 991194206Ssimon 992194206Ssimon 993194206Ssimon* Why doesn't a memory BIO work when a file does? 994194206Ssimon 995194206SsimonThis can occur in several cases for example reading an S/MIME email message. 996194206SsimonThe reason is that a memory BIO can do one of two things when all the data 997194206Ssimonhas been read from it. 998194206Ssimon 999194206SsimonThe default behaviour is to indicate that no more data is available and that 1000194206Ssimonthe call should be retried, this is to allow the application to fill up the BIO 1001194206Ssimonagain if necessary. 1002194206Ssimon 1003194206SsimonAlternatively it can indicate that no more data is available and that EOF has 1004194206Ssimonbeen reached. 1005194206Ssimon 1006194206SsimonIf a memory BIO is to behave in the same way as a file this second behaviour 1007194206Ssimonis needed. This must be done by calling: 1008194206Ssimon 1009194206Ssimon BIO_set_mem_eof_return(bio, 0); 1010194206Ssimon 1011194206SsimonSee the manual pages for more details. 1012194206Ssimon 1013194206Ssimon 1014215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 1015215697Ssimon 1016215697SsimonThese are defined and implemented by macros of the form: 1017215697Ssimon 1018215697Ssimon 1019215697Ssimon DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) 1020215697Ssimon 1021215697SsimonThe implementation passes an ASN1 "template" defining the structure into an 1022215697SsimonASN1 interpreter using generalised functions such as ASN1_item_d2i(). 1023215697Ssimon 1024215697Ssimon 102576866Skris=============================================================================== 1026