FAQ revision 79998
1117521SnjlOpenSSL - Frequently Asked Questions 2281075Sdim-------------------------------------- 3281075Sdim 4281075Sdim[MISC] Miscellaneous questions 5281075Sdim 6281075Sdim* Which is the current version of OpenSSL? 7281075Sdim* Where is the documentation? 8281075Sdim* How can I contact the OpenSSL developers? 9281075Sdim* Where can I get a compiled version of OpenSSL? 10281075Sdim* Why aren't tools like 'autoconf' and 'libtool' used? 11281075Sdim 12281075Sdim[LEGAL] Legal questions 13281075Sdim 14281075Sdim* Do I need patent licenses to use OpenSSL? 15281075Sdim* Can I use OpenSSL with GPL software? 16281075Sdim 17281075Sdim[USER] Questions on using the OpenSSL applications 18281075Sdim 19281075Sdim* Why do I get a "PRNG not seeded" error message? 20281075Sdim* Why do I get an "unable to write 'random state'" error message? 21281075Sdim* How do I create certificates or certificate requests? 22281075Sdim* Why can't I create certificate requests? 23281075Sdim* Why does <SSL program> fail with a certificate verify error? 24281075Sdim* Why can I only use weak ciphers when I connect to a server using OpenSSL? 25281075Sdim* How can I create DSA certificates? 26281075Sdim* Why can't I make an SSL connection using a DSA certificate? 27281075Sdim* How can I remove the passphrase on a private key? 28281075Sdim* Why can't I use OpenSSL certificates with SSL client authentication? 29281075Sdim* Why does my browser give a warning about a mismatched hostname? 30281075Sdim 31281075Sdim[BUILD] Questions about building and testing OpenSSL 32281075Sdim 33281075Sdim* Why does the linker complain about undefined symbols? 34281075Sdim* Why does the OpenSSL test fail with "bc: command not found"? 35281075Sdim* Why does the OpenSSL test fail with "bc: 1 no implemented"? 36281075Sdim* Why does the OpenSSL compilation fail on Alpha True64 Unix? 37281075Sdim* Why does the OpenSSL compilation fail with "ar: command not found"? 38281075Sdim* Why does the OpenSSL compilation fail on Win32 with VC++? 39281075Sdim 40281075Sdim[PROG] Questions about programming with OpenSSL 41281075Sdim 42281075Sdim* Is OpenSSL thread-safe? 43281075Sdim* I've compiled a program under Windows and it crashes: why? 44281075Sdim* How do I read or write a DER encoded buffer using the ASN1 functions? 45281075Sdim* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 46281075Sdim* I've called <some function> and it fails, why? 47281075Sdim* I just get a load of numbers for the error output, what do they mean? 48281075Sdim* Why do I get errors about unknown algorithms? 49281075Sdim* Why can't the OpenSSH configure script detect OpenSSL? 50281075Sdim* Can I use OpenSSL's SSL library with non-blocking I/O? 51281075Sdim* Why doesn't my server application receive a client certificate? 52281075Sdim 53281075Sdim=============================================================================== 54281075Sdim 55281075Sdim[MISC] ======================================================================== 56281075Sdim 57281075Sdim* Which is the current version of OpenSSL? 58281075Sdim 59281075SdimThe current version is available from <URL: http://www.openssl.org>. 60281075SdimOpenSSL 0.9.6b was released on July 9th, 2001. 61281075Sdim 62281075SdimIn addition to the current stable release, you can also access daily 63281075Sdimsnapshots of the OpenSSL development version at <URL: 64281075Sdimftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. 65281075Sdim 66281075Sdim 67281075Sdim* Where is the documentation? 68281075Sdim 69281075SdimOpenSSL is a library that provides cryptographic functionality to 70281075Sdimapplications such as secure web servers. Be sure to read the 71281075Sdimdocumentation of the application you want to use. The INSTALL file 72281075Sdimexplains how to install this library. 73281075Sdim 74281075SdimOpenSSL includes a command line utility that can be used to perform a 75281075Sdimvariety of cryptographic functions. It is described in the openssl(1) 76281075Sdimmanpage. Documentation for developers is currently being written. A 77281075Sdimfew manual pages already are available; overviews over libcrypto and 78281075Sdimlibssl are given in the crypto(3) and ssl(3) manpages. 79281075Sdim 80281075SdimThe OpenSSL manpages are installed in /usr/local/ssl/man/ (or a 81281075Sdimdifferent directory if you specified one as described in INSTALL). 82281075SdimIn addition, you can read the most current versions at 83281075Sdim<URL: http://www.openssl.org/docs/>. 84281075Sdim 85281075SdimFor information on parts of libcrypto that are not yet documented, you 86281075Sdimmight want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's 87281075Sdimpredecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much 88281075Sdimof this still applies to OpenSSL. 89281075Sdim 90281075SdimThere is some documentation about certificate extensions and PKCS#12 91281075Sdimin doc/openssl.txt 92281075Sdim 93281075SdimThe original SSLeay documentation is included in OpenSSL as 94281075Sdimdoc/ssleay.txt. It may be useful when none of the other resources 95281075Sdimhelp, but please note that it reflects the obsolete version SSLeay 96281075Sdim0.6.6. 97281075Sdim 98281075Sdim 99281075Sdim* How can I contact the OpenSSL developers? 100281075Sdim 101281075SdimThe README file describes how to submit bug reports and patches to 102281075SdimOpenSSL. Information on the OpenSSL mailing lists is available from 103281075Sdim<URL: http://www.openssl.org>. 104281075Sdim 105281075Sdim 106281075Sdim* Where can I get a compiled version of OpenSSL? 107281075Sdim 108281075SdimSome applications that use OpenSSL are distributed in binary form. 109281075SdimWhen using such an application, you don't need to install OpenSSL 110281075Sdimyourself; the application will include the required parts (e.g. DLLs). 111281075Sdim 112281075SdimIf you want to install OpenSSL on a Windows system and you don't have 113281075Sdima C compiler, read the "Mingw32" section of INSTALL.W32 for information 114281075Sdimon how to obtain and install the free GNU C compiler. 115281075Sdim 116281075SdimA number of Linux and *BSD distributions include OpenSSL. 117281075Sdim 118281075Sdim 119281075Sdim* Why aren't tools like 'autoconf' and 'libtool' used? 120281075Sdim 121281075Sdimautoconf will probably be used in future OpenSSL versions. If it was 122281075Sdimless Unix-centric, it might have been used much earlier. 123281075Sdim 124281075Sdim 125281075Sdim[LEGAL] ======================================================================= 126281075Sdim 127281075Sdim* Do I need patent licenses to use OpenSSL? 128281075Sdim 129281075SdimThe patents section of the README file lists patents that may apply to 130281075Sdimyou if you want to use OpenSSL. For information on intellectual 131281075Sdimproperty rights, please consult a lawyer. The OpenSSL team does not 132281075Sdimoffer legal advice. 133281075Sdim 134281075SdimYou can configure OpenSSL so as not to use RC5 and IDEA by using 135281075Sdim ./config no-rc5 no-idea 136281075Sdim 137281075Sdim 138281075Sdim* Can I use OpenSSL with GPL software? 139281075Sdim 140281075SdimOn many systems including the major Linux and BSD distributions, yes (the 141281075SdimGPL does not place restrictions on using libraries that are part of the 142281075Sdimnormal operating system distribution). 143281075Sdim 144281075SdimOn other systems, the situation is less clear. Some GPL software copyright 145281075Sdimholders claim that you infringe on their rights if you use OpenSSL with 146281075Sdimtheir software on operating systems that don't normally include OpenSSL. 147281075Sdim 148281075SdimIf you develop open source software that uses OpenSSL, you may find it 149281075Sdimuseful to choose an other license than the GPL, or state explicitely that 150281075Sdim"This program is released under the GPL with the additional exemption that 151281075Sdimcompiling, linking, and/or using OpenSSL is allowed." If you are using 152281075SdimGPL software developed by others, you may want to ask the copyright holder 153281075Sdimfor permission to use their software with OpenSSL. 154281075Sdim 155281075Sdim 156281075Sdim[USER] ======================================================================== 157281075Sdim 158281075Sdim* Why do I get a "PRNG not seeded" error message? 159281075Sdim 160281075SdimCryptographic software needs a source of unpredictable data to work 161281075Sdimcorrectly. Many open source operating systems provide a "randomness 162281075Sdimdevice" that serves this purpose. On other systems, applications have 163281075Sdimto call the RAND_add() or RAND_seed() function with appropriate data 164281075Sdimbefore generating keys or performing public key encryption. 165281075Sdim(These functions initialize the pseudo-random number generator, PRNG.) 166281075Sdim 167281075SdimSome broken applications do not do this. As of version 0.9.5, the 168281075SdimOpenSSL functions that need randomness report an error if the random 169281075Sdimnumber generator has not been seeded with at least 128 bits of 170281075Sdimrandomness. If this error occurs, please contact the author of the 171281075Sdimapplication you are using. It is likely that it never worked 172281075Sdimcorrectly. OpenSSL 0.9.5 and later make the error visible by refusing 173281075Sdimto perform potentially insecure encryption. 174281075Sdim 175281075SdimOn systems without /dev/urandom and /dev/random, it is a good idea to 176281075Sdimuse the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for 177281075Sdimdetails. Starting with version 0.9.7, OpenSSL will automatically look 178281075Sdimfor an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and 179281075Sdim/etc/entropy. 180281075Sdim 181281075SdimMost components of the openssl command line utility automatically try 182281075Sdimto seed the random number generator from a file. The name of the 183281075Sdimdefault seeding file is determined as follows: If environment variable 184281075SdimRANDFILE is set, then it names the seeding file. Otherwise if 185281075Sdimenvironment variable HOME is set, then the seeding file is $HOME/.rnd. 186281075SdimIf neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will 187281075Sdimuse file .rnd in the current directory while OpenSSL 0.9.6a uses no 188281075Sdimdefault seeding file at all. OpenSSL 0.9.6b and later will behave 189281075Sdimsimilarly to 0.9.6a, but will use a default of "C:" for HOME on 190281075SdimWindows systems if the environment variable has not been set. 191281075Sdim 192281075SdimIf the default seeding file does not exist or is too short, the "PRNG 193281075Sdimnot seeded" error message may occur. 194281075Sdim 195281075SdimThe openssl command line utility will write back a new state to the 196281075Sdimdefault seeding file (and create this file if necessary) unless 197281075Sdimthere was no sufficient seeding. 198281075Sdim 199281075SdimPointing $RANDFILE to an Entropy Gathering Daemon socket does not work. 200281075SdimUse the "-rand" option of the OpenSSL command line tools instead. 201281075SdimThe $RANDFILE environment variable and $HOME/.rnd are only used by the 202281075SdimOpenSSL command line tools. Applications using the OpenSSL library 203281075Sdimprovide their own configuration options to specify the entropy source, 204281075Sdimplease check out the documentation coming the with application. 205281075Sdim 206281075SdimFor Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested 207281075Sdiminstalling the SUNski package from Sun patch 105710-01 (Sparc) which 208281075Sdimadds a /dev/random device and make sure it gets used, usually through 209281075Sdim$RANDFILE. There are probably similar patches for the other Solaris 210281075Sdimversions. However, be warned that /dev/random is usually a blocking 211281075Sdimdevice, which may have some effects on OpenSSL. 212281075Sdim 213281075Sdim 214281075Sdim* Why do I get an "unable to write 'random state'" error message? 215281075Sdim 216281075Sdim 217281075SdimSometimes the openssl command line utility does not abort with 218281075Sdima "PRNG not seeded" error message, but complains that it is 219281075Sdim"unable to write 'random state'". This message refers to the 220281075Sdimdefault seeding file (see previous answer). A possible reason 221281075Sdimis that no default filename is known because neither RANDFILE 222281075Sdimnor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the 223281075Sdimcurrent directory in this case, but this has changed with 0.9.6a.) 224281075Sdim 225281075Sdim 226281075Sdim* How do I create certificates or certificate requests? 227281075Sdim 228281075SdimCheck out the CA.pl(1) manual page. This provides a simple wrapper round 229281075Sdimthe 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check 230281075Sdimout the manual pages for the individual utilities and the certificate 231281075Sdimextensions documentation (currently in doc/openssl.txt). 232281075Sdim 233281075Sdim 234281075Sdim* Why can't I create certificate requests? 235281075Sdim 236281075SdimYou typically get the error: 237281075Sdim 238281075Sdim unable to find 'distinguished_name' in config 239281075Sdim problems making Certificate Request 240281075Sdim 241281075SdimThis is because it can't find the configuration file. Check out the 242281075SdimDIAGNOSTICS section of req(1) for more information. 243281075Sdim 244281075Sdim 245281075Sdim* Why does <SSL program> fail with a certificate verify error? 246281075Sdim 247281075SdimThis problem is usually indicated by log messages saying something like 248281075Sdim"unable to get local issuer certificate" or "self signed certificate". 249281075SdimWhen a certificate is verified its root CA must be "trusted" by OpenSSL 250281075Sdimthis typically means that the CA certificate must be placed in a directory 251281075Sdimor file and the relevant program configured to read it. The OpenSSL program 252281075Sdim'verify' behaves in a similar way and issues similar error messages: check 253281075Sdimthe verify(1) program manual page for more information. 254281075Sdim 255281075Sdim 256281075Sdim* Why can I only use weak ciphers when I connect to a server using OpenSSL? 257281075Sdim 258281075SdimThis is almost certainly because you are using an old "export grade" browser 259281075Sdimwhich only supports weak encryption. Upgrade your browser to support 128 bit 260281075Sdimciphers. 261281075Sdim 262281075Sdim 263281075Sdim* How can I create DSA certificates? 264281075Sdim 265281075SdimCheck the CA.pl(1) manual page for a DSA certificate example. 266281075Sdim 267281075Sdim 268281075Sdim* Why can't I make an SSL connection to a server using a DSA certificate? 269281075Sdim 270281075SdimTypically you'll see a message saying there are no shared ciphers when 271281075Sdimthe same setup works fine with an RSA certificate. There are two possible 272281075Sdimcauses. The client may not support connections to DSA servers most web 273281075Sdimbrowsers (including Netscape and MSIE) only support connections to servers 274281075Sdimsupporting RSA cipher suites. The other cause is that a set of DH parameters 275281075Sdimhas not been supplied to the server. DH parameters can be created with the 276281075Sdimdhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: 277281075Sdimcheck the source to s_server in apps/s_server.c for an example. 278281075Sdim 279281075Sdim 280281075Sdim* How can I remove the passphrase on a private key? 281281075Sdim 282281075SdimFirstly you should be really *really* sure you want to do this. Leaving 283281075Sdima private key unencrypted is a major security risk. If you decide that 284281075Sdimyou do have to do this check the EXAMPLES sections of the rsa(1) and 285281075Sdimdsa(1) manual pages. 286281075Sdim 287281075Sdim 288281075Sdim* Why can't I use OpenSSL certificates with SSL client authentication? 289281075Sdim 290281075SdimWhat will typically happen is that when a server requests authentication 291281075Sdimit will either not include your certificate or tell you that you have 292281075Sdimno client certificates (Netscape) or present you with an empty list box 293281075Sdim(MSIE). The reason for this is that when a server requests a client 294281075Sdimcertificate it includes a list of CAs names which it will accept. Browsers 295281075Sdimwill only let you select certificates from the list on the grounds that 296281075Sdimthere is little point presenting a certificate which the server will 297281075Sdimreject. 298281075Sdim 299281075SdimThe solution is to add the relevant CA certificate to your servers "trusted 300281075SdimCA list". How you do this depends on the server sofware in uses. You can 301281075Sdimprint out the servers list of acceptable CAs using the OpenSSL s_client tool: 302281075Sdim 303281075Sdimopenssl s_client -connect www.some.host:443 -prexit 304281075Sdim 305281075SdimIf your server only requests certificates on certain URLs then you may need 306281075Sdimto manually issue an HTTP GET command to get the list when s_client connects: 307281075Sdim 308281075SdimGET /some/page/needing/a/certificate.html 309281075Sdim 310281075SdimIf your CA does not appear in the list then this confirms the problem. 311281075Sdim 312281075Sdim 313281075Sdim* Why does my browser give a warning about a mismatched hostname? 314281075Sdim 315281075SdimBrowsers expect the server's hostname to match the value in the commonName 316281075Sdim(CN) field of the certificate. If it does not then you get a warning. 317281075Sdim 318281075Sdim 319281075Sdim[BUILD] ======================================================================= 320281075Sdim 321281075Sdim* Why does the linker complain about undefined symbols? 322281075Sdim 323281075SdimMaybe the compilation was interrupted, and make doesn't notice that 324281075Sdimsomething is missing. Run "make clean; make". 325281075Sdim 326281075SdimIf you used ./Configure instead of ./config, make sure that you 327281075Sdimselected the right target. File formats may differ slightly between 328281075SdimOS versions (for example sparcv8/sparcv9, or a.out/elf). 329281075Sdim 330281075SdimIn case you get errors about the following symbols, use the config 331281075Sdimoption "no-asm", as described in INSTALL: 332281075Sdim 333281075Sdim BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, 334281075Sdim CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, 335281075Sdim RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, 336281075Sdim bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, 337281075Sdim bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, 338281075Sdim des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, 339281075Sdim des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order 340281075Sdim 341281075SdimIf none of these helps, you may want to try using the current snapshot. 342281075SdimIf the problem persists, please submit a bug report. 343281075Sdim 344281075Sdim 345281075Sdim* Why does the OpenSSL test fail with "bc: command not found"? 346281075Sdim 347281075SdimYou didn't install "bc", the Unix calculator. If you want to run the 348281075Sdimtests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. 349281075Sdim 350281075Sdim 351281075Sdim* Why does the OpenSSL test fail with "bc: 1 no implemented"? 352281075Sdim 353281075SdimOn some SCO installations or versions, bc has a bug that gets triggered 354281075Sdimwhen you run the test suite (using "make test"). The message returned is 355281075Sdim"bc: 1 not implemented". 356281075Sdim 357281075SdimThe best way to deal with this is to find another implementation of bc 358281075Sdimand compile/install it. GNU bc (see http://www.gnu.org/software/software.html 359281075Sdimfor download instructions) can be safely used, for example. 360281075Sdim 361281075Sdim 362281075Sdim* Why does the OpenSSL compilation fail on Alpha True64 Unix? 363281075Sdim 364281075SdimOn some Alpha installations running True64 Unix and Compaq C, the compilation 365281075Sdimof crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual 366281075Sdimmemory to continue compilation.' As far as the tests have shown, this may be 367281075Sdima compiler bug. What happens is that it eats up a lot of resident memory 368281075Sdimto build something, probably a table. The problem is clearly in the 369281075Sdimoptimization code, because if one eliminates optimization completely (-O0), 370281075Sdimthe compilation goes through (and the compiler consumes about 2MB of resident 371281075Sdimmemory instead of 240MB or whatever one's limit is currently). 372281075Sdim 373281075SdimThere are three options to solve this problem: 374281075Sdim 375281075Sdim1. set your current data segment size soft limit higher. Experience shows 376281075Sdimthat about 241000 kbytes seems to be enough on an AlphaServer DS10. You do 377281075Sdimthis with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of 378281075Sdimkbytes to set the limit to. 379281075Sdim 380281075Sdim2. If you have a hard limit that is lower than what you need and you can't 381281075Sdimget it changed, you can compile all of OpenSSL with -O0 as optimization 382281075Sdimlevel. This is however not a very nice thing to do for those who expect to 383281075Sdimget the best result from OpenSSL. A bit more complicated solution is the 384281075Sdimfollowing: 385281075Sdim 386281075Sdim----- snip:start ----- 387281075Sdim make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ 388281075Sdim sed -e 's/ -O[0-9] / -O0 /'`" 389281075Sdim rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` 390281075Sdim make 391281075Sdim----- snip:end ----- 392281075Sdim 393281075SdimThis will only compile sha_dgst.c with -O0, the rest with the optimization 394281075Sdimlevel chosen by the configuration process. When the above is done, do the 395281075Sdimtest and installation and you're set. 396281075Sdim 397281075Sdim 398281075Sdim* Why does the OpenSSL compilation fail with "ar: command not found"? 399281075Sdim 400281075SdimGetting this message is quite usual on Solaris 2, because Sun has hidden 401281075Sdimaway 'ar' and other development commands in directories that aren't in 402281075Sdim$PATH by default. One of those directories is '/usr/ccs/bin'. The 403281075Sdimquickest way to fix this is to do the following (it assumes you use sh 404281075Sdimor any sh-compatible shell): 405281075Sdim 406281075Sdim----- snip:start ----- 407281075Sdim PATH=${PATH}:/usr/ccs/bin; export PATH 408281075Sdim----- snip:end ----- 409281075Sdim 410281075Sdimand then redo the compilation. What you should really do is make sure 411281075Sdim'/usr/ccs/bin' is permanently in your $PATH, for example through your 412281075Sdim'.profile' (again, assuming you use a sh-compatible shell). 413281075Sdim 414281075Sdim 415281075Sdim* Why does the OpenSSL compilation fail on Win32 with VC++? 416281075Sdim 417281075SdimSometimes, you may get reports from VC++ command line (cl) that it 418281075Sdimcan't find standard include files like stdio.h and other weirdnesses. 419281075SdimOne possible cause is that the environment isn't correctly set up. 420281075SdimTo solve that problem, one should run VCVARS32.BAT which is found in 421281075Sdimthe 'bin' subdirectory of the VC++ installation directory (somewhere 422281075Sdimunder 'Program Files'). This needs to be done prior to running NMAKE, 423281075Sdimand the changes are only valid for the current DOS session. 424281075Sdim 425281075Sdim 426281075Sdim[PROG] ======================================================================== 427281075Sdim 428281075Sdim* Is OpenSSL thread-safe? 429281075Sdim 430281075SdimYes (with limitations: an SSL connection may not concurrently be used 431281075Sdimby multiple threads). On Windows and many Unix systems, OpenSSL 432281075Sdimautomatically uses the multi-threaded versions of the standard 433281075Sdimlibraries. If your platform is not one of these, consult the INSTALL 434281075Sdimfile. 435281075Sdim 436281075SdimMulti-threaded applications must provide two callback functions to 437281075SdimOpenSSL. This is described in the threads(3) manpage. 438281075Sdim 439281075Sdim 440281075Sdim* I've compiled a program under Windows and it crashes: why? 441281075Sdim 442281075SdimThis is usually because you've missed the comment in INSTALL.W32. You 443281075Sdimmust link with the multithreaded DLL version of the VC++ runtime library 444281075Sdimotherwise the conflict will cause a program to crash: typically on the 445281075Sdimfirst BIO related read or write operation. 446281075Sdim 447281075Sdim 448281075Sdim* How do I read or write a DER encoded buffer using the ASN1 functions? 449281075Sdim 450281075SdimYou have two options. You can either use a memory BIO in conjunction 451281075Sdimwith the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the 452281075Sdimi2d_XXX(), d2i_XXX() functions directly. Since these are often the 453281075Sdimcause of grief here are some code fragments using PKCS7 as an example: 454281075Sdim 455281075Sdimunsigned char *buf, *p; 456281075Sdimint len; 457281075Sdim 458281075Sdimlen = i2d_PKCS7(p7, NULL); 459281075Sdimbuf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ 460281075Sdimp = buf; 461281075Sdimi2d_PKCS7(p7, &p); 462281075Sdim 463281075SdimAt this point buf contains the len bytes of the DER encoding of 464281075Sdimp7. 465281075Sdim 466281075SdimThe opposite assumes we already have len bytes in buf: 467281075Sdim 468281075Sdimunsigned char *p; 469281075Sdimp = buf; 470281075Sdimp7 = d2i_PKCS7(NULL, &p, len); 471281075Sdim 472281075SdimAt this point p7 contains a valid PKCS7 structure of NULL if an error 473281075Sdimoccurred. If an error occurred ERR_print_errors(bio) should give more 474281075Sdiminformation. 475281075Sdim 476281075SdimThe reason for the temporary variable 'p' is that the ASN1 functions 477281075Sdimincrement the passed pointer so it is ready to read or write the next 478281075Sdimstructure. This is often a cause of problems: without the temporary 479281075Sdimvariable the buffer pointer is changed to point just after the data 480281075Sdimthat has been read or written. This may well be uninitialized data 481281075Sdimand attempts to free the buffer will have unpredictable results 482281075Sdimbecause it no longer points to the same address. 483281075Sdim 484281075Sdim 485281075Sdim* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? 486281075Sdim 487281075SdimThis usually happens when you try compiling something using the PKCS#12 488281075Sdimmacros with a C++ compiler. There is hardly ever any need to use the 489281075SdimPKCS#12 macros in a program, it is much easier to parse and create 490281075SdimPKCS#12 files using the PKCS12_parse() and PKCS12_create() functions 491281075Sdimdocumented in doc/openssl.txt and with examples in demos/pkcs12. The 492281075Sdim'pkcs12' application has to use the macros because it prints out 493281075Sdimdebugging information. 494281075Sdim 495281075Sdim 496281075Sdim* I've called <some function> and it fails, why? 497281075Sdim 498281075SdimBefore submitting a report or asking in one of the mailing lists, you 499281075Sdimshould try to determine the cause. In particular, you should call 500281075SdimERR_print_errors() or ERR_print_errors_fp() after the failed call 501281075Sdimand see if the message helps. Note that the problem may occur earlier 502281075Sdimthan you think -- you should check for errors after every call where 503281075Sdimit is possible, otherwise the actual problem may be hidden because 504281075Sdimsome OpenSSL functions clear the error state. 505281075Sdim 506281075Sdim 507281075Sdim* I just get a load of numbers for the error output, what do they mean? 508281075Sdim 509281075SdimThe actual format is described in the ERR_print_errors() manual page. 510281075SdimYou should call the function ERR_load_crypto_strings() before hand and 511281075Sdimthe message will be output in text form. If you can't do this (for example 512281075Sdimit is a pre-compiled binary) you can use the errstr utility on the error 513281075Sdimcode itself (the hex digits after the second colon). 514281075Sdim 515281075Sdim 516281075Sdim* Why do I get errors about unknown algorithms? 517281075Sdim 518281075SdimThis can happen under several circumstances such as reading in an 519281075Sdimencrypted private key or attempting to decrypt a PKCS#12 file. The cause 520281075Sdimis forgetting to load OpenSSL's table of algorithms with 521281075SdimOpenSSL_add_all_algorithms(). See the manual page for more information. 522281075Sdim 523281075Sdim 524281075Sdim* Why can't the OpenSSH configure script detect OpenSSL? 525281075Sdim 526281075SdimThere is a problem with OpenSSH 1.2.2p1, in that the configure script 527281075Sdimcan't find the installed OpenSSL libraries. The problem is actually 528281075Sdima small glitch that is easily solved with the following patch to be 529281075Sdimapplied to the OpenSSH distribution: 530281075Sdim 531281075Sdim----- snip:start ----- 532281075Sdim--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000 533281075Sdim+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000 534281075Sdim@@ -152,10 +152,10 @@ 535281075Sdim AC_MSG_CHECKING([for OpenSSL/SSLeay directory]) 536281075Sdim for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do 537281075Sdim if test ! -z "$ssldir" ; then 538281075Sdim- LIBS="$saved_LIBS -L$ssldir" 539281075Sdim+ LIBS="$saved_LIBS -L$ssldir/lib" 540281075Sdim CFLAGS="$CFLAGS -I$ssldir/include" 541281075Sdim if test "x$need_dash_r" = "x1" ; then 542281075Sdim- LIBS="$LIBS -R$ssldir" 543281075Sdim+ LIBS="$LIBS -R$ssldir/lib" 544281075Sdim fi 545281075Sdim fi 546281075Sdim LIBS="$LIBS -lcrypto" 547281075Sdim--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000 548281075Sdim+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000 549281075Sdim@@ -1890,10 +1890,10 @@ 550281075Sdim echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5 551281075Sdim for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do 552281075Sdim if test ! -z "$ssldir" ; then 553281075Sdim- LIBS="$saved_LIBS -L$ssldir" 554281075Sdim+ LIBS="$saved_LIBS -L$ssldir/lib" 555281075Sdim CFLAGS="$CFLAGS -I$ssldir/include" 556281075Sdim if test "x$need_dash_r" = "x1" ; then 557281075Sdim- LIBS="$LIBS -R$ssldir" 558281075Sdim+ LIBS="$LIBS -R$ssldir/lib" 559281075Sdim fi 560281075Sdim fi 561281075Sdim LIBS="$LIBS -lcrypto" 562281075Sdim----- snip:end ----- 563281075Sdim 564281075Sdim 565281075Sdim* Can I use OpenSSL's SSL library with non-blocking I/O? 566281075Sdim 567281075SdimYes; make sure to read the SSL_get_error(3) manual page! 568281075Sdim 569281075SdimA pitfall to avoid: Don't assume that SSL_read() will just read from 570281075Sdimthe underlying transport or that SSL_write() will just write to it -- 571281075Sdimit is also possible that SSL_write() cannot do any useful work until 572281075Sdimthere is data to read, or that SSL_read() cannot do anything until it 573281075Sdimis possible to send data. One reason for this is that the peer may 574281075Sdimrequest a new TLS/SSL handshake at any time during the protocol, 575281075Sdimrequiring a bi-directional message exchange; both SSL_read() and 576281075SdimSSL_write() will try to continue any pending handshake. 577281075Sdim 578281075Sdim 579281075Sdim* Why doesn't my server application receive a client certificate? 580281075Sdim 581281075SdimDue to the TLS protocol definition, a client will only send a certificate, 582281075Sdimif explicitely asked by the server. Use the SSL_VERIFY_PEER flag of the 583281075SdimSSL_CTX_set_verify() function to enable the use of client certificates. 584281075Sdim 585281075Sdim 586281075Sdim=============================================================================== 587281075Sdim 588281075Sdim