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? 13237657Sjkim* How does the versioning scheme work? 1476866Skris 1576866Skris[LEGAL] Legal questions 1676866Skris 1759191Skris* Do I need patent licenses to use OpenSSL? 1876866Skris* Can I use OpenSSL with GPL software? 1976866Skris 2076866Skris[USER] Questions on using the OpenSSL applications 2176866Skris 2259191Skris* Why do I get a "PRNG not seeded" error message? 2379998Skris* Why do I get an "unable to write 'random state'" error message? 2459191Skris* How do I create certificates or certificate requests? 2559191Skris* Why can't I create certificate requests? 2659191Skris* Why does <SSL program> fail with a certificate verify error? 2768651Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 2859191Skris* How can I create DSA certificates? 2959191Skris* Why can't I make an SSL connection using a DSA certificate? 3068651Skris* How can I remove the passphrase on a private key? 3176866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 3276866Skris* Why does my browser give a warning about a mismatched hostname? 3389837Skris* How do I install a CA certificate into a browser? 34109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 35160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 36194206Ssimon* Why does OpenSSL set the authority key identifier extension incorrectly? 37194206Ssimon* How can I set up a bundle of commercial root CA certificates? 3876866Skris 3976866Skris[BUILD] Questions about building and testing OpenSSL 4076866Skris 4176866Skris* Why does the linker complain about undefined symbols? 4268651Skris* Why does the OpenSSL test fail with "bc: command not found"? 4368651Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 44109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 4589837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 4668651Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 4776866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 48100936Snectar* What is special about OpenSSL on Redhat? 49109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 50100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 51109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 52109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 53160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 54160814Ssimon* Why does compiler fail to compile sha512.c? 55160814Ssimon* Test suite still fails, what to do? 56216166Ssimon* I think I've found a bug, what should I do? 57216166Ssimon* I'm SURE I've found a bug, how do I report it? 58216166Ssimon* I've found a security issue, how do I report it? 5959191Skris 6076866Skris[PROG] Questions about programming with OpenSSL 6159191Skris 6276866Skris* Is OpenSSL thread-safe? 6376866Skris* I've compiled a program under Windows and it crashes: why? 6476866Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 65142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 6676866Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 6776866Skris* I've called <some function> and it fails, why? 6876866Skris* I just get a load of numbers for the error output, what do they mean? 6976866Skris* Why do I get errors about unknown algorithms? 7076866Skris* Why can't the OpenSSH configure script detect OpenSSL? 7176866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 7279998Skris* Why doesn't my server application receive a client certificate? 73109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 74142425Snectar* I think I've detected a memory leak, is this a bug? 75194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 76194206Ssimon* Why doesn't a memory BIO work when a file does? 77215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 7876866Skris 7976866Skris=============================================================================== 8076866Skris 8176866Skris[MISC] ======================================================================== 8276866Skris 8359191Skris* Which is the current version of OpenSSL? 8459191Skris 8559191SkrisThe current version is available from <URL: http://www.openssl.org>. 86246772SjkimOpenSSL 1.0.1e was released on Feb 11th, 2013. 8759191Skris 8859191SkrisIn addition to the current stable release, you can also access daily 8959191Skrissnapshots of the OpenSSL development version at <URL: 90246772Sjkimftp://ftp.openssl.org/snapshot/>, or get it by anonymous Git access. 9159191Skris 9259191Skris 9359191Skris* Where is the documentation? 9459191Skris 9559191SkrisOpenSSL is a library that provides cryptographic functionality to 9659191Skrisapplications such as secure web servers. Be sure to read the 9759191Skrisdocumentation of the application you want to use. The INSTALL file 9859191Skrisexplains how to install this library. 9959191Skris 10059191SkrisOpenSSL includes a command line utility that can be used to perform a 10159191Skrisvariety of cryptographic functions. It is described in the openssl(1) 102215697Ssimonmanpage. Documentation for developers is currently being written. Many 103215697Ssimonmanual pages are available; overviews over libcrypto and 10459191Skrislibssl are given in the crypto(3) and ssl(3) manpages. 10559191Skris 10659191SkrisThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 10759191Skrisdifferent directory if you specified one as described in INSTALL). 10859191SkrisIn addition, you can read the most current versions at 109215697Ssimon<URL: http://www.openssl.org/docs/>. Note that the online documents refer 110215697Ssimonto the very latest development versions of OpenSSL and may include features 111215697Ssimonnot present in released versions. If in doubt refer to the documentation 112237657Sjkimthat came with the version of OpenSSL you are using. The pod format 113237657Sjkimdocumentation is included in each OpenSSL distribution under the docs 114237657Sjkimdirectory. 11559191Skris 11659191SkrisThere is some documentation about certificate extensions and PKCS#12 11759191Skrisin doc/openssl.txt 11859191Skris 11959191SkrisThe original SSLeay documentation is included in OpenSSL as 12059191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 12159191Skrishelp, but please note that it reflects the obsolete version SSLeay 12259191Skris0.6.6. 12359191Skris 12459191Skris 12559191Skris* How can I contact the OpenSSL developers? 12659191Skris 12759191SkrisThe README file describes how to submit bug reports and patches to 12859191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 12959191Skris<URL: http://www.openssl.org>. 13059191Skris 13159191Skris 13276866Skris* Where can I get a compiled version of OpenSSL? 13376866Skris 134127128SnectarYou can finder pointers to binary distributions in 135216166Ssimon<URL: http://www.openssl.org/related/binaries.html> . 136127128Snectar 13776866SkrisSome applications that use OpenSSL are distributed in binary form. 13876866SkrisWhen using such an application, you don't need to install OpenSSL 13976866Skrisyourself; the application will include the required parts (e.g. DLLs). 14076866Skris 141127128SnectarIf you want to build OpenSSL on a Windows system and you don't have 14276866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 14376866Skrison how to obtain and install the free GNU C compiler. 14476866Skris 14576866SkrisA number of Linux and *BSD distributions include OpenSSL. 14676866Skris 14776866Skris 14876866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 14976866Skris 15076866Skrisautoconf will probably be used in future OpenSSL versions. If it was 15176866Skrisless Unix-centric, it might have been used much earlier. 15276866Skris 15389837Skris* What is an 'engine' version? 15476866Skris 15589837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 15689837Skrishardware. This was realized in a special release '0.9.6-engine'. With 157160814Ssimonversion 0.9.7 the changes were merged into the main development line, 158160814Ssimonso that the special release is no longer necessary. 15989837Skris 160109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 161109998Smarkm 162109998SmarkmWe provide MD5 digests and ASC signatures of each tarball. 163109998SmarkmUse MD5 to check that a tarball from a mirror site is identical: 164109998Smarkm 165109998Smarkm md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 166109998Smarkm 167109998SmarkmYou can check authenticity using pgp or gpg. You need the OpenSSL team 168160814Ssimonmember public key used to sign it (download it from a key server, see a 169160814Ssimonlist of keys at <URL: http://www.openssl.org/about/>). Then 170109998Smarkmjust do: 171109998Smarkm 172109998Smarkm pgp TARBALL.asc 173109998Smarkm 174237657Sjkim* How does the versioning scheme work? 175237657Sjkim 176237657SjkimAfter the release of OpenSSL 1.0.0 the versioning scheme changed. Letter 177237657Sjkimreleases (e.g. 1.0.1a) can only contain bug and security fixes and no 178237657Sjkimnew features. Minor releases change the last number (e.g. 1.0.2) and 179237657Sjkimcan contain new features that retain binary compatibility. Changes to 180237657Sjkimthe middle number are considered major releases and neither source nor 181237657Sjkimbinary compatibility is guaranteed. 182237657Sjkim 183237657SjkimTherefore the answer to the common question "when will feature X be 184237657Sjkimbackported to OpenSSL 1.0.0/0.9.8?" is "never" but it could appear 185237657Sjkimin the next minor release. 186237657Sjkim 18776866Skris[LEGAL] ======================================================================= 18876866Skris 18959191Skris* Do I need patent licenses to use OpenSSL? 19059191Skris 19159191SkrisThe patents section of the README file lists patents that may apply to 19259191Skrisyou if you want to use OpenSSL. For information on intellectual 19359191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 19459191Skrisoffer legal advice. 19559191Skris 196160814SsimonYou can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using 197160814Ssimon ./config no-idea no-mdc2 no-rc5 19859191Skris 19959191Skris 20076866Skris* Can I use OpenSSL with GPL software? 20159191Skris 20276866SkrisOn many systems including the major Linux and BSD distributions, yes (the 20376866SkrisGPL does not place restrictions on using libraries that are part of the 20476866Skrisnormal operating system distribution). 20559191Skris 20676866SkrisOn other systems, the situation is less clear. Some GPL software copyright 20776866Skrisholders claim that you infringe on their rights if you use OpenSSL with 20876866Skristheir software on operating systems that don't normally include OpenSSL. 20959191Skris 21076866SkrisIf you develop open source software that uses OpenSSL, you may find it 21189837Skrisuseful to choose an other license than the GPL, or state explicitly that 21276866Skris"This program is released under the GPL with the additional exemption that 21376866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 21476866SkrisGPL software developed by others, you may want to ask the copyright holder 21576866Skrisfor permission to use their software with OpenSSL. 21659191Skris 21776866Skris 21876866Skris[USER] ======================================================================== 21976866Skris 22059191Skris* Why do I get a "PRNG not seeded" error message? 22159191Skris 22259191SkrisCryptographic software needs a source of unpredictable data to work 22359191Skriscorrectly. Many open source operating systems provide a "randomness 224111147Snectardevice" (/dev/urandom or /dev/random) that serves this purpose. 225111147SnectarAll OpenSSL versions try to use /dev/urandom by default; starting with 226111147Snectarversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 227111147Snectaravailable. 22859191Skris 229111147SnectarOn other systems, applications have to call the RAND_add() or 230111147SnectarRAND_seed() function with appropriate data before generating keys or 231111147Snectarperforming public key encryption. (These functions initialize the 232111147Snectarpseudo-random number generator, PRNG.) Some broken applications do 233111147Snectarnot do this. As of version 0.9.5, the OpenSSL functions that need 234111147Snectarrandomness report an error if the random number generator has not been 235111147Snectarseeded with at least 128 bits of randomness. If this error occurs and 236111147Snectaris not discussed in the documentation of the application you are 237111147Snectarusing, please contact the author of that application; it is likely 238111147Snectarthat it never worked correctly. OpenSSL 0.9.5 and later make the 239111147Snectarerror visible by refusing to perform potentially insecure encryption. 24059191Skris 241111147SnectarIf you are using Solaris 8, you can add /dev/urandom and /dev/random 242111147Snectardevices by installing patch 112438 (Sparc) or 112439 (x86), which are 243111147Snectaravailable via the Patchfinder at <URL: http://sunsolve.sun.com> 244111147Snectar(Solaris 9 includes these devices by default). For /dev/random support 245111147Snectarfor earlier Solaris versions, see Sun's statement at 246111147Snectar<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 247111147Snectar(the SUNWski package is available in patch 105710). 248111147Snectar 24979998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 25079998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 25179998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 25279998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 25379998Skris/etc/entropy. 25459191Skris 25579998SkrisMost components of the openssl command line utility automatically try 25679998Skristo seed the random number generator from a file. The name of the 25779998Skrisdefault seeding file is determined as follows: If environment variable 25879998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 25979998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 26079998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 26179998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 26279998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 26389837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 26479998SkrisWindows systems if the environment variable has not been set. 26559191Skris 26679998SkrisIf the default seeding file does not exist or is too short, the "PRNG 26779998Skrisnot seeded" error message may occur. 26859191Skris 26979998SkrisThe openssl command line utility will write back a new state to the 27079998Skrisdefault seeding file (and create this file if necessary) unless 27179998Skristhere was no sufficient seeding. 27279998Skris 27379998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 27479998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 27579998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 27679998SkrisOpenSSL command line tools. Applications using the OpenSSL library 27779998Skrisprovide their own configuration options to specify the entropy source, 27879998Skrisplease check out the documentation coming the with application. 27979998Skris 28059191Skris 28179998Skris* Why do I get an "unable to write 'random state'" error message? 28279998Skris 28379998Skris 28479998SkrisSometimes the openssl command line utility does not abort with 28579998Skrisa "PRNG not seeded" error message, but complains that it is 28679998Skris"unable to write 'random state'". This message refers to the 28779998Skrisdefault seeding file (see previous answer). A possible reason 28879998Skrisis that no default filename is known because neither RANDFILE 28979998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 29079998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 29179998Skris 29279998Skris 29376866Skris* How do I create certificates or certificate requests? 29476866Skris 29576866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 29676866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 29776866Skrisout the manual pages for the individual utilities and the certificate 298237657Sjkimextensions documentation (in ca(1), req(1), x509v3_config(5) ) 29976866Skris 30076866Skris 30176866Skris* Why can't I create certificate requests? 30276866Skris 30376866SkrisYou typically get the error: 30476866Skris 30576866Skris unable to find 'distinguished_name' in config 30676866Skris problems making Certificate Request 30776866Skris 30876866SkrisThis is because it can't find the configuration file. Check out the 30976866SkrisDIAGNOSTICS section of req(1) for more information. 31076866Skris 31176866Skris 31276866Skris* Why does <SSL program> fail with a certificate verify error? 31376866Skris 31476866SkrisThis problem is usually indicated by log messages saying something like 31576866Skris"unable to get local issuer certificate" or "self signed certificate". 31676866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 31776866Skristhis typically means that the CA certificate must be placed in a directory 31876866Skrisor file and the relevant program configured to read it. The OpenSSL program 31976866Skris'verify' behaves in a similar way and issues similar error messages: check 32076866Skristhe verify(1) program manual page for more information. 32176866Skris 32276866Skris 32376866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 32476866Skris 32576866SkrisThis is almost certainly because you are using an old "export grade" browser 32676866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 32776866Skrisciphers. 32876866Skris 32976866Skris 33076866Skris* How can I create DSA certificates? 33176866Skris 33276866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 33376866Skris 33476866Skris 33576866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 33676866Skris 33776866SkrisTypically you'll see a message saying there are no shared ciphers when 33876866Skristhe same setup works fine with an RSA certificate. There are two possible 33976866Skriscauses. The client may not support connections to DSA servers most web 34076866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 34176866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 34276866Skrishas not been supplied to the server. DH parameters can be created with the 34376866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 34476866Skrischeck the source to s_server in apps/s_server.c for an example. 34576866Skris 34676866Skris 34776866Skris* How can I remove the passphrase on a private key? 34876866Skris 34976866SkrisFirstly you should be really *really* sure you want to do this. Leaving 35076866Skrisa private key unencrypted is a major security risk. If you decide that 35176866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 35276866Skrisdsa(1) manual pages. 35376866Skris 35476866Skris 35576866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 35676866Skris 35776866SkrisWhat will typically happen is that when a server requests authentication 35876866Skrisit will either not include your certificate or tell you that you have 35976866Skrisno client certificates (Netscape) or present you with an empty list box 36076866Skris(MSIE). The reason for this is that when a server requests a client 36176866Skriscertificate it includes a list of CAs names which it will accept. Browsers 36276866Skriswill only let you select certificates from the list on the grounds that 36376866Skristhere is little point presenting a certificate which the server will 36476866Skrisreject. 36576866Skris 36676866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 36789837SkrisCA list". How you do this depends on the server software in uses. You can 36876866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 36976866Skris 37076866Skrisopenssl s_client -connect www.some.host:443 -prexit 37176866Skris 37276866SkrisIf your server only requests certificates on certain URLs then you may need 37376866Skristo manually issue an HTTP GET command to get the list when s_client connects: 37476866Skris 37576866SkrisGET /some/page/needing/a/certificate.html 37676866Skris 37776866SkrisIf your CA does not appear in the list then this confirms the problem. 37876866Skris 37976866Skris 38076866Skris* Why does my browser give a warning about a mismatched hostname? 38176866Skris 38276866SkrisBrowsers expect the server's hostname to match the value in the commonName 38376866Skris(CN) field of the certificate. If it does not then you get a warning. 38476866Skris 38576866Skris 38689837Skris* How do I install a CA certificate into a browser? 38789837Skris 38889837SkrisThe usual way is to send the DER encoded certificate to the browser as 38989837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 39089837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 39189837Skriscan import the certificate using the certificate import wizard. 39289837Skris 39389837SkrisYou can convert a certificate to DER form using the command: 39489837Skris 39589837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 39689837Skris 39789837SkrisOccasionally someone suggests using a command such as: 39889837Skris 39989837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 40089837Skris 40189837SkrisDO NOT DO THIS! This command will give away your CAs private key and 40289837Skrisreduces its security to zero: allowing anyone to forge certificates in 40389837Skriswhatever name they choose. 40489837Skris 405109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 40689837Skris 407109998SmarkmThe ways to print out the oneline format of the DN (Distinguished Name) have 408109998Smarkmbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 409109998Smarkminterface, the "-nameopt" option could be introduded. See the manual 410109998Smarkmpage of the "openssl x509" commandline tool for details. The old behaviour 411109998Smarkmhas however been left as default for the sake of compatibility. 412109998Smarkm 413160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 414160814Ssimon 415160814SsimonThe term "128 bit certificate" is a highly misleading marketing term. It does 416160814Ssimon*not* refer to the size of the public key in the certificate! A certificate 417160814Ssimoncontaining a 128 bit RSA key would have negligible security. 418160814Ssimon 419160814SsimonThere were various other names such as "magic certificates", "SGC 420160814Ssimoncertificates", "step up certificates" etc. 421160814Ssimon 422160814SsimonYou can't generally create such a certificate using OpenSSL but there is no 423160814Ssimonneed to any more. Nowadays web browsers using unrestricted strong encryption 424160814Ssimonare generally available. 425160814Ssimon 426194206SsimonWhen there were tight restrictions on the export of strong encryption 427160814Ssimonsoftware from the US only weak encryption algorithms could be freely exported 428160814Ssimon(initially 40 bit and then 56 bit). It was widely recognised that this was 429194206Ssimoninadequate. A relaxation of the rules allowed the use of strong encryption but 430160814Ssimononly to an authorised server. 431160814Ssimon 432160814SsimonTwo slighly different techniques were developed to support this, one used by 433160814SsimonNetscape was called "step up", the other used by MSIE was called "Server Gated 434160814SsimonCryptography" (SGC). When a browser initially connected to a server it would 435160814Ssimoncheck to see if the certificate contained certain extensions and was issued by 436160814Ssimonan authorised authority. If these test succeeded it would reconnect using 437160814Ssimonstrong encryption. 438160814Ssimon 439160814SsimonOnly certain (initially one) certificate authorities could issue the 440160814Ssimoncertificates and they generally cost more than ordinary certificates. 441160814Ssimon 442160814SsimonAlthough OpenSSL can create certificates containing the appropriate extensions 443160814Ssimonthe certificate would not come from a permitted authority and so would not 444160814Ssimonbe recognized. 445160814Ssimon 446160814SsimonThe export laws were later changed to allow almost unrestricted use of strong 447160814Ssimonencryption so these certificates are now obsolete. 448160814Ssimon 449160814Ssimon 450194206Ssimon* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? 451194206Ssimon 452194206SsimonIt doesn't: this extension is often the cause of confusion. 453194206Ssimon 454194206SsimonConsider a certificate chain A->B->C so that A signs B and B signs C. Suppose 455194206Ssimoncertificate C contains AKID. 456194206Ssimon 457194206SsimonThe purpose of this extension is to identify the authority certificate B. This 458194206Ssimoncan be done either by including the subject key identifier of B or its issuer 459194206Ssimonname and serial number. 460194206Ssimon 461194206SsimonIn this latter case because it is identifying certifcate B it must contain the 462194206Ssimonissuer name and serial number of B. 463194206Ssimon 464194206SsimonIt is often wrongly assumed that it should contain the subject name of B. If it 465194206Ssimondid this would be redundant information because it would duplicate the issuer 466194206Ssimonname of C. 467194206Ssimon 468194206Ssimon 469194206Ssimon* How can I set up a bundle of commercial root CA certificates? 470194206Ssimon 471194206SsimonThe OpenSSL software is shipped without any root CA certificate as the 472194206SsimonOpenSSL project does not have any policy on including or excluding 473194206Ssimonany specific CA and does not intend to set up such a policy. Deciding 474194206Ssimonabout which CAs to support is up to application developers or 475194206Ssimonadministrators. 476194206Ssimon 477194206SsimonOther projects do have other policies so you can for example extract the CA 478194206Ssimonbundle used by Mozilla and/or modssl as described in this article: 479194206Ssimon 480216166Ssimon <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html> 481194206Ssimon 482194206Ssimon 48376866Skris[BUILD] ======================================================================= 48476866Skris 48559191Skris* Why does the linker complain about undefined symbols? 48659191Skris 48759191SkrisMaybe the compilation was interrupted, and make doesn't notice that 48859191Skrissomething is missing. Run "make clean; make". 48959191Skris 49059191SkrisIf you used ./Configure instead of ./config, make sure that you 49159191Skrisselected the right target. File formats may differ slightly between 49259191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 49359191Skris 49459191SkrisIn case you get errors about the following symbols, use the config 49559191Skrisoption "no-asm", as described in INSTALL: 49659191Skris 49759191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 49859191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 49959191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 50059191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 50159191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 50259191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 50359191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 50459191Skris 50559191SkrisIf none of these helps, you may want to try using the current snapshot. 50659191SkrisIf the problem persists, please submit a bug report. 50759191Skris 50859191Skris 50976866Skris* Why does the OpenSSL test fail with "bc: command not found"? 51059191Skris 51176866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 51276866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 51359191Skris 51459191Skris 51576866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 51659191Skris 51776866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 51876866Skriswhen you run the test suite (using "make test"). The message returned is 51976866Skris"bc: 1 not implemented". 52059191Skris 52176866SkrisThe 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> 52376866Skrisfor download instructions) can be safely used, for example. 52476866Skris 52576866Skris 526109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 527109998Smarkm 528109998SmarkmOn some DG/ux versions, bc seems to have a too small stack for calculations 529109998Smarkmthat the OpenSSL bntest throws at it. This gets triggered when you run the 530109998Smarkmtest suite (using "make test"). The message returned is "bc: stack empty". 531109998Smarkm 532109998SmarkmThe best way to deal with this is to find another implementation of bc 533216166Ssimonand compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 534109998Smarkmfor download instructions) can be safely used, for example. 535109998Smarkm 536109998Smarkm 53789837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 53876866Skris 53989837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 54076866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 54176866Skrismemory to continue compilation.' As far as the tests have shown, this may be 54276866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 54376866Skristo build something, probably a table. The problem is clearly in the 54476866Skrisoptimization code, because if one eliminates optimization completely (-O0), 54576866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 54676866Skrismemory instead of 240MB or whatever one's limit is currently). 54776866Skris 54876866SkrisThere are three options to solve this problem: 54976866Skris 55076866Skris1. set your current data segment size soft limit higher. Experience shows 55176866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 55276866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 55376866Skriskbytes to set the limit to. 55476866Skris 55576866Skris2. If you have a hard limit that is lower than what you need and you can't 55676866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 55776866Skrislevel. This is however not a very nice thing to do for those who expect to 55876866Skrisget the best result from OpenSSL. A bit more complicated solution is the 55976866Skrisfollowing: 56076866Skris 56176866Skris----- snip:start ----- 562160814Ssimon make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 56376866Skris sed -e 's/ -O[0-9] / -O0 /'`" 56476866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 56576866Skris make 56676866Skris----- snip:end ----- 56776866Skris 56876866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 56976866Skrislevel chosen by the configuration process. When the above is done, do the 57076866Skristest and installation and you're set. 57176866Skris 572160814Ssimon3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 573160814Ssimonshould not be used and is not used in SSL/TLS nor any other recognized 574160814Ssimonprotocol in either case. 57576866Skris 576160814Ssimon 57776866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 57876866Skris 57976866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 58076866Skrisaway 'ar' and other development commands in directories that aren't in 58176866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 58276866Skrisquickest way to fix this is to do the following (it assumes you use sh 58376866Skrisor any sh-compatible shell): 58476866Skris 58576866Skris----- snip:start ----- 58676866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 58776866Skris----- snip:end ----- 58876866Skris 58976866Skrisand then redo the compilation. What you should really do is make sure 59076866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 59176866Skris'.profile' (again, assuming you use a sh-compatible shell). 59276866Skris 59376866Skris 59476866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 59576866Skris 59676866SkrisSometimes, you may get reports from VC++ command line (cl) that it 59776866Skriscan't find standard include files like stdio.h and other weirdnesses. 59876866SkrisOne possible cause is that the environment isn't correctly set up. 599111147SnectarTo solve that problem for VC++ versions up to 6, one should run 600111147SnectarVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 601111147Snectarinstallation directory (somewhere under 'Program Files'). For VC++ 602111147Snectarversion 7 (and up?), which is also called VS.NET, the file is called 603111147SnectarVSVARS32.BAT instead. 604111147SnectarThis needs to be done prior to running NMAKE, and the changes are only 605111147Snectarvalid for the current DOS session. 60676866Skris 60776866Skris 608100936Snectar* What is special about OpenSSL on Redhat? 609100936Snectar 610100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 611100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 612100936Snectaris disabled in this version. The same may apply to other Linux distributions. 613100936SnectarUsers may therefore wish to install more or all of the features left out. 614100936Snectar 615100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 616100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 617100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 618100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 619100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 620100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 621100936Snectar/lib/libcrypto.so.2 respectively). 622100936Snectar 623100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 624100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 625100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 626100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 627100936Snectaropenssl on each distribution never change the package version, only the 628100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 629100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 630100936Snectarrelevant updates in packages up to and including 0.9.6b. 631100936Snectar 632100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 633100936Snectarversion of Red Hat Linux. 634100936Snectar 635100936SnectarFYI: Patent numbers and expiry dates of US patents: 636100936SnectarMDC-2: 4,908,861 13/03/2007 637100936SnectarIDEA: 5,214,703 25/05/2010 638100936SnectarRC5: 5,724,428 03/03/2015 639100936Snectar 640100936Snectar 641109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 642109998Smarkm 643109998SmarkmIf the failure happens when trying to build the "openssl" binary, with 644109998Smarkma large number of undefined symbols, it's very probable that you have 645109998SmarkmOpenSSL 0.9.6b delivered with the operating system (you can find out by 646109998Smarkmrunning '/usr/bin/openssl version') and that you were trying to build 647109998SmarkmOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 648109998SmarkmMacOS X has a misfeature that's quite difficult to go around. 649109998SmarkmLook in the file PROBLEMS for a more detailed explanation and for possible 650109998Smarkmsolutions. 651109998Smarkm 652109998Smarkm 653100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 654100936Snectar 655100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 656100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 657100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 658100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 659100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 660100936Snectargo around and has linked the programs "openssl" and the test programs 661100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 662100936Snectarlibraries you just built. 663100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 664100936Snectarsolutions. 665100936Snectar 666109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 667109998Smarkm 668109998SmarkmFailure in BN_sqr test is most likely caused by a failure to configure the 669109998Smarkmtoolkit for current platform or lack of support for the platform in question. 670109998SmarkmRun './config -t' and './apps/openssl version -p'. Do these platform 671109998Smarkmidentifiers match? If they don't, then you most likely failed to run 672109998Smarkm./config and you're hereby advised to do so before filing a bug report. 673109998SmarkmIf ./config itself fails to run, then it's most likely problem with your 674109998Smarkmlocal environment and you should turn to your system administrator (or 675109998Smarkmsimilar). If identifiers match (and/or no alternative identifier is 676109998Smarkmsuggested by ./config script), then the platform is unsupported. There might 677109998Smarkmor might not be a workaround. Most notably on SPARC64 platforms with GNU 678109998SmarkmC compiler you should be able to produce a working build by running 679109998Smarkm'./config -m32'. I understand that -m32 might not be what you want/need, 680109998Smarkmbut the build should be operational. For further details turn to 681109998Smarkm<openssl-dev@openssl.org>. 682109998Smarkm 683109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 684109998Smarkm 685109998SmarkmAs of 0.9.7 assembler routines were overhauled for position independence 686109998Smarkmof the machine code, which is essential for shared library support. For 687109998Smarkmsome reason OpenBSD is equipped with an out-of-date GNU assembler which 688109998Smarkmfinds the new code offensive. To work around the problem, configure with 689111147Snectarno-asm (and sacrifice a great deal of performance) or patch your assembler 690111147Snectaraccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 691109998SmarkmFor your convenience a pre-compiled replacement binary is provided at 692111147Snectar<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 693111147SnectarReportedly elder *BSD a.out platforms also suffer from this problem and 694111147Snectarremedy should be same. Provided binary is statically linked and should be 695111147Snectarworking across wider range of *BSD branches, not just OpenBSD. 696109998Smarkm 697160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 698160814Ssimon 699160814SsimonIf the test program in question fails withs SIGILL, Illegal Instruction 700160814Ssimonexception, then you more than likely to run SSE2-capable CPU, such as 701160814SsimonIntel P4, under control of kernel which does not support SSE2 702160814Ssimoninstruction extentions. See accompanying INSTALL file and 703160814SsimonOPENSSL_ia32cap(3) documentation page for further information. 704160814Ssimon 705160814Ssimon* Why does compiler fail to compile sha512.c? 706160814Ssimon 707160814SsimonOpenSSL SHA-512 implementation depends on compiler support for 64-bit 708160814Ssimoninteger type. Few elder compilers [ULTRIX cc, SCO compiler to mention a 709160814Ssimoncouple] lack support for this and therefore are incapable of compiling 710160814Ssimonthe module in question. The recommendation is to disable SHA-512 by 711160814Ssimonadding no-sha512 to ./config [or ./Configure] command line. Another 712160814Ssimonpossible alternative might be to switch to GCC. 713160814Ssimon 714160814Ssimon* Test suite still fails, what to do? 715160814Ssimon 716160814SsimonAnother common reason for failure to complete some particular test is 717160814Ssimonsimply bad code generated by a buggy component in toolchain or deficiency 718160814Ssimonin run-time environment. There are few cases documented in PROBLEMS file, 719160814Ssimonconsult it for possible workaround before you beat the drum. Even if you 720160814Ssimondon't find solution or even mention there, do reserve for possibility of 721160814Ssimona compiler bug. Compiler bugs might appear in rather bizarre ways, they 722160814Ssimonnever make sense, and tend to emerge when you least expect them. In order 723160814Ssimonto identify one, drop optimization level, e.g. by editing CFLAG line in 724160814Ssimontop-level Makefile, recompile and re-run the test. 725160814Ssimon 726216166Ssimon* I think I've found a bug, what should I do? 727216166Ssimon 728216166SsimonIf you are a new user then it is quite likely you haven't found a bug and 729216166Ssimonsomething is happening you aren't familiar with. Check this FAQ, the associated 730216166Ssimondocumentation and the mailing lists for similar queries. If you are still 731216166Ssimonunsure whether it is a bug or not submit a query to the openssl-users mailing 732216166Ssimonlist. 733216166Ssimon 734216166Ssimon 735216166Ssimon* I'm SURE I've found a bug, how do I report it? 736216166Ssimon 737216166SsimonBug reports with no security implications should be sent to the request 738216166Ssimontracker. This can be done by mailing the report to <rt@openssl.org> (or its 739216166Ssimonalias <openssl-bugs@openssl.org>), please note that messages sent to the 740216166Ssimonrequest tracker also appear in the public openssl-dev mailing list. 741216166Ssimon 742216166SsimonThe report should be in plain text. Any patches should be sent as 743216166Ssimonplain text attachments because some mailers corrupt patches sent inline. 744216166SsimonIf your issue affects multiple versions of OpenSSL check any patches apply 745216166Ssimoncleanly and, if possible include patches to each affected version. 746216166Ssimon 747216166SsimonThe report should be given a meaningful subject line briefly summarising the 748216166Ssimonissue. Just "bug in OpenSSL" or "bug in OpenSSL 0.9.8n" is not very helpful. 749216166Ssimon 750216166SsimonBy sending reports to the request tracker the bug can then be given a priority 751216166Ssimonand assigned to the appropriate maintainer. The history of discussions can be 752216166Ssimonaccessed and if the issue has been addressed or a reason why not. If patches 753216166Ssimonare only sent to openssl-dev they can be mislaid if a team member has to 754216166Ssimonwade through months of old messages to review the discussion. 755216166Ssimon 756216166SsimonSee also <URL: http://www.openssl.org/support/rt.html> 757216166Ssimon 758216166Ssimon 759216166Ssimon* I've found a security issue, how do I report it? 760216166Ssimon 761216166SsimonIf you think your bug has security implications then please send it to 762216166Ssimonopenssl-security@openssl.org if you don't get a prompt reply at least 763216166Ssimonacknowledging receipt then resend or mail it directly to one of the 764216166Ssimonmore active team members (e.g. Steve). 765216166Ssimon 766264331SjkimNote that bugs only present in the openssl utility are not in general 767264331Sjkimconsidered to be security issues. 768264331Sjkim 76976866Skris[PROG] ======================================================================== 77076866Skris 77176866Skris* Is OpenSSL thread-safe? 77276866Skris 77376866SkrisYes (with limitations: an SSL connection may not concurrently be used 77476866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 77576866Skrisautomatically uses the multi-threaded versions of the standard 77676866Skrislibraries. If your platform is not one of these, consult the INSTALL 77776866Skrisfile. 77876866Skris 77976866SkrisMulti-threaded applications must provide two callback functions to 780162911SsimonOpenSSL by calling CRYPTO_set_locking_callback() and 781215697SsimonCRYPTO_set_id_callback(), for all versions of OpenSSL up to and 782215697Ssimonincluding 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback() 783215697Ssimonand associated APIs are deprecated by CRYPTO_THREADID_set_callback() 784215697Ssimonand friends. This is described in the threads(3) manpage. 78576866Skris 78659191Skris* I've compiled a program under Windows and it crashes: why? 78759191Skris 78889837SkrisThis is usually because you've missed the comment in INSTALL.W32. 78989837SkrisYour application must link against the same version of the Win32 79089837SkrisC-Runtime against which your openssl libraries were linked. The 79189837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 79259191Skris 79389837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 79489837Skrismany cases, your new project most likely defaulted to "Debug 79589837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 79689837Skrisprogram will crash, typically on the first BIO related read or write 79789837Skrisoperation. 79859191Skris 79989837SkrisFor each of the six possible link stage configurations within Win32, 80089837Skrisyour application must link against the same by which OpenSSL was 80189837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 80289837Skrisby: 80389837Skris 804160814Ssimon 1. Select Settings... from the Project Menu. 805160814Ssimon 2. Select the C/C++ Tab. 806160814Ssimon 3. Select "Code Generation from the "Category" drop down list box 807160814Ssimon 4. Select the Appropriate library (see table below) from the "Use 80889837Skris run-time library" drop down list box. Perform this step for both 80989837Skris your debug and release versions of your application (look at the 81089837Skris top left of the settings panel to change between the two) 81189837Skris 81289837Skris Single Threaded /ML - MS VC++ often defaults to 81389837Skris this for the release 81489837Skris version of a new project. 81589837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 81689837Skris this for the debug version 81789837Skris of a new project. 81889837Skris Multithreaded /MT 81989837Skris Debug Multithreaded /MTd 82089837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 82189837Skris Debug Multithreaded DLL /MDd 82289837Skris 82389837SkrisNote that debug and release libraries are NOT interchangeable. If you 82489837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 82589837Skris 826160814SsimonAs per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL 827160814Ssimon.DLLs compiled with some specific run-time option [we insist on the 828160814Ssimondefault /MD] can be deployed with application compiled with different 829160814Ssimonoption or even different compiler. But there is a catch! Instead of 830160814Ssimonre-compiling OpenSSL toolkit, as you would have to with prior versions, 831160814Ssimonyou have to compile small C snippet with compiler and/or options of 832160814Ssimonyour choice. The snippet gets installed as 833160814Ssimon<install-root>/include/openssl/applink.c and should be either added to 834160814Ssimonyour application project or simply #include-d in one [and only one] 835160814Ssimonof your application source files. Failure to link this shim module 836160814Ssimoninto your application manifests itself as fatal "no OPENSSL_Applink" 837160814Ssimonrun-time error. An explicit reminder is due that in this situation 838160814Ssimon[mixing compiler options] it is as important to add CRYPTO_malloc_init 839160814Ssimonprior first call to OpenSSL. 84089837Skris 84168651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 84268651Skris 84368651SkrisYou have two options. You can either use a memory BIO in conjunction 844160814Ssimonwith the i2d_*_bio() or d2i_*_bio() functions or you can use the 845160814Ssimoni2d_*(), d2i_*() functions directly. Since these are often the 84668651Skriscause of grief here are some code fragments using PKCS7 as an example: 84768651Skris 848160814Ssimon unsigned char *buf, *p; 849160814Ssimon int len; 85068651Skris 851160814Ssimon len = i2d_PKCS7(p7, NULL); 852160814Ssimon buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 853160814Ssimon p = buf; 854160814Ssimon i2d_PKCS7(p7, &p); 85568651Skris 85668651SkrisAt this point buf contains the len bytes of the DER encoding of 85768651Skrisp7. 85868651Skris 85968651SkrisThe opposite assumes we already have len bytes in buf: 86068651Skris 861160814Ssimon unsigned char *p; 862160814Ssimon p = buf; 863160814Ssimon p7 = d2i_PKCS7(NULL, &p, len); 86468651Skris 86568651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 86668651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 86768651Skrisinformation. 86868651Skris 86968651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 87068651Skrisincrement the passed pointer so it is ready to read or write the next 87168651Skrisstructure. This is often a cause of problems: without the temporary 87268651Skrisvariable the buffer pointer is changed to point just after the data 87368651Skristhat has been read or written. This may well be uninitialized data 87468651Skrisand attempts to free the buffer will have unpredictable results 87568651Skrisbecause it no longer points to the same address. 87668651Skris 87768651Skris 878142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 879142425Snectar 880142425SnectarThe short answer is yes, because DER is a special case of BER and OpenSSL 881142425SnectarASN1 decoders can process BER. 882142425Snectar 883142425SnectarThe longer answer is that ASN1 structures can be encoded in a number of 884142425Snectardifferent ways. One set of ways is the Basic Encoding Rules (BER) with various 885142425Snectarpermissible encodings. A restriction of BER is the Distinguished Encoding 886142425SnectarRules (DER): these uniquely specify how a given structure is encoded. 887142425Snectar 888142425SnectarTherefore, because DER is a special case of BER, DER is an acceptable encoding 889142425Snectarfor BER. 890142425Snectar 891142425Snectar 89268651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 89368651Skris 89468651SkrisThis usually happens when you try compiling something using the PKCS#12 89568651Skrismacros with a C++ compiler. There is hardly ever any need to use the 89668651SkrisPKCS#12 macros in a program, it is much easier to parse and create 89768651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 89868651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 89968651Skris'pkcs12' application has to use the macros because it prints out 90068651Skrisdebugging information. 90168651Skris 90268651Skris 90359191Skris* I've called <some function> and it fails, why? 90459191Skris 90568651SkrisBefore submitting a report or asking in one of the mailing lists, you 90668651Skrisshould try to determine the cause. In particular, you should call 90759191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 90868651Skrisand see if the message helps. Note that the problem may occur earlier 90968651Skristhan you think -- you should check for errors after every call where 91068651Skrisit is possible, otherwise the actual problem may be hidden because 91168651Skrissome OpenSSL functions clear the error state. 91259191Skris 91359191Skris 91459191Skris* I just get a load of numbers for the error output, what do they mean? 91559191Skris 91659191SkrisThe actual format is described in the ERR_print_errors() manual page. 91759191SkrisYou should call the function ERR_load_crypto_strings() before hand and 91859191Skristhe message will be output in text form. If you can't do this (for example 91959191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 92059191Skriscode itself (the hex digits after the second colon). 92159191Skris 92259191Skris 92359191Skris* Why do I get errors about unknown algorithms? 92459191Skris 925194206SsimonThe cause is forgetting to load OpenSSL's table of algorithms with 926194206SsimonOpenSSL_add_all_algorithms(). See the manual page for more information. This 927194206Ssimoncan cause several problems such as being unable to read in an encrypted 928194206SsimonPEM file, unable to decrypt a PKCS#12 file or signature failure when 929194206Ssimonverifying certificates. 93059191Skris 93159191Skris* Why can't the OpenSSH configure script detect OpenSSL? 93259191Skris 93389837SkrisSeveral reasons for problems with the automatic detection exist. 93489837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 93589837SkrisSometimes the distribution has installed an older version in the system 93689837Skrislocations that is detected instead of a new one installed. The OpenSSL 93789837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 93889837SkrisPermissions might be wrong. 93959191Skris 94089837SkrisThe general answer is to check the config.log file generated when running 94189837Skristhe OpenSSH configure script. It should contain the detailed information 94289837Skrison why the OpenSSL library was not detected or considered incompatible. 94368651Skris 944120631Snectar 94576866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 94668651Skris 94776866SkrisYes; make sure to read the SSL_get_error(3) manual page! 94868651Skris 94976866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 95076866Skristhe underlying transport or that SSL_write() will just write to it -- 95176866Skrisit is also possible that SSL_write() cannot do any useful work until 95276866Skristhere is data to read, or that SSL_read() cannot do anything until it 95376866Skrisis possible to send data. One reason for this is that the peer may 95476866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 95576866Skrisrequiring a bi-directional message exchange; both SSL_read() and 95676866SkrisSSL_write() will try to continue any pending handshake. 95768651Skris 95868651Skris 95979998Skris* Why doesn't my server application receive a client certificate? 96079998Skris 96179998SkrisDue to the TLS protocol definition, a client will only send a certificate, 96289837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 96379998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 96479998Skris 96579998Skris 966109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 967109998Smarkm 968109998SmarkmFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 969109998Smarkmversions, uniqueIdentifier was incorrectly used for X.509 certificates. 970109998SmarkmThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 971109998SmarkmChange your code to use the new name when compiling against OpenSSL 0.9.7. 972109998Smarkm 973109998Smarkm 974142425Snectar* I think I've detected a memory leak, is this a bug? 975142425Snectar 976142425SnectarIn most cases the cause of an apparent memory leak is an OpenSSL internal table 977142425Snectarthat is allocated when an application starts up. Since such tables do not grow 978142425Snectarin size over time they are harmless. 979142425Snectar 980142425SnectarThese internal tables can be freed up when an application closes using various 981160814Ssimonfunctions. Currently these include following: 982142425Snectar 983160814SsimonThread-local cleanup functions: 984142425Snectar 985160814Ssimon ERR_remove_state() 986160814Ssimon 987160814SsimonApplication-global cleanup functions that are aware of usage (and therefore 988160814Ssimonthread-safe): 989160814Ssimon 990160814Ssimon ENGINE_cleanup() and CONF_modules_unload() 991160814Ssimon 992160814Ssimon"Brutal" (thread-unsafe) Application-global cleanup functions: 993160814Ssimon 994160814Ssimon ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). 995160814Ssimon 996160814Ssimon 997194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 998194206Ssimon 999194206SsimonWhen OpenSSL's PRNG routines are called to generate random numbers the supplied 1000194206Ssimonbuffer contents are mixed into the entropy pool: so it technically does not 1001194206Ssimonmatter whether the buffer is initialized at this point or not. Valgrind (and 1002194206Ssimonother test tools) will complain about this. When using Valgrind, make sure the 1003194206SsimonOpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) 1004194206Ssimonto get rid of these warnings. 1005194206Ssimon 1006194206Ssimon 1007194206Ssimon* Why doesn't a memory BIO work when a file does? 1008194206Ssimon 1009194206SsimonThis can occur in several cases for example reading an S/MIME email message. 1010194206SsimonThe reason is that a memory BIO can do one of two things when all the data 1011194206Ssimonhas been read from it. 1012194206Ssimon 1013194206SsimonThe default behaviour is to indicate that no more data is available and that 1014194206Ssimonthe call should be retried, this is to allow the application to fill up the BIO 1015194206Ssimonagain if necessary. 1016194206Ssimon 1017194206SsimonAlternatively it can indicate that no more data is available and that EOF has 1018194206Ssimonbeen reached. 1019194206Ssimon 1020194206SsimonIf a memory BIO is to behave in the same way as a file this second behaviour 1021194206Ssimonis needed. This must be done by calling: 1022194206Ssimon 1023194206Ssimon BIO_set_mem_eof_return(bio, 0); 1024194206Ssimon 1025194206SsimonSee the manual pages for more details. 1026194206Ssimon 1027194206Ssimon 1028215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 1029215697Ssimon 1030215697SsimonThese are defined and implemented by macros of the form: 1031215697Ssimon 1032215697Ssimon 1033215697Ssimon DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) 1034215697Ssimon 1035215697SsimonThe implementation passes an ASN1 "template" defining the structure into an 1036215697SsimonASN1 interpreter using generalised functions such as ASN1_item_d2i(). 1037215697Ssimon 1038215697Ssimon 103976866Skris=============================================================================== 1040