FAQ revision 216166
141502SwpaulOpenSSL - Frequently Asked Questions 241502Swpaul-------------------------------------- 341502Swpaul 441502Swpaul[MISC] Miscellaneous questions 541502Swpaul 641502Swpaul* Which is the current version of OpenSSL? 741502Swpaul* Where is the documentation? 841502Swpaul* How can I contact the OpenSSL developers? 941502Swpaul* Where can I get a compiled version of OpenSSL? 1041502Swpaul* Why aren't tools like 'autoconf' and 'libtool' used? 1141502Swpaul* What is an 'engine' version? 1241502Swpaul* How do I check the authenticity of the OpenSSL distribution? 1341502Swpaul 1441502Swpaul[LEGAL] Legal questions 1541502Swpaul 1641502Swpaul* Do I need patent licenses to use OpenSSL? 1741502Swpaul* Can I use OpenSSL with GPL software? 1841502Swpaul 1941502Swpaul[USER] Questions on using the OpenSSL applications 2041502Swpaul 2141502Swpaul* Why do I get a "PRNG not seeded" error message? 2241502Swpaul* Why do I get an "unable to write 'random state'" error message? 2341502Swpaul* How do I create certificates or certificate requests? 2441502Swpaul* Why can't I create certificate requests? 2541502Swpaul* Why does <SSL program> fail with a certificate verify error? 2641502Swpaul* Why can I only use weak ciphers when I connect to a server using OpenSSL? 2741502Swpaul* How can I create DSA certificates? 2841502Swpaul* Why can't I make an SSL connection using a DSA certificate? 2941502Swpaul* How can I remove the passphrase on a private key? 3041502Swpaul* Why can't I use OpenSSL certificates with SSL client authentication? 3141502Swpaul* Why does my browser give a warning about a mismatched hostname? 3241502Swpaul* How do I install a CA certificate into a browser? 33122678Sobrien* Why is OpenSSL x509 DN output not conformant to RFC2253? 34122678Sobrien* What is a "128 bit certificate"? Can I create one with OpenSSL? 35122678Sobrien* Why does OpenSSL set the authority key identifier extension incorrectly? 3641502Swpaul* How can I set up a bundle of commercial root CA certificates? 3741502Swpaul 3841502Swpaul[BUILD] Questions about building and testing OpenSSL 3941502Swpaul 4041502Swpaul* Why does the linker complain about undefined symbols? 4141502Swpaul* Why does the OpenSSL test fail with "bc: command not found"? 4241502Swpaul* Why does the OpenSSL test fail with "bc: 1 no implemented"? 4341502Swpaul* Why does the OpenSSL test fail with "bc: stack empty"? 4441502Swpaul* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 4541502Swpaul* Why does the OpenSSL compilation fail with "ar: command not found"? 4641502Swpaul* Why does the OpenSSL compilation fail on Win32 with VC++? 4741502Swpaul* What is special about OpenSSL on Redhat? 4841502Swpaul* Why does the OpenSSL compilation fail on MacOS X? 4941502Swpaul* Why does the OpenSSL test suite fail on MacOS X? 5041502Swpaul* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 5141502Swpaul* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 5241502Swpaul* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 5341502Swpaul* Why does compiler fail to compile sha512.c? 5441502Swpaul* Test suite still fails, what to do? 5541502Swpaul* I think I've found a bug, what should I do? 5641502Swpaul* I'm SURE I've found a bug, how do I report it? 5741502Swpaul* I've found a security issue, how do I report it? 5841502Swpaul 5941502Swpaul[PROG] Questions about programming with OpenSSL 6041502Swpaul 6141502Swpaul* Is OpenSSL thread-safe? 6241502Swpaul* I've compiled a program under Windows and it crashes: why? 6341502Swpaul* How do I read or write a DER encoded buffer using the ASN1 functions? 6441502Swpaul* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 6541502Swpaul* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 6641502Swpaul* I've called <some function> and it fails, why? 6741502Swpaul* I just get a load of numbers for the error output, what do they mean? 6841502Swpaul* Why do I get errors about unknown algorithms? 6941502Swpaul* Why can't the OpenSSH configure script detect OpenSSL? 7041502Swpaul* Can I use OpenSSL's SSL library with non-blocking I/O? 7141502Swpaul* Why doesn't my server application receive a client certificate? 7241502Swpaul* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 7341502Swpaul* I think I've detected a memory leak, is this a bug? 7441502Swpaul* Why does Valgrind complain about the use of uninitialized data? 7541502Swpaul* Why doesn't a memory BIO work when a file does? 7641502Swpaul* Where are the declarations and implementations of d2i_X509() etc? 7741502Swpaul 7841502Swpaul=============================================================================== 7941502Swpaul 8041502Swpaul[MISC] ======================================================================== 8141502Swpaul 8241502Swpaul* Which is the current version of OpenSSL? 8341502Swpaul 8441502SwpaulThe current version is available from <URL: http://www.openssl.org>. 8541502SwpaulOpenSSL 1.0.0c was released on Dec 2nd, 2010. 8648745Swpaul 8741502SwpaulIn addition to the current stable release, you can also access daily 8841502Swpaulsnapshots of the OpenSSL development version at <URL: 8941502Swpaulftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 9041502Swpaul 9141502Swpaul 9241502Swpaul* Where is the documentation? 93129878Sphk 9441502SwpaulOpenSSL is a library that provides cryptographic functionality to 9541502Swpaulapplications such as secure web servers. Be sure to read the 9650675Swpauldocumentation of the application you want to use. The INSTALL file 9741502Swpaulexplains how to install this library. 9841502Swpaul 9941502SwpaulOpenSSL includes a command line utility that can be used to perform a 10041502Swpaulvariety of cryptographic functions. It is described in the openssl(1) 10141502Swpaulmanpage. Documentation for developers is currently being written. Many 10241502Swpaulmanual pages are available; overviews over libcrypto and 10341502Swpaullibssl are given in the crypto(3) and ssl(3) manpages. 10441502Swpaul 10541502SwpaulThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 10641502Swpauldifferent directory if you specified one as described in INSTALL). 10741502SwpaulIn addition, you can read the most current versions at 10841502Swpaul<URL: http://www.openssl.org/docs/>. Note that the online documents refer 10941502Swpaulto the very latest development versions of OpenSSL and may include features 11041502Swpaulnot present in released versions. If in doubt refer to the documentation 11149611Swpaulthat came with the version of OpenSSL you are using. 11249611Swpaul 11349611SwpaulFor information on parts of libcrypto that are not yet documented, you 11441502Swpaulmight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 115119288Simppredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 116119288Simpof this still applies to OpenSSL. 11741502Swpaul 11850675SwpaulThere is some documentation about certificate extensions and PKCS#12 11950675Swpaulin doc/openssl.txt 12050675Swpaul 12151089SpeterThe original SSLeay documentation is included in OpenSSL as 12250675Swpauldoc/ssleay.txt. It may be useful when none of the other resources 12350675Swpaulhelp, but please note that it reflects the obsolete version SSLeay 12441502Swpaul0.6.6. 12541502Swpaul 12641502Swpaul 12741502Swpaul* How can I contact the OpenSSL developers? 128113506Smdodd 129113506SmdoddThe README file describes how to submit bug reports and patches to 13059758SpeterOpenSSL. Information on the OpenSSL mailing lists is available from 13159758Speter<URL: http://www.openssl.org>. 13241502Swpaul 13341502Swpaul 13441502Swpaul* Where can I get a compiled version of OpenSSL? 13541502Swpaul 13641502SwpaulYou can finder pointers to binary distributions in 13741502Swpaul<URL: http://www.openssl.org/related/binaries.html> . 13841502Swpaul 13941502SwpaulSome applications that use OpenSSL are distributed in binary form. 14041502SwpaulWhen using such an application, you don't need to install OpenSSL 14141502Swpaulyourself; the application will include the required parts (e.g. DLLs). 14241502Swpaul 14392739SalfredIf you want to build OpenSSL on a Windows system and you don't have 14492739Salfreda C compiler, read the "Mingw32" section of INSTALL.W32 for information 14592739Salfredon how to obtain and install the free GNU C compiler. 14641502Swpaul 14798995SalfredA number of Linux and *BSD distributions include OpenSSL. 14892739Salfred 14948745Swpaul 15092739Salfred* Why aren't tools like 'autoconf' and 'libtool' used? 15192739Salfred 15292739Salfredautoconf will probably be used in future OpenSSL versions. If it was 15341502Swpaulless Unix-centric, it might have been used much earlier. 15492739Salfred 15592739Salfred* What is an 'engine' version? 15692739Salfred 15792739SalfredWith version 0.9.6 OpenSSL was extended to interface to external crypto 15892739Salfredhardware. This was realized in a special release '0.9.6-engine'. With 15992739Salfredversion 0.9.7 the changes were merged into the main development line, 16092739Salfredso that the special release is no longer necessary. 16192739Salfred 16292739Salfred* How do I check the authenticity of the OpenSSL distribution? 16392739Salfred 16492739SalfredWe provide MD5 digests and ASC signatures of each tarball. 16592739SalfredUse MD5 to check that a tarball from a mirror site is identical: 16692739Salfred 16792739Salfred md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 16841502Swpaul 16992739SalfredYou can check authenticity using pgp or gpg. You need the OpenSSL team 17092739Salfredmember public key used to sign it (download it from a key server, see a 17192739Salfredlist of keys at <URL: http://www.openssl.org/about/>). Then 17292739Salfredjust do: 17392739Salfred 17492739Salfred pgp TARBALL.asc 17592739Salfred 17641502Swpaul[LEGAL] ======================================================================= 17792739Salfred 17892739Salfred* Do I need patent licenses to use OpenSSL? 17992739Salfred 18092739SalfredThe patents section of the README file lists patents that may apply to 18192739Salfredyou if you want to use OpenSSL. For information on intellectual 18292739Salfredproperty rights, please consult a lawyer. The OpenSSL team does not 18341502Swpauloffer legal advice. 18492739Salfred 18592739SalfredYou can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using 18692739Salfred ./config no-idea no-mdc2 no-rc5 18750675Swpaul 18849611Swpaul 18949611Swpaul* Can I use OpenSSL with GPL software? 19049611Swpaul 19149611SwpaulOn many systems including the major Linux and BSD distributions, yes (the 19249611SwpaulGPL does not place restrictions on using libraries that are part of the 19349611Swpaulnormal operating system distribution). 19449611Swpaul 19549611SwpaulOn other systems, the situation is less clear. Some GPL software copyright 19649611Swpaulholders claim that you infringe on their rights if you use OpenSSL with 19749611Swpaultheir software on operating systems that don't normally include OpenSSL. 19849611Swpaul 19949611SwpaulIf you develop open source software that uses OpenSSL, you may find it 20049611Swpauluseful to choose an other license than the GPL, or state explicitly that 20149611Swpaul"This program is released under the GPL with the additional exemption that 20250675Swpaulcompiling, linking, and/or using OpenSSL is allowed." If you are using 20350675SwpaulGPL software developed by others, you may want to ask the copyright holder 20450675Swpaulfor permission to use their software with OpenSSL. 20550675Swpaul 20650675Swpaul 20750675Swpaul[USER] ======================================================================== 20850675Swpaul 20950675Swpaul* Why do I get a "PRNG not seeded" error message? 21050675Swpaul 21149611SwpaulCryptographic software needs a source of unpredictable data to work 21249611Swpaulcorrectly. Many open source operating systems provide a "randomness 21349611Swpauldevice" (/dev/urandom or /dev/random) that serves this purpose. 21449611SwpaulAll OpenSSL versions try to use /dev/urandom by default; starting with 21551455Swpaulversion 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not 21649611Swpaulavailable. 21749611Swpaul 21849611SwpaulOn other systems, applications have to call the RAND_add() or 21949611SwpaulRAND_seed() function with appropriate data before generating keys or 22049611Swpaulperforming public key encryption. (These functions initialize the 22149611Swpaulpseudo-random number generator, PRNG.) Some broken applications do 222113506Smdoddnot do this. As of version 0.9.5, the OpenSSL functions that need 22351473Swpaulrandomness report an error if the random number generator has not been 22449611Swpaulseeded with at least 128 bits of randomness. If this error occurs and 22541502Swpaulis not discussed in the documentation of the application you are 22641502Swpaulusing, please contact the author of that application; it is likely 227105221Sphkthat it never worked correctly. OpenSSL 0.9.5 and later make the 22841502Swpaulerror visible by refusing to perform potentially insecure encryption. 22941502Swpaul 23041502SwpaulIf you are using Solaris 8, you can add /dev/urandom and /dev/random 231105221Sphkdevices by installing patch 112438 (Sparc) or 112439 (x86), which are 23241502Swpaulavailable via the Patchfinder at <URL: http://sunsolve.sun.com> 23341502Swpaul(Solaris 9 includes these devices by default). For /dev/random support 23441502Swpaulfor earlier Solaris versions, see Sun's statement at 235105221Sphk<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> 23641502Swpaul(the SUNWski package is available in patch 105710). 23741502Swpaul 23841502SwpaulOn systems without /dev/urandom and /dev/random, it is a good idea to 239105221Sphkuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 24041502Swpauldetails. Starting with version 0.9.7, OpenSSL will automatically look 24141502Swpaulfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 24241502Swpaul/etc/entropy. 24341502Swpaul 244102336SalfredMost components of the openssl command line utility automatically try 245102336Salfredto seed the random number generator from a file. The name of the 24641502Swpauldefault seeding file is determined as follows: If environment variable 24742718SwpaulRANDFILE is set, then it names the seeding file. Otherwise if 24841502Swpaulenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 24941502SwpaulIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 25041502Swpauluse file .rnd in the current directory while OpenSSL 0.9.6a uses no 25141502Swpauldefault seeding file at all. OpenSSL 0.9.6b and later will behave 25241502Swpaulsimilarly to 0.9.6a, but will use a default of "C:\" for HOME on 25341502SwpaulWindows systems if the environment variable has not been set. 25441502Swpaul 25541502SwpaulIf the default seeding file does not exist or is too short, the "PRNG 25641502Swpaulnot seeded" error message may occur. 25741502Swpaul 25841502SwpaulThe openssl command line utility will write back a new state to the 25941502Swpauldefault seeding file (and create this file if necessary) unless 26041502Swpaulthere was no sufficient seeding. 26141502Swpaul 26241502SwpaulPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 26341502SwpaulUse the "-rand" option of the OpenSSL command line tools instead. 26441502SwpaulThe $RANDFILE environment variable and $HOME/.rnd are only used by the 26541502SwpaulOpenSSL command line tools. Applications using the OpenSSL library 26641502Swpaulprovide their own configuration options to specify the entropy source, 26741502Swpaulplease check out the documentation coming the with application. 26841502Swpaul 26941502Swpaul 27041502Swpaul* Why do I get an "unable to write 'random state'" error message? 27141502Swpaul 27241502Swpaul 27341502SwpaulSometimes the openssl command line utility does not abort with 27441502Swpaula "PRNG not seeded" error message, but complains that it is 275102336Salfred"unable to write 'random state'". This message refers to the 276102336Salfreddefault seeding file (see previous answer). A possible reason 27741502Swpaulis that no default filename is known because neither RANDFILE 27842718Swpaulnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 27941502Swpaulcurrent directory in this case, but this has changed with 0.9.6a.) 28041502Swpaul 28141502Swpaul 28241502Swpaul* How do I create certificates or certificate requests? 28341502Swpaul 28441502SwpaulCheck out the CA.pl(1) manual page. This provides a simple wrapper round 28541502Swpaulthe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 28641502Swpaulout the manual pages for the individual utilities and the certificate 28741502Swpaulextensions documentation (currently in doc/openssl.txt). 28841502Swpaul 28941502Swpaul 29041502Swpaul* Why can't I create certificate requests? 29141502Swpaul 29241502SwpaulYou typically get the error: 29341502Swpaul 29441502Swpaul unable to find 'distinguished_name' in config 29541502Swpaul problems making Certificate Request 29641502Swpaul 29741502SwpaulThis is because it can't find the configuration file. Check out the 29841502SwpaulDIAGNOSTICS section of req(1) for more information. 29941502Swpaul 30041502Swpaul 30141502Swpaul* Why does <SSL program> fail with a certificate verify error? 30241502Swpaul 30341502SwpaulThis problem is usually indicated by log messages saying something like 30441502Swpaul"unable to get local issuer certificate" or "self signed certificate". 30541502SwpaulWhen a certificate is verified its root CA must be "trusted" by OpenSSL 30641502Swpaulthis typically means that the CA certificate must be placed in a directory 30741502Swpaulor file and the relevant program configured to read it. The OpenSSL program 30841502Swpaul'verify' behaves in a similar way and issues similar error messages: check 30941502Swpaulthe verify(1) program manual page for more information. 31041502Swpaul 31141502Swpaul 31241502Swpaul* Why can I only use weak ciphers when I connect to a server using OpenSSL? 31341502Swpaul 31441502SwpaulThis is almost certainly because you are using an old "export grade" browser 31541502Swpaulwhich only supports weak encryption. Upgrade your browser to support 128 bit 31641502Swpaulciphers. 317102336Salfred 318102336Salfred 31941502Swpaul* How can I create DSA certificates? 32041502Swpaul 32141502SwpaulCheck the CA.pl(1) manual page for a DSA certificate example. 32241502Swpaul 32341502Swpaul 32441502Swpaul* Why can't I make an SSL connection to a server using a DSA certificate? 32541502Swpaul 32641502SwpaulTypically you'll see a message saying there are no shared ciphers when 32741502Swpaulthe same setup works fine with an RSA certificate. There are two possible 32841502Swpaulcauses. The client may not support connections to DSA servers most web 32941502Swpaulbrowsers (including Netscape and MSIE) only support connections to servers 33041502Swpaulsupporting RSA cipher suites. The other cause is that a set of DH parameters 33141502Swpaulhas not been supplied to the server. DH parameters can be created with the 33241502Swpauldhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 33341502Swpaulcheck the source to s_server in apps/s_server.c for an example. 33441502Swpaul 33541502Swpaul 33641502Swpaul* How can I remove the passphrase on a private key? 33741502Swpaul 33841502SwpaulFirstly you should be really *really* sure you want to do this. Leaving 33941502Swpaula private key unencrypted is a major security risk. If you decide that 34041502Swpaulyou do have to do this check the EXAMPLES sections of the rsa(1) and 34141502Swpauldsa(1) manual pages. 34241502Swpaul 343102336Salfred 344102336Salfred* Why can't I use OpenSSL certificates with SSL client authentication? 34541502Swpaul 34641502SwpaulWhat will typically happen is that when a server requests authentication 34741502Swpaulit will either not include your certificate or tell you that you have 34841502Swpaulno client certificates (Netscape) or present you with an empty list box 34941502Swpaul(MSIE). The reason for this is that when a server requests a client 35041502Swpaulcertificate it includes a list of CAs names which it will accept. Browsers 35141502Swpaulwill only let you select certificates from the list on the grounds that 35241502Swpaulthere is little point presenting a certificate which the server will 35341502Swpaulreject. 35441502Swpaul 35541502SwpaulThe solution is to add the relevant CA certificate to your servers "trusted 35641502SwpaulCA list". How you do this depends on the server software in uses. You can 35741502Swpaulprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 35841502Swpaul 35941502Swpaulopenssl s_client -connect www.some.host:443 -prexit 36041502Swpaul 36141502SwpaulIf your server only requests certificates on certain URLs then you may need 36241502Swpaulto manually issue an HTTP GET command to get the list when s_client connects: 36341502Swpaul 364102336SalfredGET /some/page/needing/a/certificate.html 365102336Salfred 36641502SwpaulIf your CA does not appear in the list then this confirms the problem. 36741502Swpaul 36841502Swpaul 36941502Swpaul* Why does my browser give a warning about a mismatched hostname? 37041502Swpaul 37141502SwpaulBrowsers expect the server's hostname to match the value in the commonName 37241502Swpaul(CN) field of the certificate. If it does not then you get a warning. 37341502Swpaul 37441502Swpaul 37541502Swpaul* How do I install a CA certificate into a browser? 37641502Swpaul 37741502SwpaulThe usual way is to send the DER encoded certificate to the browser as 37841502SwpaulMIME type application/x-x509-ca-cert, for example by clicking on an appropriate 37941502Swpaullink. On MSIE certain extensions such as .der or .cacert may also work, or you 38041502Swpaulcan import the certificate using the certificate import wizard. 38141502Swpaul 38241502SwpaulYou can convert a certificate to DER form using the command: 38341502Swpaul 38441502Swpaulopenssl x509 -in ca.pem -outform DER -out ca.der 38541502Swpaul 38641502SwpaulOccasionally someone suggests using a command such as: 38741502Swpaul 38841502Swpaulopenssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem 38941502Swpaul 390102336SalfredDO NOT DO THIS! This command will give away your CAs private key and 391102336Salfredreduces its security to zero: allowing anyone to forge certificates in 39241502Swpaulwhatever name they choose. 39341502Swpaul 39441502Swpaul* Why is OpenSSL x509 DN output not conformant to RFC2253? 39541502Swpaul 39667087SwpaulThe ways to print out the oneline format of the DN (Distinguished Name) have 39741502Swpaulbeen extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() 39867087Swpaulinterface, the "-nameopt" option could be introduded. See the manual 39941502Swpaulpage of the "openssl x509" commandline tool for details. The old behaviour 40041502Swpaulhas however been left as default for the sake of compatibility. 40141502Swpaul 40241502Swpaul* What is a "128 bit certificate"? Can I create one with OpenSSL? 40341502Swpaul 40441502SwpaulThe term "128 bit certificate" is a highly misleading marketing term. It does 40541502Swpaul*not* refer to the size of the public key in the certificate! A certificate 40641502Swpaulcontaining a 128 bit RSA key would have negligible security. 40741502Swpaul 40841502SwpaulThere were various other names such as "magic certificates", "SGC 40941502Swpaulcertificates", "step up certificates" etc. 41041502Swpaul 41141502SwpaulYou can't generally create such a certificate using OpenSSL but there is no 41241502Swpaulneed to any more. Nowadays web browsers using unrestricted strong encryption 41341502Swpaulare generally available. 41441502Swpaul 41541502SwpaulWhen there were tight restrictions on the export of strong encryption 41641502Swpaulsoftware from the US only weak encryption algorithms could be freely exported 41741502Swpaul(initially 40 bit and then 56 bit). It was widely recognised that this was 41841502Swpaulinadequate. A relaxation of the rules allowed the use of strong encryption but 41941502Swpaulonly to an authorised server. 42041502Swpaul 42141502SwpaulTwo slighly different techniques were developed to support this, one used by 42241502SwpaulNetscape was called "step up", the other used by MSIE was called "Server Gated 42341502SwpaulCryptography" (SGC). When a browser initially connected to a server it would 42441502Swpaulcheck to see if the certificate contained certain extensions and was issued by 42541502Swpaulan authorised authority. If these test succeeded it would reconnect using 42641502Swpaulstrong encryption. 42741502Swpaul 42841502SwpaulOnly certain (initially one) certificate authorities could issue the 42941502Swpaulcertificates and they generally cost more than ordinary certificates. 43041502Swpaul 43141502SwpaulAlthough OpenSSL can create certificates containing the appropriate extensions 43241502Swpaulthe certificate would not come from a permitted authority and so would not 43341502Swpaulbe recognized. 43441502Swpaul 43541502SwpaulThe export laws were later changed to allow almost unrestricted use of strong 436109058Smbrencryption so these certificates are now obsolete. 43741502Swpaul 43841502Swpaul 43941502Swpaul* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? 44041502Swpaul 44141502SwpaulIt doesn't: this extension is often the cause of confusion. 44241502Swpaul 44341502SwpaulConsider a certificate chain A->B->C so that A signs B and B signs C. Suppose 44441502Swpaulcertificate C contains AKID. 44541502Swpaul 44641502SwpaulThe purpose of this extension is to identify the authority certificate B. This 44741502Swpaulcan be done either by including the subject key identifier of B or its issuer 44841502Swpaulname and serial number. 44941502Swpaul 45041502SwpaulIn this latter case because it is identifying certifcate B it must contain the 45141502Swpaulissuer name and serial number of B. 45241502Swpaul 45341502SwpaulIt is often wrongly assumed that it should contain the subject name of B. If it 45441502Swpauldid this would be redundant information because it would duplicate the issuer 45541502Swpaulname of C. 45641502Swpaul 45741502Swpaul 45841502Swpaul* How can I set up a bundle of commercial root CA certificates? 45941502Swpaul 46041502SwpaulThe OpenSSL software is shipped without any root CA certificate as the 46141502SwpaulOpenSSL project does not have any policy on including or excluding 46241502Swpaulany specific CA and does not intend to set up such a policy. Deciding 46341502Swpaulabout which CAs to support is up to application developers or 46441502Swpauladministrators. 46541502Swpaul 46641502SwpaulOther projects do have other policies so you can for example extract the CA 46741502Swpaulbundle used by Mozilla and/or modssl as described in this article: 46841502Swpaul 46941502Swpaul <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html> 47041502Swpaul 47141502Swpaul 47241502Swpaul[BUILD] ======================================================================= 47341502Swpaul 47441502Swpaul* Why does the linker complain about undefined symbols? 47541502Swpaul 47641502SwpaulMaybe the compilation was interrupted, and make doesn't notice that 47767087Swpaulsomething is missing. Run "make clean; make". 47841502Swpaul 47941502SwpaulIf you used ./Configure instead of ./config, make sure that you 48041502Swpaulselected the right target. File formats may differ slightly between 48141502SwpaulOS versions (for example sparcv8/sparcv9, or a.out/elf). 48241502Swpaul 48341502SwpaulIn case you get errors about the following symbols, use the config 48441502Swpauloption "no-asm", as described in INSTALL: 48541502Swpaul 48641502Swpaul BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 487102336Salfred CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 488102336Salfred RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 48941502Swpaul bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 49041502Swpaul bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 49141502Swpaul des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 49241502Swpaul des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 49367087Swpaul 49441502SwpaulIf none of these helps, you may want to try using the current snapshot. 49541502SwpaulIf the problem persists, please submit a bug report. 49641502Swpaul 49741502Swpaul 49841502Swpaul* Why does the OpenSSL test fail with "bc: command not found"? 49941502Swpaul 50041502SwpaulYou didn't install "bc", the Unix calculator. If you want to run the 50141502Swpaultests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 50241502Swpaul 50341502Swpaul 50441502Swpaul* Why does the OpenSSL test fail with "bc: 1 no implemented"? 50541502Swpaul 50641502SwpaulOn some SCO installations or versions, bc has a bug that gets triggered 50741502Swpaulwhen you run the test suite (using "make test"). The message returned is 50841502Swpaul"bc: 1 not implemented". 50941502Swpaul 51041502SwpaulThe best way to deal with this is to find another implementation of bc 51141502Swpauland compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 51241502Swpaulfor download instructions) can be safely used, for example. 51341502Swpaul 51441502Swpaul 51541502Swpaul* Why does the OpenSSL test fail with "bc: stack empty"? 51641502Swpaul 51741502SwpaulOn some DG/ux versions, bc seems to have a too small stack for calculations 51841502Swpaulthat the OpenSSL bntest throws at it. This gets triggered when you run the 51941502Swpaultest suite (using "make test"). The message returned is "bc: stack empty". 52041502Swpaul 52141502SwpaulThe best way to deal with this is to find another implementation of bc 52241502Swpauland compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> 52341502Swpaulfor download instructions) can be safely used, for example. 52441502Swpaul 52541502Swpaul 52641502Swpaul* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? 52741502Swpaul 52867087SwpaulOn some Alpha installations running Tru64 Unix and Compaq C, the compilation 52941502Swpaulof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 53041502Swpaulmemory to continue compilation.' As far as the tests have shown, this may be 53141502Swpaula compiler bug. What happens is that it eats up a lot of resident memory 53241502Swpaulto build something, probably a table. The problem is clearly in the 533102336Salfredoptimization code, because if one eliminates optimization completely (-O0), 534102336Salfredthe compilation goes through (and the compiler consumes about 2MB of resident 53550675Swpaulmemory instead of 240MB or whatever one's limit is currently). 53650675Swpaul 53750675SwpaulThere are three options to solve this problem: 53841502Swpaul 53941502Swpaul1. set your current data segment size soft limit higher. Experience shows 54041502Swpaulthat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 54150675Swpaulthis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 54250675Swpaulkbytes to set the limit to. 54341502Swpaul 54441502Swpaul2. If you have a hard limit that is lower than what you need and you can't 54550675Swpaulget it changed, you can compile all of OpenSSL with -O0 as optimization 54641502Swpaullevel. This is however not a very nice thing to do for those who expect to 54741502Swpaulget the best result from OpenSSL. A bit more complicated solution is the 54841502Swpaulfollowing: 54941502Swpaul 55041502Swpaul----- snip:start ----- 55141502Swpaul make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 552102336Salfred sed -e 's/ -O[0-9] / -O0 /'`" 553102336Salfred rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 55450675Swpaul make 55550675Swpaul----- snip:end ----- 55650675Swpaul 55741502SwpaulThis will only compile sha_dgst.c with -O0, the rest with the optimization 55841502Swpaullevel chosen by the configuration process. When the above is done, do the 55941502Swpaultest and installation and you're set. 56050675Swpaul 56150675Swpaul3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 56241502Swpaulshould not be used and is not used in SSL/TLS nor any other recognized 56341502Swpaulprotocol in either case. 56450675Swpaul 56541502Swpaul 56641502Swpaul* Why does the OpenSSL compilation fail with "ar: command not found"? 56741502Swpaul 56841502SwpaulGetting this message is quite usual on Solaris 2, because Sun has hidden 56941502Swpaulaway 'ar' and other development commands in directories that aren't in 57050675Swpaul$PATH by default. One of those directories is '/usr/ccs/bin'. The 57150675Swpaulquickest way to fix this is to do the following (it assumes you use sh 57250675Swpaulor any sh-compatible shell): 573102336Salfred 574102336Salfred----- snip:start ----- 57550675Swpaul PATH=${PATH}:/usr/ccs/bin; export PATH 57650675Swpaul----- snip:end ----- 57750675Swpaul 57850675Swpauland then redo the compilation. What you should really do is make sure 57950675Swpaul'/usr/ccs/bin' is permanently in your $PATH, for example through your 58050675Swpaul'.profile' (again, assuming you use a sh-compatible shell). 58167087Swpaul 58250675Swpaul 58350675Swpaul* Why does the OpenSSL compilation fail on Win32 with VC++? 58467087Swpaul 58550675SwpaulSometimes, you may get reports from VC++ command line (cl) that it 58641502Swpaulcan't find standard include files like stdio.h and other weirdnesses. 58741502SwpaulOne possible cause is that the environment isn't correctly set up. 58841502SwpaulTo solve that problem for VC++ versions up to 6, one should run 58941502SwpaulVCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ 59041502Swpaulinstallation directory (somewhere under 'Program Files'). For VC++ 59141502Swpaulversion 7 (and up?), which is also called VS.NET, the file is called 592102336SalfredVSVARS32.BAT instead. 593102336SalfredThis needs to be done prior to running NMAKE, and the changes are only 59441502Swpaulvalid for the current DOS session. 59541502Swpaul 59641502Swpaul 59741502Swpaul* What is special about OpenSSL on Redhat? 59841502Swpaul 59941502SwpaulRed Hat Linux (release 7.0 and later) include a preinstalled limited 60041502Swpaulversion of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 60141502Swpaulis disabled in this version. The same may apply to other Linux distributions. 60241502SwpaulUsers may therefore wish to install more or all of the features left out. 60341502Swpaul 60441502SwpaulTo do this you MUST ensure that you do not overwrite the openssl that is in 60541502Swpaul/usr/bin on your Red Hat machine. Several packages depend on this file, 60641502Swpaulincluding sendmail and ssh. /usr/local/bin is a good alternative choice. The 60741502Swpaullibraries that come with Red Hat 7.0 onwards have different names and so are 60841502Swpaulnot affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and 60941502Swpaul/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and 61041502Swpaul/lib/libcrypto.so.2 respectively). 61141502Swpaul 61241502SwpaulPlease note that we have been advised by Red Hat attempting to recompile the 61341502Swpaulopenssl rpm with all the cryptography enabled will not work. All other 61441502Swpaulpackages depend on the original Red Hat supplied openssl package. It is also 61541502Swpaulworth noting that due to the way Red Hat supplies its packages, updates to 61641502Swpaulopenssl on each distribution never change the package version, only the 61741502Swpaulbuild number. For example, on Red Hat 7.1, the latest openssl package has 61841502Swpaulversion number 0.9.6 and build number 9 even though it contains all the 61941502Swpaulrelevant updates in packages up to and including 0.9.6b. 62072084Sphk 62141502SwpaulA possible way around this is to persuade Red Hat to produce a non-US 62241502Swpaulversion of Red Hat Linux. 623130270Snaddy 624130270SnaddyFYI: Patent numbers and expiry dates of US patents: 62541502SwpaulMDC-2: 4,908,861 13/03/2007 62641502SwpaulIDEA: 5,214,703 25/05/2010 62741502SwpaulRC5: 5,724,428 03/03/2015 62841502Swpaul 62941502Swpaul 63041502Swpaul* Why does the OpenSSL compilation fail on MacOS X? 63141502Swpaul 63241502SwpaulIf the failure happens when trying to build the "openssl" binary, with 63341502Swpaula large number of undefined symbols, it's very probable that you have 63441502SwpaulOpenSSL 0.9.6b delivered with the operating system (you can find out by 63541502Swpaulrunning '/usr/bin/openssl version') and that you were trying to build 63641502SwpaulOpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in 63741502SwpaulMacOS X has a misfeature that's quite difficult to go around. 63841502SwpaulLook in the file PROBLEMS for a more detailed explanation and for possible 63941502Swpaulsolutions. 64041502Swpaul 64141502Swpaul 64241502Swpaul* Why does the OpenSSL test suite fail on MacOS X? 64341502Swpaul 64441502SwpaulIf the failure happens when running 'make test' and the RC4 test fails, 64541502Swpaulit's very probable that you have OpenSSL 0.9.6b delivered with the 64641502Swpauloperating system (you can find out by running '/usr/bin/openssl version') 64741502Swpauland that you were trying to build OpenSSL 0.9.6d. The problem is that 64841502Swpaulthe loader ('ld') in MacOS X has a misfeature that's quite difficult to 649102336Salfredgo around and has linked the programs "openssl" and the test programs 650102336Salfredwith /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the 65141502Swpaullibraries you just built. 65250675SwpaulLook in the file PROBLEMS for a more detailed explanation and for possible 65341502Swpaulsolutions. 65441502Swpaul 65541502Swpaul* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? 65641502Swpaul 65741502SwpaulFailure in BN_sqr test is most likely caused by a failure to configure the 65841502Swpaultoolkit for current platform or lack of support for the platform in question. 65941502SwpaulRun './config -t' and './apps/openssl version -p'. Do these platform 66041502Swpaulidentifiers match? If they don't, then you most likely failed to run 66141502Swpaul./config and you're hereby advised to do so before filing a bug report. 66241502SwpaulIf ./config itself fails to run, then it's most likely problem with your 66341502Swpaullocal environment and you should turn to your system administrator (or 66441502Swpaulsimilar). If identifiers match (and/or no alternative identifier is 66541502Swpaulsuggested by ./config script), then the platform is unsupported. There might 66641502Swpaulor might not be a workaround. Most notably on SPARC64 platforms with GNU 66741502SwpaulC compiler you should be able to produce a working build by running 66841502Swpaul'./config -m32'. I understand that -m32 might not be what you want/need, 66941502Swpaulbut the build should be operational. For further details turn to 67041502Swpaul<openssl-dev@openssl.org>. 67141502Swpaul 67250675Swpaul* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? 67350675Swpaul 67450675SwpaulAs of 0.9.7 assembler routines were overhauled for position independence 67541502Swpaulof the machine code, which is essential for shared library support. For 67641502Swpaulsome reason OpenBSD is equipped with an out-of-date GNU assembler which 67750675Swpaulfinds the new code offensive. To work around the problem, configure with 67841502Swpaulno-asm (and sacrifice a great deal of performance) or patch your assembler 67941502Swpaulaccording to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. 68041502SwpaulFor your convenience a pre-compiled replacement binary is provided at 68141502Swpaul<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. 68241502SwpaulReportedly elder *BSD a.out platforms also suffer from this problem and 68341502Swpaulremedy should be same. Provided binary is statically linked and should be 68441502Swpaulworking across wider range of *BSD branches, not just OpenBSD. 68541502Swpaul 68641502Swpaul* Why does the OpenSSL test suite fail in sha512t on x86 CPU? 68741502Swpaul 688102336SalfredIf the test program in question fails withs SIGILL, Illegal Instruction 689102336Salfredexception, then you more than likely to run SSE2-capable CPU, such as 69041502SwpaulIntel P4, under control of kernel which does not support SSE2 69141502Swpaulinstruction extentions. See accompanying INSTALL file and 69241502SwpaulOPENSSL_ia32cap(3) documentation page for further information. 69350675Swpaul 69441502Swpaul* Why does compiler fail to compile sha512.c? 69550675Swpaul 69650675SwpaulOpenSSL SHA-512 implementation depends on compiler support for 64-bit 69750675Swpaulinteger type. Few elder compilers [ULTRIX cc, SCO compiler to mention a 69850675Swpaulcouple] lack support for this and therefore are incapable of compiling 69950675Swpaulthe module in question. The recommendation is to disable SHA-512 by 70041502Swpauladding no-sha512 to ./config [or ./Configure] command line. Another 70150675Swpaulpossible alternative might be to switch to GCC. 70241502Swpaul 70341502Swpaul* Test suite still fails, what to do? 70441502Swpaul 70541502SwpaulAnother common reason for failure to complete some particular test is 70641502Swpaulsimply bad code generated by a buggy component in toolchain or deficiency 70741502Swpaulin run-time environment. There are few cases documented in PROBLEMS file, 70841502Swpaulconsult it for possible workaround before you beat the drum. Even if you 70941502Swpauldon't find solution or even mention there, do reserve for possibility of 71041502Swpaula compiler bug. Compiler bugs might appear in rather bizarre ways, they 71141502Swpaulnever make sense, and tend to emerge when you least expect them. In order 71241502Swpaulto identify one, drop optimization level, e.g. by editing CFLAG line in 71341502Swpaultop-level Makefile, recompile and re-run the test. 71450675Swpaul 71550675Swpaul* I think I've found a bug, what should I do? 71641502Swpaul 71750675SwpaulIf you are a new user then it is quite likely you haven't found a bug and 71850675Swpaulsomething is happening you aren't familiar with. Check this FAQ, the associated 71950675Swpauldocumentation and the mailing lists for similar queries. If you are still 72050675Swpaulunsure whether it is a bug or not submit a query to the openssl-users mailing 72150675Swpaullist. 72250675Swpaul 72372012Sphk 72450675Swpaul* I'm SURE I've found a bug, how do I report it? 72550675Swpaul 72650675SwpaulBug reports with no security implications should be sent to the request 72741502Swpaultracker. This can be done by mailing the report to <rt@openssl.org> (or its 72841502Swpaulalias <openssl-bugs@openssl.org>), please note that messages sent to the 72941502Swpaulrequest tracker also appear in the public openssl-dev mailing list. 730102336Salfred 731102336SalfredThe report should be in plain text. Any patches should be sent as 73250675Swpaulplain text attachments because some mailers corrupt patches sent inline. 73350675SwpaulIf your issue affects multiple versions of OpenSSL check any patches apply 73450675Swpaulcleanly and, if possible include patches to each affected version. 73550675Swpaul 73650675SwpaulThe report should be given a meaningful subject line briefly summarising the 73750675Swpaulissue. Just "bug in OpenSSL" or "bug in OpenSSL 0.9.8n" is not very helpful. 73850675Swpaul 73950675SwpaulBy sending reports to the request tracker the bug can then be given a priority 74050675Swpauland assigned to the appropriate maintainer. The history of discussions can be 74150675Swpaulaccessed and if the issue has been addressed or a reason why not. If patches 74250675Swpaulare only sent to openssl-dev they can be mislaid if a team member has to 74350675Swpaulwade through months of old messages to review the discussion. 74450675Swpaul 74550675SwpaulSee also <URL: http://www.openssl.org/support/rt.html> 74650675Swpaul 74750675Swpaul 74850675Swpaul* I've found a security issue, how do I report it? 74950675Swpaul 75050675SwpaulIf you think your bug has security implications then please send it to 75150675Swpaulopenssl-security@openssl.org if you don't get a prompt reply at least 75250675Swpaulacknowledging receipt then resend or mail it directly to one of the 75350675Swpaulmore active team members (e.g. Steve). 75450675Swpaul 75550675Swpaul[PROG] ======================================================================== 75650675Swpaul 75750675Swpaul* Is OpenSSL thread-safe? 75850675Swpaul 75941502SwpaulYes (with limitations: an SSL connection may not concurrently be used 76041502Swpaulby multiple threads). On Windows and many Unix systems, OpenSSL 76141502Swpaulautomatically uses the multi-threaded versions of the standard 76241502Swpaullibraries. If your platform is not one of these, consult the INSTALL 763102336Salfredfile. 764102336Salfred 76549611SwpaulMulti-threaded applications must provide two callback functions to 76641502SwpaulOpenSSL by calling CRYPTO_set_locking_callback() and 76741502SwpaulCRYPTO_set_id_callback(), for all versions of OpenSSL up to and 76841502Swpaulincluding 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback() 76941502Swpauland associated APIs are deprecated by CRYPTO_THREADID_set_callback() 77041502Swpauland friends. This is described in the threads(3) manpage. 77141502Swpaul 77249611Swpaul* I've compiled a program under Windows and it crashes: why? 77349611Swpaul 77449611SwpaulThis is usually because you've missed the comment in INSTALL.W32. 77549611SwpaulYour application must link against the same version of the Win32 77641502SwpaulC-Runtime against which your openssl libraries were linked. The 77741502Swpauldefault version for OpenSSL is /MD - "Multithreaded DLL". 77841502Swpaul 77941502SwpaulIf you are using Microsoft Visual C++'s IDE (Visual Studio), in 78049611Swpaulmany cases, your new project most likely defaulted to "Debug 78141502SwpaulSinglethreaded" - /ML. This is NOT interchangeable with /MD and your 78241502Swpaulprogram will crash, typically on the first BIO related read or write 78341502Swpauloperation. 78441502Swpaul 78541502SwpaulFor each of the six possible link stage configurations within Win32, 78641502Swpaulyour application must link against the same by which OpenSSL was 787102336Salfredbuilt. If you are using MS Visual C++ (Studio) this can be changed 788102336Salfredby: 78949611Swpaul 79041502Swpaul 1. Select Settings... from the Project Menu. 79141502Swpaul 2. Select the C/C++ Tab. 79241502Swpaul 3. Select "Code Generation from the "Category" drop down list box 79341502Swpaul 4. Select the Appropriate library (see table below) from the "Use 79449611Swpaul run-time library" drop down list box. Perform this step for both 79541502Swpaul your debug and release versions of your application (look at the 79649611Swpaul top left of the settings panel to change between the two) 79749611Swpaul 79841502Swpaul Single Threaded /ML - MS VC++ often defaults to 79993818Sjhb this for the release 80093818Sjhb version of a new project. 80141502Swpaul Debug Single Threaded /MLd - MS VC++ often defaults to 80241502Swpaul this for the debug version 80341502Swpaul of a new project. 80472813Swpaul Multithreaded /MT 80541502Swpaul Debug Multithreaded /MTd 80649611Swpaul Multithreaded DLL /MD - OpenSSL defaults to this. 807127135Snjl Debug Multithreaded DLL /MDd 80849611Swpaul 80949611SwpaulNote that debug and release libraries are NOT interchangeable. If you 81049611Swpaulbuilt OpenSSL with /MD your application must use /MD and cannot use /MDd. 81149611Swpaul 81241502SwpaulAs per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL 81341502Swpaul.DLLs compiled with some specific run-time option [we insist on the 81441502Swpauldefault /MD] can be deployed with application compiled with different 81549611Swpauloption or even different compiler. But there is a catch! Instead of 81649611Swpaulre-compiling OpenSSL toolkit, as you would have to with prior versions, 81749611Swpaulyou have to compile small C snippet with compiler and/or options of 81841502Swpaulyour choice. The snippet gets installed as 81949611Swpaul<install-root>/include/openssl/applink.c and should be either added to 820127135Snjlyour application project or simply #include-d in one [and only one] 82149611Swpaulof your application source files. Failure to link this shim module 82249611Swpaulinto your application manifests itself as fatal "no OPENSSL_Applink" 82349611Swpaulrun-time error. An explicit reminder is due that in this situation 82441502Swpaul[mixing compiler options] it is as important to add CRYPTO_malloc_init 82549611Swpaulprior first call to OpenSSL. 82641502Swpaul 82741502Swpaul* How do I read or write a DER encoded buffer using the ASN1 functions? 82841502Swpaul 82950675SwpaulYou have two options. You can either use a memory BIO in conjunction 83050675Swpaulwith the i2d_*_bio() or d2i_*_bio() functions or you can use the 83150675Swpauli2d_*(), d2i_*() functions directly. Since these are often the 83241502Swpaulcause of grief here are some code fragments using PKCS7 as an example: 83341502Swpaul 83441502Swpaul unsigned char *buf, *p; 83541502Swpaul int len; 83641502Swpaul 83741502Swpaul len = i2d_PKCS7(p7, NULL); 83841502Swpaul buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 83941502Swpaul p = buf; 84041502Swpaul i2d_PKCS7(p7, &p); 84141502Swpaul 84241502SwpaulAt this point buf contains the len bytes of the DER encoding of 84350675Swpaulp7. 84451657Swpaul 84550675SwpaulThe opposite assumes we already have len bytes in buf: 84650675Swpaul 84741502Swpaul unsigned char *p; 84849611Swpaul p = buf; 84949611Swpaul p7 = d2i_PKCS7(NULL, &p, len); 85041502Swpaul 85141502SwpaulAt this point p7 contains a valid PKCS7 structure of NULL if an error 85241502Swpauloccurred. If an error occurred ERR_print_errors(bio) should give more 85341502Swpaulinformation. 85441502Swpaul 85541502SwpaulThe reason for the temporary variable 'p' is that the ASN1 functions 856121816Sbrooksincrement the passed pointer so it is ready to read or write the next 85741502Swpaulstructure. This is often a cause of problems: without the temporary 858134442Srwatsonvariable the buffer pointer is changed to point just after the data 859134442Srwatsonthat has been read or written. This may well be uninitialized data 86041502Swpauland attempts to free the buffer will have unpredictable results 86141502Swpaulbecause it no longer points to the same address. 86241502Swpaul 86341502Swpaul 86441502Swpaul* OpenSSL uses DER but I need BER format: does OpenSSL support BER? 86543515Swpaul 86641502SwpaulThe short answer is yes, because DER is a special case of BER and OpenSSL 86750675SwpaulASN1 decoders can process BER. 86850675Swpaul 86950675SwpaulThe longer answer is that ASN1 structures can be encoded in a number of 87050675Swpauldifferent ways. One set of ways is the Basic Encoding Rules (BER) with various 87150675Swpaulpermissible encodings. A restriction of BER is the Distinguished Encoding 87249611SwpaulRules (DER): these uniquely specify how a given structure is encoded. 87341502Swpaul 87441502SwpaulTherefore, because DER is a special case of BER, DER is an acceptable encoding 87541502Swpaulfor BER. 87641502Swpaul 87763090Sarchie 87841502Swpaul* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 879106936Ssam 88041502SwpaulThis usually happens when you try compiling something using the PKCS#12 881113609Snjlmacros with a C++ compiler. There is hardly ever any need to use the 882112872SnjlPKCS#12 macros in a program, it is much easier to parse and create 883112872SnjlPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 884112872Snjldocumented in doc/openssl.txt and with examples in demos/pkcs12. The 885112872Snjl'pkcs12' application has to use the macros because it prints out 886112872Snjldebugging information. 887113609Snjl 888112872Snjl 889112872Snjl* I've called <some function> and it fails, why? 890112872Snjl 89141502SwpaulBefore submitting a report or asking in one of the mailing lists, you 89250675Swpaulshould try to determine the cause. In particular, you should call 893112872SnjlERR_print_errors() or ERR_print_errors_fp() after the failed call 89450675Swpauland see if the message helps. Note that the problem may occur earlier 89549611Swpaulthan you think -- you should check for errors after every call where 89641502Swpaulit is possible, otherwise the actual problem may be hidden because 89741502Swpaulsome OpenSSL functions clear the error state. 898113609Snjl 899113609Snjl 900113609Snjl* I just get a load of numbers for the error output, what do they mean? 901113609Snjl 902113609SnjlThe actual format is described in the ERR_print_errors() manual page. 903113609SnjlYou should call the function ERR_load_crypto_strings() before hand and 904113609Snjlthe message will be output in text form. If you can't do this (for example 905102336Salfredit is a pre-compiled binary) you can use the errstr utility on the error 906102336Salfredcode itself (the hex digits after the second colon). 90749611Swpaul 90849611Swpaul 90949611Swpaul* Why do I get errors about unknown algorithms? 91049611Swpaul 91149611SwpaulThe cause is forgetting to load OpenSSL's table of algorithms with 91249611SwpaulOpenSSL_add_all_algorithms(). See the manual page for more information. This 913112880Sjhbcan cause several problems such as being unable to read in an encrypted 91467087SwpaulPEM file, unable to decrypt a PKCS#12 file or signature failure when 91549611Swpaulverifying certificates. 91649611Swpaul 917113609Snjl* Why can't the OpenSSH configure script detect OpenSSL? 918113609Snjl 919113609SnjlSeveral reasons for problems with the automatic detection exist. 920113609SnjlOpenSSH requires at least version 0.9.5a of the OpenSSL libraries. 921113812SimpSometimes the distribution has installed an older version in the system 922113609Snjllocations that is detected instead of a new one installed. The OpenSSL 923112872Snjllibrary might have been compiled for another CPU or another mode (32/64 bits). 924113609SnjlPermissions might be wrong. 925113609Snjl 926112872SnjlThe general answer is to check the config.log file generated when running 927113609Snjlthe OpenSSH configure script. It should contain the detailed information 92850675Swpaulon why the OpenSSL library was not detected or considered incompatible. 929112872Snjl 930112872Snjl 931112872Snjl* Can I use OpenSSL's SSL library with non-blocking I/O? 932112872Snjl 933112872SnjlYes; make sure to read the SSL_get_error(3) manual page! 934112872Snjl 93549611SwpaulA pitfall to avoid: Don't assume that SSL_read() will just read from 936112872Snjlthe underlying transport or that SSL_write() will just write to it -- 937112872Snjlit is also possible that SSL_write() cannot do any useful work until 938112872Snjlthere is data to read, or that SSL_read() cannot do anything until it 939112872Snjlis possible to send data. One reason for this is that the peer may 94049611Swpaulrequest a new TLS/SSL handshake at any time during the protocol, 94167087Swpaulrequiring a bi-directional message exchange; both SSL_read() and 94267087SwpaulSSL_write() will try to continue any pending handshake. 94349611Swpaul 94449611Swpaul 94549611Swpaul* Why doesn't my server application receive a client certificate? 94649611Swpaul 94741502SwpaulDue to the TLS protocol definition, a client will only send a certificate, 94841502Swpaulif explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the 94941502SwpaulSSL_CTX_set_verify() function to enable the use of client certificates. 950102336Salfred 951102336Salfred 95241502Swpaul* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? 95341502Swpaul 95441502SwpaulFor OpenSSL 0.9.7 the OID table was extended and corrected. In earlier 95541502Swpaulversions, uniqueIdentifier was incorrectly used for X.509 certificates. 95641502SwpaulThe correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. 95741502SwpaulChange your code to use the new name when compiling against OpenSSL 0.9.7. 95841502Swpaul 95941502Swpaul 96041502Swpaul* I think I've detected a memory leak, is this a bug? 96141502Swpaul 96241502SwpaulIn most cases the cause of an apparent memory leak is an OpenSSL internal table 96341502Swpaulthat is allocated when an application starts up. Since such tables do not grow 96441502Swpaulin size over time they are harmless. 96541502Swpaul 96641502SwpaulThese internal tables can be freed up when an application closes using various 96741502Swpaulfunctions. Currently these include following: 96841502Swpaul 96941502SwpaulThread-local cleanup functions: 97041502Swpaul 97141502Swpaul ERR_remove_state() 97241502Swpaul 97341502SwpaulApplication-global cleanup functions that are aware of usage (and therefore 97441502Swpaulthread-safe): 97541502Swpaul 97641502Swpaul ENGINE_cleanup() and CONF_modules_unload() 97741502Swpaul 97841502Swpaul"Brutal" (thread-unsafe) Application-global cleanup functions: 97941502Swpaul 98041502Swpaul ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). 98141502Swpaul 98241502Swpaul 98341502Swpaul* Why does Valgrind complain about the use of uninitialized data? 984102336Salfred 985102336SalfredWhen OpenSSL's PRNG routines are called to generate random numbers the supplied 98641502Swpaulbuffer contents are mixed into the entropy pool: so it technically does not 98741502Swpaulmatter whether the buffer is initialized at this point or not. Valgrind (and 98841502Swpaulother test tools) will complain about this. When using Valgrind, make sure the 98941502SwpaulOpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) 99041502Swpaulto get rid of these warnings. 99141502Swpaul 99241502Swpaul 99341502Swpaul* Why doesn't a memory BIO work when a file does? 99441502Swpaul 99541502SwpaulThis can occur in several cases for example reading an S/MIME email message. 99641502SwpaulThe reason is that a memory BIO can do one of two things when all the data 99741502Swpaulhas been read from it. 99850675Swpaul 99948745SwpaulThe default behaviour is to indicate that no more data is available and that 100041502Swpaulthe call should be retried, this is to allow the application to fill up the BIO 100141502Swpaulagain if necessary. 100241502Swpaul 100341502SwpaulAlternatively it can indicate that no more data is available and that EOF has 100441502Swpaulbeen reached. 100541502Swpaul 100641502SwpaulIf a memory BIO is to behave in the same way as a file this second behaviour 100741502Swpaulis needed. This must be done by calling: 100841502Swpaul 100941502Swpaul BIO_set_mem_eof_return(bio, 0); 101041502Swpaul 101141502SwpaulSee the manual pages for more details. 101241502Swpaul 101341502Swpaul 101441502Swpaul* Where are the declarations and implementations of d2i_X509() etc? 101541502Swpaul 101641502SwpaulThese are defined and implemented by macros of the form: 101741502Swpaul 1018102336Salfred 1019102336Salfred DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) 102098995Salfred 102164837SdwmaloneThe implementation passes an ASN1 "template" defining the structure into an 102250675SwpaulASN1 interpreter using generalised functions such as ASN1_item_d2i(). 102350675Swpaul 102450675Swpaul 102550675Swpaul=============================================================================== 102641502Swpaul