FAQ revision 237657
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>. 86237657SjkimOpenSSL 1.0.1c was released on May 10th, 2012. 8759191Skris 8859191SkrisIn addition to the current stable release, you can also access daily 8959191Skrissnapshots of the OpenSSL development version at <URL: 9059191Skrisftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS 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 11659191SkrisFor information on parts of libcrypto that are not yet documented, you 11759191Skrismight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 11859191Skrispredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 11959191Skrisof this still applies to OpenSSL. 12059191Skris 12159191SkrisThere is some documentation about certificate extensions and PKCS#12 12259191Skrisin doc/openssl.txt 12359191Skris 12459191SkrisThe original SSLeay documentation is included in OpenSSL as 12559191Skrisdoc/ssleay.txt. It may be useful when none of the other resources 12659191Skrishelp, but please note that it reflects the obsolete version SSLeay 12759191Skris0.6.6. 12859191Skris 12959191Skris 13059191Skris* How can I contact the OpenSSL developers? 13159191Skris 13259191SkrisThe README file describes how to submit bug reports and patches to 13359191SkrisOpenSSL. Information on the OpenSSL mailing lists is available from 13459191Skris<URL: http://www.openssl.org>. 13559191Skris 13659191Skris 13776866Skris* Where can I get a compiled version of OpenSSL? 13876866Skris 139127128SnectarYou can finder pointers to binary distributions in 140216166Ssimon<URL: http://www.openssl.org/related/binaries.html> . 141127128Snectar 14276866SkrisSome applications that use OpenSSL are distributed in binary form. 14376866SkrisWhen using such an application, you don't need to install OpenSSL 14476866Skrisyourself; the application will include the required parts (e.g. DLLs). 14576866Skris 146127128SnectarIf you want to build OpenSSL on a Windows system and you don't have 14776866Skrisa C compiler, read the "Mingw32" section of INSTALL.W32 for information 14876866Skrison how to obtain and install the free GNU C compiler. 14976866Skris 15076866SkrisA number of Linux and *BSD distributions include OpenSSL. 15176866Skris 15276866Skris 15376866Skris* Why aren't tools like 'autoconf' and 'libtool' used? 15476866Skris 15576866Skrisautoconf will probably be used in future OpenSSL versions. If it was 15676866Skrisless Unix-centric, it might have been used much earlier. 15776866Skris 15889837Skris* What is an 'engine' version? 15976866Skris 16089837SkrisWith version 0.9.6 OpenSSL was extended to interface to external crypto 16189837Skrishardware. This was realized in a special release '0.9.6-engine'. With 162160814Ssimonversion 0.9.7 the changes were merged into the main development line, 163160814Ssimonso that the special release is no longer necessary. 16489837Skris 165109998Smarkm* How do I check the authenticity of the OpenSSL distribution? 166109998Smarkm 167109998SmarkmWe provide MD5 digests and ASC signatures of each tarball. 168109998SmarkmUse MD5 to check that a tarball from a mirror site is identical: 169109998Smarkm 170109998Smarkm md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 171109998Smarkm 172109998SmarkmYou can check authenticity using pgp or gpg. You need the OpenSSL team 173160814Ssimonmember public key used to sign it (download it from a key server, see a 174160814Ssimonlist of keys at <URL: http://www.openssl.org/about/>). Then 175109998Smarkmjust do: 176109998Smarkm 177109998Smarkm pgp TARBALL.asc 178109998Smarkm 179237657Sjkim* How does the versioning scheme work? 180237657Sjkim 181237657SjkimAfter the release of OpenSSL 1.0.0 the versioning scheme changed. Letter 182237657Sjkimreleases (e.g. 1.0.1a) can only contain bug and security fixes and no 183237657Sjkimnew features. Minor releases change the last number (e.g. 1.0.2) and 184237657Sjkimcan contain new features that retain binary compatibility. Changes to 185237657Sjkimthe middle number are considered major releases and neither source nor 186237657Sjkimbinary compatibility is guaranteed. 187237657Sjkim 188237657SjkimTherefore the answer to the common question "when will feature X be 189237657Sjkimbackported to OpenSSL 1.0.0/0.9.8?" is "never" but it could appear 190237657Sjkimin the next minor release. 191237657Sjkim 19276866Skris[LEGAL] ======================================================================= 19376866Skris 19459191Skris* Do I need patent licenses to use OpenSSL? 19559191Skris 19659191SkrisThe patents section of the README file lists patents that may apply to 19759191Skrisyou if you want to use OpenSSL. For information on intellectual 19859191Skrisproperty rights, please consult a lawyer. The OpenSSL team does not 19959191Skrisoffer legal advice. 20059191Skris 201160814SsimonYou can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using 202160814Ssimon ./config no-idea no-mdc2 no-rc5 20359191Skris 20459191Skris 20576866Skris* Can I use OpenSSL with GPL software? 20659191Skris 20776866SkrisOn many systems including the major Linux and BSD distributions, yes (the 20876866SkrisGPL does not place restrictions on using libraries that are part of the 20976866Skrisnormal operating system distribution). 21059191Skris 21176866SkrisOn other systems, the situation is less clear. Some GPL software copyright 21276866Skrisholders claim that you infringe on their rights if you use OpenSSL with 21376866Skristheir software on operating systems that don't normally include OpenSSL. 21459191Skris 21576866SkrisIf you develop open source software that uses OpenSSL, you may find it 21689837Skrisuseful to choose an other license than the GPL, or state explicitly that 21776866Skris"This program is released under the GPL with the additional exemption that 21876866Skriscompiling, linking, and/or using OpenSSL is allowed." If you are using 21976866SkrisGPL software developed by others, you may want to ask the copyright holder 22076866Skrisfor permission to use their software with OpenSSL. 22159191Skris 22276866Skris 22376866Skris[USER] ======================================================================== 22476866Skris 22559191Skris* Why do I get a "PRNG not seeded" error message? 22659191Skris 22759191SkrisCryptographic software needs a source of unpredictable data to work 22859191Skriscorrectly. Many open source operating systems provide a "randomness 229111147Snectardevice" (/dev/urandom or /dev/random) that serves this purpose. 230111147SnectarAll OpenSSL versions try to use /dev/urandom by default; starting with 231111147Snectarversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 232111147Snectaravailable. 23359191Skris 234111147SnectarOn other systems, applications have to call the RAND_add() or 235111147SnectarRAND_seed() function with appropriate data before generating keys or 236111147Snectarperforming public key encryption. (These functions initialize the 237111147Snectarpseudo-random number generator, PRNG.) Some broken applications do 238111147Snectarnot do this. As of version 0.9.5, the OpenSSL functions that need 239111147Snectarrandomness report an error if the random number generator has not been 240111147Snectarseeded with at least 128 bits of randomness. If this error occurs and 241111147Snectaris not discussed in the documentation of the application you are 242111147Snectarusing, please contact the author of that application; it is likely 243111147Snectarthat it never worked correctly. OpenSSL 0.9.5 and later make the 244111147Snectarerror visible by refusing to perform potentially insecure encryption. 24559191Skris 246111147SnectarIf you are using Solaris 8, you can add /dev/urandom and /dev/random 247111147Snectardevices by installing patch 112438 (Sparc) or 112439 (x86), which are 248111147Snectaravailable via the Patchfinder at <URL: http://sunsolve.sun.com> 249111147Snectar(Solaris 9 includes these devices by default). For /dev/random support 250111147Snectarfor earlier Solaris versions, see Sun's statement at 251111147Snectar<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 252111147Snectar(the SUNWski package is available in patch 105710). 253111147Snectar 25479998SkrisOn systems without /dev/urandom and /dev/random, it is a good idea to 25579998Skrisuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 25679998Skrisdetails. Starting with version 0.9.7, OpenSSL will automatically look 25779998Skrisfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 25879998Skris/etc/entropy. 25959191Skris 26079998SkrisMost components of the openssl command line utility automatically try 26179998Skristo seed the random number generator from a file. The name of the 26279998Skrisdefault seeding file is determined as follows: If environment variable 26379998SkrisRANDFILE is set, then it names the seeding file. Otherwise if 26479998Skrisenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 26579998SkrisIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 26679998Skrisuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 26779998Skrisdefault seeding file at all. OpenSSL 0.9.6b and later will behave 26889837Skrissimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 26979998SkrisWindows systems if the environment variable has not been set. 27059191Skris 27179998SkrisIf the default seeding file does not exist or is too short, the "PRNG 27279998Skrisnot seeded" error message may occur. 27359191Skris 27479998SkrisThe openssl command line utility will write back a new state to the 27579998Skrisdefault seeding file (and create this file if necessary) unless 27679998Skristhere was no sufficient seeding. 27779998Skris 27879998SkrisPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 27979998SkrisUse the "-rand" option of the OpenSSL command line tools instead. 28079998SkrisThe $RANDFILE environment variable and $HOME/.rnd are only used by the 28179998SkrisOpenSSL command line tools. Applications using the OpenSSL library 28279998Skrisprovide their own configuration options to specify the entropy source, 28379998Skrisplease check out the documentation coming the with application. 28479998Skris 28559191Skris 28679998Skris* Why do I get an "unable to write 'random state'" error message? 28779998Skris 28879998Skris 28979998SkrisSometimes the openssl command line utility does not abort with 29079998Skrisa "PRNG not seeded" error message, but complains that it is 29179998Skris"unable to write 'random state'". This message refers to the 29279998Skrisdefault seeding file (see previous answer). A possible reason 29379998Skrisis that no default filename is known because neither RANDFILE 29479998Skrisnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 29579998Skriscurrent directory in this case, but this has changed with 0.9.6a.) 29679998Skris 29779998Skris 29876866Skris* How do I create certificates or certificate requests? 29976866Skris 30076866SkrisCheck out the CA.pl(1) manual page. This provides a simple wrapper round 30176866Skristhe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 30276866Skrisout the manual pages for the individual utilities and the certificate 303237657Sjkimextensions documentation (in ca(1), req(1), x509v3_config(5) ) 30476866Skris 30576866Skris 30676866Skris* Why can't I create certificate requests? 30776866Skris 30876866SkrisYou typically get the error: 30976866Skris 31076866Skris unable to find 'distinguished_name' in config 31176866Skris problems making Certificate Request 31276866Skris 31376866SkrisThis is because it can't find the configuration file. Check out the 31476866SkrisDIAGNOSTICS section of req(1) for more information. 31576866Skris 31676866Skris 31776866Skris* Why does <SSL program> fail with a certificate verify error? 31876866Skris 31976866SkrisThis problem is usually indicated by log messages saying something like 32076866Skris"unable to get local issuer certificate" or "self signed certificate". 32176866SkrisWhen a certificate is verified its root CA must be "trusted" by OpenSSL 32276866Skristhis typically means that the CA certificate must be placed in a directory 32376866Skrisor file and the relevant program configured to read it. The OpenSSL program 32476866Skris'verify' behaves in a similar way and issues similar error messages: check 32576866Skristhe verify(1) program manual page for more information. 32676866Skris 32776866Skris 32876866Skris* Why can I only use weak ciphers when I connect to a server using OpenSSL? 32976866Skris 33076866SkrisThis is almost certainly because you are using an old "export grade" browser 33176866Skriswhich only supports weak encryption. Upgrade your browser to support 128 bit 33276866Skrisciphers. 33376866Skris 33476866Skris 33576866Skris* How can I create DSA certificates? 33676866Skris 33776866SkrisCheck the CA.pl(1) manual page for a DSA certificate example. 33876866Skris 33976866Skris 34076866Skris* Why can't I make an SSL connection to a server using a DSA certificate? 34176866Skris 34276866SkrisTypically you'll see a message saying there are no shared ciphers when 34376866Skristhe same setup works fine with an RSA certificate. There are two possible 34476866Skriscauses. The client may not support connections to DSA servers most web 34576866Skrisbrowsers (including Netscape and MSIE) only support connections to servers 34676866Skrissupporting RSA cipher suites. The other cause is that a set of DH parameters 34776866Skrishas not been supplied to the server. DH parameters can be created with the 34876866Skrisdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 34976866Skrischeck the source to s_server in apps/s_server.c for an example. 35076866Skris 35176866Skris 35276866Skris* How can I remove the passphrase on a private key? 35376866Skris 35476866SkrisFirstly you should be really *really* sure you want to do this. Leaving 35576866Skrisa private key unencrypted is a major security risk. If you decide that 35676866Skrisyou do have to do this check the EXAMPLES sections of the rsa(1) and 35776866Skrisdsa(1) manual pages. 35876866Skris 35976866Skris 36076866Skris* Why can't I use OpenSSL certificates with SSL client authentication? 36176866Skris 36276866SkrisWhat will typically happen is that when a server requests authentication 36376866Skrisit will either not include your certificate or tell you that you have 36476866Skrisno client certificates (Netscape) or present you with an empty list box 36576866Skris(MSIE). The reason for this is that when a server requests a client 36676866Skriscertificate it includes a list of CAs names which it will accept. Browsers 36776866Skriswill only let you select certificates from the list on the grounds that 36876866Skristhere is little point presenting a certificate which the server will 36976866Skrisreject. 37076866Skris 37176866SkrisThe solution is to add the relevant CA certificate to your servers "trusted 37289837SkrisCA list". How you do this depends on the server software in uses. You can 37376866Skrisprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 37476866Skris 37576866Skrisopenssl s_client -connect www.some.host:443 -prexit 37676866Skris 37776866SkrisIf your server only requests certificates on certain URLs then you may need 37876866Skristo manually issue an HTTP GET command to get the list when s_client connects: 37976866Skris 38076866SkrisGET /some/page/needing/a/certificate.html 38176866Skris 38276866SkrisIf your CA does not appear in the list then this confirms the problem. 38376866Skris 38476866Skris 38576866Skris* Why does my browser give a warning about a mismatched hostname? 38676866Skris 38776866SkrisBrowsers expect the server's hostname to match the value in the commonName 38876866Skris(CN) field of the certificate. If it does not then you get a warning. 38976866Skris 39076866Skris 39189837Skris* How do I install a CA certificate into a browser? 39289837Skris 39389837SkrisThe usual way is to send the DER encoded certificate to the browser as 39489837SkrisMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 39589837Skrislink. On MSIE certain extensions such as .der or .cacert may also work, or you 39689837Skriscan import the certificate using the certificate import wizard. 39789837Skris 39889837SkrisYou can convert a certificate to DER form using the command: 39989837Skris 40089837Skrisopenssl x509 -in ca.pem -outform DER -out ca.der 40189837Skris 40289837SkrisOccasionally someone suggests using a command such as: 40389837Skris 40489837Skrisopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 40589837Skris 40689837SkrisDO NOT DO THIS! This command will give away your CAs private key and 40789837Skrisreduces its security to zero: allowing anyone to forge certificates in 40889837Skriswhatever name they choose. 40989837Skris 410109998Smarkm* Why is OpenSSL x509 DN output not conformant to RFC2253? 41189837Skris 412109998SmarkmThe ways to print out the oneline format of the DN (Distinguished Name) have 413109998Smarkmbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 414109998Smarkminterface, the "-nameopt" option could be introduded. See the manual 415109998Smarkmpage of the "openssl x509" commandline tool for details. The old behaviour 416109998Smarkmhas however been left as default for the sake of compatibility. 417109998Smarkm 418160814Ssimon* What is a "128 bit certificate"? Can I create one with OpenSSL? 419160814Ssimon 420160814SsimonThe term "128 bit certificate" is a highly misleading marketing term. It does 421160814Ssimon*not* refer to the size of the public key in the certificate! A certificate 422160814Ssimoncontaining a 128 bit RSA key would have negligible security. 423160814Ssimon 424160814SsimonThere were various other names such as "magic certificates", "SGC 425160814Ssimoncertificates", "step up certificates" etc. 426160814Ssimon 427160814SsimonYou can't generally create such a certificate using OpenSSL but there is no 428160814Ssimonneed to any more. Nowadays web browsers using unrestricted strong encryption 429160814Ssimonare generally available. 430160814Ssimon 431194206SsimonWhen there were tight restrictions on the export of strong encryption 432160814Ssimonsoftware from the US only weak encryption algorithms could be freely exported 433160814Ssimon(initially 40 bit and then 56 bit). It was widely recognised that this was 434194206Ssimoninadequate. A relaxation of the rules allowed the use of strong encryption but 435160814Ssimononly to an authorised server. 436160814Ssimon 437160814SsimonTwo slighly different techniques were developed to support this, one used by 438160814SsimonNetscape was called "step up", the other used by MSIE was called "Server Gated 439160814SsimonCryptography" (SGC). When a browser initially connected to a server it would 440160814Ssimoncheck to see if the certificate contained certain extensions and was issued by 441160814Ssimonan authorised authority. If these test succeeded it would reconnect using 442160814Ssimonstrong encryption. 443160814Ssimon 444160814SsimonOnly certain (initially one) certificate authorities could issue the 445160814Ssimoncertificates and they generally cost more than ordinary certificates. 446160814Ssimon 447160814SsimonAlthough OpenSSL can create certificates containing the appropriate extensions 448160814Ssimonthe certificate would not come from a permitted authority and so would not 449160814Ssimonbe recognized. 450160814Ssimon 451160814SsimonThe export laws were later changed to allow almost unrestricted use of strong 452160814Ssimonencryption so these certificates are now obsolete. 453160814Ssimon 454160814Ssimon 455194206Ssimon* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? 456194206Ssimon 457194206SsimonIt doesn't: this extension is often the cause of confusion. 458194206Ssimon 459194206SsimonConsider a certificate chain A->B->C so that A signs B and B signs C. Suppose 460194206Ssimoncertificate C contains AKID. 461194206Ssimon 462194206SsimonThe purpose of this extension is to identify the authority certificate B. This 463194206Ssimoncan be done either by including the subject key identifier of B or its issuer 464194206Ssimonname and serial number. 465194206Ssimon 466194206SsimonIn this latter case because it is identifying certifcate B it must contain the 467194206Ssimonissuer name and serial number of B. 468194206Ssimon 469194206SsimonIt is often wrongly assumed that it should contain the subject name of B. If it 470194206Ssimondid this would be redundant information because it would duplicate the issuer 471194206Ssimonname of C. 472194206Ssimon 473194206Ssimon 474194206Ssimon* How can I set up a bundle of commercial root CA certificates? 475194206Ssimon 476194206SsimonThe OpenSSL software is shipped without any root CA certificate as the 477194206SsimonOpenSSL project does not have any policy on including or excluding 478194206Ssimonany specific CA and does not intend to set up such a policy. Deciding 479194206Ssimonabout which CAs to support is up to application developers or 480194206Ssimonadministrators. 481194206Ssimon 482194206SsimonOther projects do have other policies so you can for example extract the CA 483194206Ssimonbundle used by Mozilla and/or modssl as described in this article: 484194206Ssimon 485216166Ssimon <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html> 486194206Ssimon 487194206Ssimon 48876866Skris[BUILD] ======================================================================= 48976866Skris 49059191Skris* Why does the linker complain about undefined symbols? 49159191Skris 49259191SkrisMaybe the compilation was interrupted, and make doesn't notice that 49359191Skrissomething is missing. Run "make clean; make". 49459191Skris 49559191SkrisIf you used ./Configure instead of ./config, make sure that you 49659191Skrisselected the right target. File formats may differ slightly between 49759191SkrisOS versions (for example sparcv8/sparcv9, or a.out/elf). 49859191Skris 49959191SkrisIn case you get errors about the following symbols, use the config 50059191Skrisoption "no-asm", as described in INSTALL: 50159191Skris 50259191Skris BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 50359191Skris CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 50459191Skris RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 50559191Skris bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 50659191Skris bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 50759191Skris des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 50859191Skris des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 50959191Skris 51059191SkrisIf none of these helps, you may want to try using the current snapshot. 51159191SkrisIf the problem persists, please submit a bug report. 51259191Skris 51359191Skris 51476866Skris* Why does the OpenSSL test fail with "bc: command not found"? 51559191Skris 51676866SkrisYou didn't install "bc", the Unix calculator. If you want to run the 51776866Skristests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 51859191Skris 51959191Skris 52076866Skris* Why does the OpenSSL test fail with "bc: 1 no implemented"? 52159191Skris 52276866SkrisOn some SCO installations or versions, bc has a bug that gets triggered 52376866Skriswhen you run the test suite (using "make test"). The message returned is 52476866Skris"bc: 1 not implemented". 52559191Skris 52676866SkrisThe best way to deal with this is to find another implementation of bc 527216166Ssimonand compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 52876866Skrisfor download instructions) can be safely used, for example. 52976866Skris 53076866Skris 531109998Smarkm* Why does the OpenSSL test fail with "bc: stack empty"? 532109998Smarkm 533109998SmarkmOn some DG/ux versions, bc seems to have a too small stack for calculations 534109998Smarkmthat the OpenSSL bntest throws at it. This gets triggered when you run the 535109998Smarkmtest suite (using "make test"). The message returned is "bc: stack empty". 536109998Smarkm 537109998SmarkmThe best way to deal with this is to find another implementation of bc 538216166Ssimonand compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 539109998Smarkmfor download instructions) can be safely used, for example. 540109998Smarkm 541109998Smarkm 54289837Skris* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 54376866Skris 54489837SkrisOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 54576866Skrisof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 54676866Skrismemory to continue compilation.' As far as the tests have shown, this may be 54776866Skrisa compiler bug. What happens is that it eats up a lot of resident memory 54876866Skristo build something, probably a table. The problem is clearly in the 54976866Skrisoptimization code, because if one eliminates optimization completely (-O0), 55076866Skristhe compilation goes through (and the compiler consumes about 2MB of resident 55176866Skrismemory instead of 240MB or whatever one's limit is currently). 55276866Skris 55376866SkrisThere are three options to solve this problem: 55476866Skris 55576866Skris1. set your current data segment size soft limit higher. Experience shows 55676866Skristhat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 55776866Skristhis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 55876866Skriskbytes to set the limit to. 55976866Skris 56076866Skris2. If you have a hard limit that is lower than what you need and you can't 56176866Skrisget it changed, you can compile all of OpenSSL with -O0 as optimization 56276866Skrislevel. This is however not a very nice thing to do for those who expect to 56376866Skrisget the best result from OpenSSL. A bit more complicated solution is the 56476866Skrisfollowing: 56576866Skris 56676866Skris----- snip:start ----- 567160814Ssimon make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 56876866Skris sed -e 's/ -O[0-9] / -O0 /'`" 56976866Skris rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 57076866Skris make 57176866Skris----- snip:end ----- 57276866Skris 57376866SkrisThis will only compile sha_dgst.c with -O0, the rest with the optimization 57476866Skrislevel chosen by the configuration process. When the above is done, do the 57576866Skristest and installation and you're set. 57676866Skris 577160814Ssimon3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 578160814Ssimonshould not be used and is not used in SSL/TLS nor any other recognized 579160814Ssimonprotocol in either case. 58076866Skris 581160814Ssimon 58276866Skris* Why does the OpenSSL compilation fail with "ar: command not found"? 58376866Skris 58476866SkrisGetting this message is quite usual on Solaris 2, because Sun has hidden 58576866Skrisaway 'ar' and other development commands in directories that aren't in 58676866Skris$PATH by default. One of those directories is '/usr/ccs/bin'. The 58776866Skrisquickest way to fix this is to do the following (it assumes you use sh 58876866Skrisor any sh-compatible shell): 58976866Skris 59076866Skris----- snip:start ----- 59176866Skris PATH=${PATH}:/usr/ccs/bin; export PATH 59276866Skris----- snip:end ----- 59376866Skris 59476866Skrisand then redo the compilation. What you should really do is make sure 59576866Skris'/usr/ccs/bin' is permanently in your $PATH, for example through your 59676866Skris'.profile' (again, assuming you use a sh-compatible shell). 59776866Skris 59876866Skris 59976866Skris* Why does the OpenSSL compilation fail on Win32 with VC++? 60076866Skris 60176866SkrisSometimes, you may get reports from VC++ command line (cl) that it 60276866Skriscan't find standard include files like stdio.h and other weirdnesses. 60376866SkrisOne possible cause is that the environment isn't correctly set up. 604111147SnectarTo solve that problem for VC++ versions up to 6, one should run 605111147SnectarVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 606111147Snectarinstallation directory (somewhere under 'Program Files'). For VC++ 607111147Snectarversion 7 (and up?), which is also called VS.NET, the file is called 608111147SnectarVSVARS32.BAT instead. 609111147SnectarThis needs to be done prior to running NMAKE, and the changes are only 610111147Snectarvalid for the current DOS session. 61176866Skris 61276866Skris 613100936Snectar* What is special about OpenSSL on Redhat? 614100936Snectar 615100936SnectarRed Hat Linux (release 7.0 and later) include a preinstalled limited 616100936Snectarversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 617100936Snectaris disabled in this version. The same may apply to other Linux distributions. 618100936SnectarUsers may therefore wish to install more or all of the features left out. 619100936Snectar 620100936SnectarTo do this you MUST ensure that you do not overwrite the openssl that is in 621100936Snectar/usr/bin on your Red Hat machine. Several packages depend on this file, 622100936Snectarincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 623100936Snectarlibraries that come with Red Hat 7.0 onwards have different names and so are 624100936Snectarnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 625100936Snectar/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 626100936Snectar/lib/libcrypto.so.2 respectively). 627100936Snectar 628100936SnectarPlease note that we have been advised by Red Hat attempting to recompile the 629100936Snectaropenssl rpm with all the cryptography enabled will not work. All other 630100936Snectarpackages depend on the original Red Hat supplied openssl package. It is also 631100936Snectarworth noting that due to the way Red Hat supplies its packages, updates to 632100936Snectaropenssl on each distribution never change the package version, only the 633100936Snectarbuild number. For example, on Red Hat 7.1, the latest openssl package has 634100936Snectarversion number 0.9.6 and build number 9 even though it contains all the 635100936Snectarrelevant updates in packages up to and including 0.9.6b. 636100936Snectar 637100936SnectarA possible way around this is to persuade Red Hat to produce a non-US 638100936Snectarversion of Red Hat Linux. 639100936Snectar 640100936SnectarFYI: Patent numbers and expiry dates of US patents: 641100936SnectarMDC-2: 4,908,861 13/03/2007 642100936SnectarIDEA: 5,214,703 25/05/2010 643100936SnectarRC5: 5,724,428 03/03/2015 644100936Snectar 645100936Snectar 646109998Smarkm* Why does the OpenSSL compilation fail on MacOS X? 647109998Smarkm 648109998SmarkmIf the failure happens when trying to build the "openssl" binary, with 649109998Smarkma large number of undefined symbols, it's very probable that you have 650109998SmarkmOpenSSL 0.9.6b delivered with the operating system (you can find out by 651109998Smarkmrunning '/usr/bin/openssl version') and that you were trying to build 652109998SmarkmOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 653109998SmarkmMacOS X has a misfeature that's quite difficult to go around. 654109998SmarkmLook in the file PROBLEMS for a more detailed explanation and for possible 655109998Smarkmsolutions. 656109998Smarkm 657109998Smarkm 658100936Snectar* Why does the OpenSSL test suite fail on MacOS X? 659100936Snectar 660100936SnectarIf the failure happens when running 'make test' and the RC4 test fails, 661100936Snectarit's very probable that you have OpenSSL 0.9.6b delivered with the 662100936Snectaroperating system (you can find out by running '/usr/bin/openssl version') 663100936Snectarand that you were trying to build OpenSSL 0.9.6d. The problem is that 664100936Snectarthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 665100936Snectargo around and has linked the programs "openssl" and the test programs 666100936Snectarwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 667100936Snectarlibraries you just built. 668100936SnectarLook in the file PROBLEMS for a more detailed explanation and for possible 669100936Snectarsolutions. 670100936Snectar 671109998Smarkm* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 672109998Smarkm 673109998SmarkmFailure in BN_sqr test is most likely caused by a failure to configure the 674109998Smarkmtoolkit for current platform or lack of support for the platform in question. 675109998SmarkmRun './config -t' and './apps/openssl version -p'. Do these platform 676109998Smarkmidentifiers match? If they don't, then you most likely failed to run 677109998Smarkm./config and you're hereby advised to do so before filing a bug report. 678109998SmarkmIf ./config itself fails to run, then it's most likely problem with your 679109998Smarkmlocal environment and you should turn to your system administrator (or 680109998Smarkmsimilar). If identifiers match (and/or no alternative identifier is 681109998Smarkmsuggested by ./config script), then the platform is unsupported. There might 682109998Smarkmor might not be a workaround. Most notably on SPARC64 platforms with GNU 683109998SmarkmC compiler you should be able to produce a working build by running 684109998Smarkm'./config -m32'. I understand that -m32 might not be what you want/need, 685109998Smarkmbut the build should be operational. For further details turn to 686109998Smarkm<openssl-dev@openssl.org>. 687109998Smarkm 688109998Smarkm* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 689109998Smarkm 690109998SmarkmAs of 0.9.7 assembler routines were overhauled for position independence 691109998Smarkmof the machine code, which is essential for shared library support. For 692109998Smarkmsome reason OpenBSD is equipped with an out-of-date GNU assembler which 693109998Smarkmfinds the new code offensive. To work around the problem, configure with 694111147Snectarno-asm (and sacrifice a great deal of performance) or patch your assembler 695111147Snectaraccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 696109998SmarkmFor your convenience a pre-compiled replacement binary is provided at 697111147Snectar<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 698111147SnectarReportedly elder *BSD a.out platforms also suffer from this problem and 699111147Snectarremedy should be same. Provided binary is statically linked and should be 700111147Snectarworking across wider range of *BSD branches, not just OpenBSD. 701109998Smarkm 702160814Ssimon* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 703160814Ssimon 704160814SsimonIf the test program in question fails withs SIGILL, Illegal Instruction 705160814Ssimonexception, then you more than likely to run SSE2-capable CPU, such as 706160814SsimonIntel P4, under control of kernel which does not support SSE2 707160814Ssimoninstruction extentions. See accompanying INSTALL file and 708160814SsimonOPENSSL_ia32cap(3) documentation page for further information. 709160814Ssimon 710160814Ssimon* Why does compiler fail to compile sha512.c? 711160814Ssimon 712160814SsimonOpenSSL SHA-512 implementation depends on compiler support for 64-bit 713160814Ssimoninteger type. Few elder compilers [ULTRIX cc, SCO compiler to mention a 714160814Ssimoncouple] lack support for this and therefore are incapable of compiling 715160814Ssimonthe module in question. The recommendation is to disable SHA-512 by 716160814Ssimonadding no-sha512 to ./config [or ./Configure] command line. Another 717160814Ssimonpossible alternative might be to switch to GCC. 718160814Ssimon 719160814Ssimon* Test suite still fails, what to do? 720160814Ssimon 721160814SsimonAnother common reason for failure to complete some particular test is 722160814Ssimonsimply bad code generated by a buggy component in toolchain or deficiency 723160814Ssimonin run-time environment. There are few cases documented in PROBLEMS file, 724160814Ssimonconsult it for possible workaround before you beat the drum. Even if you 725160814Ssimondon't find solution or even mention there, do reserve for possibility of 726160814Ssimona compiler bug. Compiler bugs might appear in rather bizarre ways, they 727160814Ssimonnever make sense, and tend to emerge when you least expect them. In order 728160814Ssimonto identify one, drop optimization level, e.g. by editing CFLAG line in 729160814Ssimontop-level Makefile, recompile and re-run the test. 730160814Ssimon 731216166Ssimon* I think I've found a bug, what should I do? 732216166Ssimon 733216166SsimonIf you are a new user then it is quite likely you haven't found a bug and 734216166Ssimonsomething is happening you aren't familiar with. Check this FAQ, the associated 735216166Ssimondocumentation and the mailing lists for similar queries. If you are still 736216166Ssimonunsure whether it is a bug or not submit a query to the openssl-users mailing 737216166Ssimonlist. 738216166Ssimon 739216166Ssimon 740216166Ssimon* I'm SURE I've found a bug, how do I report it? 741216166Ssimon 742216166SsimonBug reports with no security implications should be sent to the request 743216166Ssimontracker. This can be done by mailing the report to <rt@openssl.org> (or its 744216166Ssimonalias <openssl-bugs@openssl.org>), please note that messages sent to the 745216166Ssimonrequest tracker also appear in the public openssl-dev mailing list. 746216166Ssimon 747216166SsimonThe report should be in plain text. Any patches should be sent as 748216166Ssimonplain text attachments because some mailers corrupt patches sent inline. 749216166SsimonIf your issue affects multiple versions of OpenSSL check any patches apply 750216166Ssimoncleanly and, if possible include patches to each affected version. 751216166Ssimon 752216166SsimonThe report should be given a meaningful subject line briefly summarising the 753216166Ssimonissue. Just "bug in OpenSSL" or "bug in OpenSSL 0.9.8n" is not very helpful. 754216166Ssimon 755216166SsimonBy sending reports to the request tracker the bug can then be given a priority 756216166Ssimonand assigned to the appropriate maintainer. The history of discussions can be 757216166Ssimonaccessed and if the issue has been addressed or a reason why not. If patches 758216166Ssimonare only sent to openssl-dev they can be mislaid if a team member has to 759216166Ssimonwade through months of old messages to review the discussion. 760216166Ssimon 761216166SsimonSee also <URL: http://www.openssl.org/support/rt.html> 762216166Ssimon 763216166Ssimon 764216166Ssimon* I've found a security issue, how do I report it? 765216166Ssimon 766216166SsimonIf you think your bug has security implications then please send it to 767216166Ssimonopenssl-security@openssl.org if you don't get a prompt reply at least 768216166Ssimonacknowledging receipt then resend or mail it directly to one of the 769216166Ssimonmore active team members (e.g. Steve). 770216166Ssimon 77176866Skris[PROG] ======================================================================== 77276866Skris 77376866Skris* Is OpenSSL thread-safe? 77476866Skris 77576866SkrisYes (with limitations: an SSL connection may not concurrently be used 77676866Skrisby multiple threads). On Windows and many Unix systems, OpenSSL 77776866Skrisautomatically uses the multi-threaded versions of the standard 77876866Skrislibraries. If your platform is not one of these, consult the INSTALL 77976866Skrisfile. 78076866Skris 78176866SkrisMulti-threaded applications must provide two callback functions to 782162911SsimonOpenSSL by calling CRYPTO_set_locking_callback() and 783215697SsimonCRYPTO_set_id_callback(), for all versions of OpenSSL up to and 784215697Ssimonincluding 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback() 785215697Ssimonand associated APIs are deprecated by CRYPTO_THREADID_set_callback() 786215697Ssimonand friends. This is described in the threads(3) manpage. 78776866Skris 78859191Skris* I've compiled a program under Windows and it crashes: why? 78959191Skris 79089837SkrisThis is usually because you've missed the comment in INSTALL.W32. 79189837SkrisYour application must link against the same version of the Win32 79289837SkrisC-Runtime against which your openssl libraries were linked. The 79389837Skrisdefault version for OpenSSL is /MD - "Multithreaded DLL". 79459191Skris 79589837SkrisIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 79689837Skrismany cases, your new project most likely defaulted to "Debug 79789837SkrisSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 79889837Skrisprogram will crash, typically on the first BIO related read or write 79989837Skrisoperation. 80059191Skris 80189837SkrisFor each of the six possible link stage configurations within Win32, 80289837Skrisyour application must link against the same by which OpenSSL was 80389837Skrisbuilt. If you are using MS Visual C++ (Studio) this can be changed 80489837Skrisby: 80589837Skris 806160814Ssimon 1. Select Settings... from the Project Menu. 807160814Ssimon 2. Select the C/C++ Tab. 808160814Ssimon 3. Select "Code Generation from the "Category" drop down list box 809160814Ssimon 4. Select the Appropriate library (see table below) from the "Use 81089837Skris run-time library" drop down list box. Perform this step for both 81189837Skris your debug and release versions of your application (look at the 81289837Skris top left of the settings panel to change between the two) 81389837Skris 81489837Skris Single Threaded /ML - MS VC++ often defaults to 81589837Skris this for the release 81689837Skris version of a new project. 81789837Skris Debug Single Threaded /MLd - MS VC++ often defaults to 81889837Skris this for the debug version 81989837Skris of a new project. 82089837Skris Multithreaded /MT 82189837Skris Debug Multithreaded /MTd 82289837Skris Multithreaded DLL /MD - OpenSSL defaults to this. 82389837Skris Debug Multithreaded DLL /MDd 82489837Skris 82589837SkrisNote that debug and release libraries are NOT interchangeable. If you 82689837Skrisbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 82789837Skris 828160814SsimonAs per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL 829160814Ssimon.DLLs compiled with some specific run-time option [we insist on the 830160814Ssimondefault /MD] can be deployed with application compiled with different 831160814Ssimonoption or even different compiler. But there is a catch! Instead of 832160814Ssimonre-compiling OpenSSL toolkit, as you would have to with prior versions, 833160814Ssimonyou have to compile small C snippet with compiler and/or options of 834160814Ssimonyour choice. The snippet gets installed as 835160814Ssimon<install-root>/include/openssl/applink.c and should be either added to 836160814Ssimonyour application project or simply #include-d in one [and only one] 837160814Ssimonof your application source files. Failure to link this shim module 838160814Ssimoninto your application manifests itself as fatal "no OPENSSL_Applink" 839160814Ssimonrun-time error. An explicit reminder is due that in this situation 840160814Ssimon[mixing compiler options] it is as important to add CRYPTO_malloc_init 841160814Ssimonprior first call to OpenSSL. 84289837Skris 84368651Skris* How do I read or write a DER encoded buffer using the ASN1 functions? 84468651Skris 84568651SkrisYou have two options. You can either use a memory BIO in conjunction 846160814Ssimonwith the i2d_*_bio() or d2i_*_bio() functions or you can use the 847160814Ssimoni2d_*(), d2i_*() functions directly. Since these are often the 84868651Skriscause of grief here are some code fragments using PKCS7 as an example: 84968651Skris 850160814Ssimon unsigned char *buf, *p; 851160814Ssimon int len; 85268651Skris 853160814Ssimon len = i2d_PKCS7(p7, NULL); 854160814Ssimon buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 855160814Ssimon p = buf; 856160814Ssimon i2d_PKCS7(p7, &p); 85768651Skris 85868651SkrisAt this point buf contains the len bytes of the DER encoding of 85968651Skrisp7. 86068651Skris 86168651SkrisThe opposite assumes we already have len bytes in buf: 86268651Skris 863160814Ssimon unsigned char *p; 864160814Ssimon p = buf; 865160814Ssimon p7 = d2i_PKCS7(NULL, &p, len); 86668651Skris 86768651SkrisAt this point p7 contains a valid PKCS7 structure of NULL if an error 86868651Skrisoccurred. If an error occurred ERR_print_errors(bio) should give more 86968651Skrisinformation. 87068651Skris 87168651SkrisThe reason for the temporary variable 'p' is that the ASN1 functions 87268651Skrisincrement the passed pointer so it is ready to read or write the next 87368651Skrisstructure. This is often a cause of problems: without the temporary 87468651Skrisvariable the buffer pointer is changed to point just after the data 87568651Skristhat has been read or written. This may well be uninitialized data 87668651Skrisand attempts to free the buffer will have unpredictable results 87768651Skrisbecause it no longer points to the same address. 87868651Skris 87968651Skris 880142425Snectar* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 881142425Snectar 882142425SnectarThe short answer is yes, because DER is a special case of BER and OpenSSL 883142425SnectarASN1 decoders can process BER. 884142425Snectar 885142425SnectarThe longer answer is that ASN1 structures can be encoded in a number of 886142425Snectardifferent ways. One set of ways is the Basic Encoding Rules (BER) with various 887142425Snectarpermissible encodings. A restriction of BER is the Distinguished Encoding 888142425SnectarRules (DER): these uniquely specify how a given structure is encoded. 889142425Snectar 890142425SnectarTherefore, because DER is a special case of BER, DER is an acceptable encoding 891142425Snectarfor BER. 892142425Snectar 893142425Snectar 89468651Skris* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 89568651Skris 89668651SkrisThis usually happens when you try compiling something using the PKCS#12 89768651Skrismacros with a C++ compiler. There is hardly ever any need to use the 89868651SkrisPKCS#12 macros in a program, it is much easier to parse and create 89968651SkrisPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 90068651Skrisdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 90168651Skris'pkcs12' application has to use the macros because it prints out 90268651Skrisdebugging information. 90368651Skris 90468651Skris 90559191Skris* I've called <some function> and it fails, why? 90659191Skris 90768651SkrisBefore submitting a report or asking in one of the mailing lists, you 90868651Skrisshould try to determine the cause. In particular, you should call 90959191SkrisERR_print_errors() or ERR_print_errors_fp() after the failed call 91068651Skrisand see if the message helps. Note that the problem may occur earlier 91168651Skristhan you think -- you should check for errors after every call where 91268651Skrisit is possible, otherwise the actual problem may be hidden because 91368651Skrissome OpenSSL functions clear the error state. 91459191Skris 91559191Skris 91659191Skris* I just get a load of numbers for the error output, what do they mean? 91759191Skris 91859191SkrisThe actual format is described in the ERR_print_errors() manual page. 91959191SkrisYou should call the function ERR_load_crypto_strings() before hand and 92059191Skristhe message will be output in text form. If you can't do this (for example 92159191Skrisit is a pre-compiled binary) you can use the errstr utility on the error 92259191Skriscode itself (the hex digits after the second colon). 92359191Skris 92459191Skris 92559191Skris* Why do I get errors about unknown algorithms? 92659191Skris 927194206SsimonThe cause is forgetting to load OpenSSL's table of algorithms with 928194206SsimonOpenSSL_add_all_algorithms(). See the manual page for more information. This 929194206Ssimoncan cause several problems such as being unable to read in an encrypted 930194206SsimonPEM file, unable to decrypt a PKCS#12 file or signature failure when 931194206Ssimonverifying certificates. 93259191Skris 93359191Skris* Why can't the OpenSSH configure script detect OpenSSL? 93459191Skris 93589837SkrisSeveral reasons for problems with the automatic detection exist. 93689837SkrisOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 93789837SkrisSometimes the distribution has installed an older version in the system 93889837Skrislocations that is detected instead of a new one installed. The OpenSSL 93989837Skrislibrary might have been compiled for another CPU or another mode (32/64 bits). 94089837SkrisPermissions might be wrong. 94159191Skris 94289837SkrisThe general answer is to check the config.log file generated when running 94389837Skristhe OpenSSH configure script. It should contain the detailed information 94489837Skrison why the OpenSSL library was not detected or considered incompatible. 94568651Skris 946120631Snectar 94776866Skris* Can I use OpenSSL's SSL library with non-blocking I/O? 94868651Skris 94976866SkrisYes; make sure to read the SSL_get_error(3) manual page! 95068651Skris 95176866SkrisA pitfall to avoid: Don't assume that SSL_read() will just read from 95276866Skristhe underlying transport or that SSL_write() will just write to it -- 95376866Skrisit is also possible that SSL_write() cannot do any useful work until 95476866Skristhere is data to read, or that SSL_read() cannot do anything until it 95576866Skrisis possible to send data. One reason for this is that the peer may 95676866Skrisrequest a new TLS/SSL handshake at any time during the protocol, 95776866Skrisrequiring a bi-directional message exchange; both SSL_read() and 95876866SkrisSSL_write() will try to continue any pending handshake. 95968651Skris 96068651Skris 96179998Skris* Why doesn't my server application receive a client certificate? 96279998Skris 96379998SkrisDue to the TLS protocol definition, a client will only send a certificate, 96489837Skrisif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 96579998SkrisSSL_CTX_set_verify() function to enable the use of client certificates. 96679998Skris 96779998Skris 968109998Smarkm* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 969109998Smarkm 970109998SmarkmFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 971109998Smarkmversions, uniqueIdentifier was incorrectly used for X.509 certificates. 972109998SmarkmThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 973109998SmarkmChange your code to use the new name when compiling against OpenSSL 0.9.7. 974109998Smarkm 975109998Smarkm 976142425Snectar* I think I've detected a memory leak, is this a bug? 977142425Snectar 978142425SnectarIn most cases the cause of an apparent memory leak is an OpenSSL internal table 979142425Snectarthat is allocated when an application starts up. Since such tables do not grow 980142425Snectarin size over time they are harmless. 981142425Snectar 982142425SnectarThese internal tables can be freed up when an application closes using various 983160814Ssimonfunctions. Currently these include following: 984142425Snectar 985160814SsimonThread-local cleanup functions: 986142425Snectar 987160814Ssimon ERR_remove_state() 988160814Ssimon 989160814SsimonApplication-global cleanup functions that are aware of usage (and therefore 990160814Ssimonthread-safe): 991160814Ssimon 992160814Ssimon ENGINE_cleanup() and CONF_modules_unload() 993160814Ssimon 994160814Ssimon"Brutal" (thread-unsafe) Application-global cleanup functions: 995160814Ssimon 996160814Ssimon ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). 997160814Ssimon 998160814Ssimon 999194206Ssimon* Why does Valgrind complain about the use of uninitialized data? 1000194206Ssimon 1001194206SsimonWhen OpenSSL's PRNG routines are called to generate random numbers the supplied 1002194206Ssimonbuffer contents are mixed into the entropy pool: so it technically does not 1003194206Ssimonmatter whether the buffer is initialized at this point or not. Valgrind (and 1004194206Ssimonother test tools) will complain about this. When using Valgrind, make sure the 1005194206SsimonOpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) 1006194206Ssimonto get rid of these warnings. 1007194206Ssimon 1008194206Ssimon 1009194206Ssimon* Why doesn't a memory BIO work when a file does? 1010194206Ssimon 1011194206SsimonThis can occur in several cases for example reading an S/MIME email message. 1012194206SsimonThe reason is that a memory BIO can do one of two things when all the data 1013194206Ssimonhas been read from it. 1014194206Ssimon 1015194206SsimonThe default behaviour is to indicate that no more data is available and that 1016194206Ssimonthe call should be retried, this is to allow the application to fill up the BIO 1017194206Ssimonagain if necessary. 1018194206Ssimon 1019194206SsimonAlternatively it can indicate that no more data is available and that EOF has 1020194206Ssimonbeen reached. 1021194206Ssimon 1022194206SsimonIf a memory BIO is to behave in the same way as a file this second behaviour 1023194206Ssimonis needed. This must be done by calling: 1024194206Ssimon 1025194206Ssimon BIO_set_mem_eof_return(bio, 0); 1026194206Ssimon 1027194206SsimonSee the manual pages for more details. 1028194206Ssimon 1029194206Ssimon 1030215697Ssimon* Where are the declarations and implementations of d2i_X509() etc? 1031215697Ssimon 1032215697SsimonThese are defined and implemented by macros of the form: 1033215697Ssimon 1034215697Ssimon 1035215697Ssimon DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) 1036215697Ssimon 1037215697SsimonThe implementation passes an ASN1 "template" defining the structure into an 1038215697SsimonASN1 interpreter using generalised functions such as ASN1_item_d2i(). 1039215697Ssimon 1040215697Ssimon 104176866Skris=============================================================================== 1042