For a long time, I've wanted to be able to easily run one or a few
[oweals/openssl.git] / FAQ
1 OpenSSL  -  Frequently Asked Questions
2 --------------------------------------
3
4 * Which is the current version of OpenSSL?
5 * Where is the documentation?
6 * How can I contact the OpenSSL developers?
7 * Do I need patent licenses to use OpenSSL?
8 * Is OpenSSL thread-safe?
9 * Why do I get a "PRNG not seeded" error message?
10 * Why does the linker complain about undefined symbols?
11 * Where can I get a compiled version of OpenSSL?
12 * I've compiled a program under Windows and it crashes: why?
13 * How do I read or write a DER encoded buffer using the ASN1 functions?
14 * I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
15 * I've called <some function> and it fails, why?
16 * I just get a load of numbers for the error output, what do they mean?
17 * Why do I get errors about unknown algorithms?
18 * How do I create certificates or certificate requests?
19 * Why can't I create certificate requests?
20 * Why does <SSL program> fail with a certificate verify error?
21 * Why can I only use weak ciphers when I connect to a server using OpenSSL?
22 * How can I create DSA certificates?
23 * Why can't I make an SSL connection using a DSA certificate?
24 * How can I remove the passphrase on a private key?
25 * Why can't the OpenSSH configure script detect OpenSSL?
26 * Why does the OpenSSL test fail with "bc: command not found"?
27 * Why does the OpenSSL test fail with "bc: 1 no implemented"?
28 * Why does the OpenSSL compilation fail on Alpha True64 Unix?
29 * Why does the OpenSSL compilation fail with "ar: command not found"?
30 * Why does the OpenSSL compilation fail on Win32 with VC++?
31 * Why aren't tools like 'autoconf' and 'libtool' used?
32
33
34 * Which is the current version of OpenSSL?
35
36 The current version is available from <URL: http://www.openssl.org>.
37 OpenSSL 0.9.6 was released on September 24th, 2000.
38
39 In addition to the current stable release, you can also access daily
40 snapshots of the OpenSSL development version at <URL:
41 ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access.
42
43
44 * Where is the documentation?
45
46 OpenSSL is a library that provides cryptographic functionality to
47 applications such as secure web servers.  Be sure to read the
48 documentation of the application you want to use.  The INSTALL file
49 explains how to install this library.
50
51 OpenSSL includes a command line utility that can be used to perform a
52 variety of cryptographic functions.  It is described in the openssl(1)
53 manpage.  Documentation for developers is currently being written.  A
54 few manual pages already are available; overviews over libcrypto and
55 libssl are given in the crypto(3) and ssl(3) manpages.
56
57 The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a
58 different directory if you specified one as described in INSTALL).
59 In addition, you can read the most current versions at
60 <URL: http://www.openssl.org/docs/>.
61
62 For information on parts of libcrypto that are not yet documented, you
63 might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's
64 predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>.  Much
65 of this still applies to OpenSSL.
66
67 There is some documentation about certificate extensions and PKCS#12
68 in doc/openssl.txt
69
70 The original SSLeay documentation is included in OpenSSL as
71 doc/ssleay.txt.  It may be useful when none of the other resources
72 help, but please note that it reflects the obsolete version SSLeay
73 0.6.6.
74
75
76 * How can I contact the OpenSSL developers?
77
78 The README file describes how to submit bug reports and patches to
79 OpenSSL.  Information on the OpenSSL mailing lists is available from
80 <URL: http://www.openssl.org>.
81
82
83 * Do I need patent licenses to use OpenSSL?
84
85 The patents section of the README file lists patents that may apply to
86 you if you want to use OpenSSL.  For information on intellectual
87 property rights, please consult a lawyer.  The OpenSSL team does not
88 offer legal advice.
89
90 You can configure OpenSSL so as not to use RC5 and IDEA by using
91  ./config no-rc5 no-idea
92
93
94 * Is OpenSSL thread-safe?
95
96 Yes (with limitations: an SSL connection may not concurrently be used
97 by multiple threads).  On Windows and many Unix systems, OpenSSL
98 automatically uses the multi-threaded versions of the standard
99 libraries.  If your platform is not one of these, consult the INSTALL
100 file.
101
102 Multi-threaded applications must provide two callback functions to
103 OpenSSL.  This is described in the threads(3) manpage.
104
105
106 * Why do I get a "PRNG not seeded" error message?
107
108 Cryptographic software needs a source of unpredictable data to work
109 correctly.  Many open source operating systems provide a "randomness
110 device" that serves this purpose.  On other systems, applications have
111 to call the RAND_add() or RAND_seed() function with appropriate data
112 before generating keys or performing public key encryption.
113
114 Some broken applications do not do this.  As of version 0.9.5, the
115 OpenSSL functions that need randomness report an error if the random
116 number generator has not been seeded with at least 128 bits of
117 randomness.  If this error occurs, please contact the author of the
118 application you are using.  It is likely that it never worked
119 correctly.  OpenSSL 0.9.5 and later make the error visible by refusing
120 to perform potentially insecure encryption.
121
122 On systems without /dev/urandom, it is a good idea to use the Entropy
123 Gathering Demon; see the RAND_egd() manpage for details.
124
125 Most components of the openssl command line tool try to use the
126 file $HOME/.rnd (or $RANDFILE, if this environment variable is set)
127 for seeding the PRNG.  If this file does not exist or is too short,
128 the "PRNG not seeded" error message may occur.
129
130 [Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version
131 0.9.5 does not do this and will fail on systems without /dev/urandom
132 when trying to password-encrypt an RSA key!  This is a bug in the
133 library; try a later version instead.]
134
135 For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested
136 installing the SUNski package from Sun patch 105710-01 (Sparc) which
137 adds a /dev/random device and make sure it gets used, usually through
138 $RANDFILE.  There are probably similar patches for the other Solaris
139 versions.  However, be warned that /dev/random is usually a blocking
140 device, which may have some effects on OpenSSL.
141
142
143 * Why does the linker complain about undefined symbols?
144
145 Maybe the compilation was interrupted, and make doesn't notice that
146 something is missing.  Run "make clean; make".
147
148 If you used ./Configure instead of ./config, make sure that you
149 selected the right target.  File formats may differ slightly between
150 OS versions (for example sparcv8/sparcv9, or a.out/elf).
151
152 In case you get errors about the following symbols, use the config
153 option "no-asm", as described in INSTALL:
154
155  BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt,
156  CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt,
157  RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words,
158  bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4,
159  bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3,
160  des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3,
161  des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order
162
163 If none of these helps, you may want to try using the current snapshot.
164 If the problem persists, please submit a bug report.
165
166
167 * Where can I get a compiled version of OpenSSL?
168
169 Some applications that use OpenSSL are distributed in binary form.
170 When using such an application, you don't need to install OpenSSL
171 yourself; the application will include the required parts (e.g. DLLs).
172
173 If you want to install OpenSSL on a Windows system and you don't have
174 a C compiler, read the "Mingw32" section of INSTALL.W32 for information
175 on how to obtain and install the free GNU C compiler.
176
177 A number of Linux and *BSD distributions include OpenSSL.
178
179
180 * I've compiled a program under Windows and it crashes: why?
181
182 This is usually because you've missed the comment in INSTALL.W32. You
183 must link with the multithreaded DLL version of the VC++ runtime library
184 otherwise the conflict will cause a program to crash: typically on the
185 first BIO related read or write operation.
186
187
188 * How do I read or write a DER encoded buffer using the ASN1 functions?
189
190 You have two options. You can either use a memory BIO in conjunction
191 with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the
192 i2d_XXX(), d2i_XXX() functions directly. Since these are often the
193 cause of grief here are some code fragments using PKCS7 as an example:
194
195 unsigned char *buf, *p;
196 int len;
197
198 len = i2d_PKCS7(p7, NULL);
199 buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
200 p = buf;
201 i2d_PKCS7(p7, &p);
202
203 At this point buf contains the len bytes of the DER encoding of
204 p7.
205
206 The opposite assumes we already have len bytes in buf:
207
208 unsigned char *p;
209 p = buf;
210 p7 = d2i_PKCS7(NULL, &p, len);
211
212 At this point p7 contains a valid PKCS7 structure of NULL if an error
213 occurred. If an error occurred ERR_print_errors(bio) should give more
214 information.
215
216 The reason for the temporary variable 'p' is that the ASN1 functions
217 increment the passed pointer so it is ready to read or write the next
218 structure. This is often a cause of problems: without the temporary
219 variable the buffer pointer is changed to point just after the data
220 that has been read or written. This may well be uninitialized data
221 and attempts to free the buffer will have unpredictable results
222 because it no longer points to the same address.
223
224
225 * I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
226
227 This usually happens when you try compiling something using the PKCS#12
228 macros with a C++ compiler. There is hardly ever any need to use the
229 PKCS#12 macros in a program, it is much easier to parse and create
230 PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions
231 documented in doc/openssl.txt and with examples in demos/pkcs12. The
232 'pkcs12' application has to use the macros because it prints out 
233 debugging information.
234
235
236 * I've called <some function> and it fails, why?
237
238 Before submitting a report or asking in one of the mailing lists, you
239 should try to determine the cause. In particular, you should call
240 ERR_print_errors() or ERR_print_errors_fp() after the failed call
241 and see if the message helps. Note that the problem may occur earlier
242 than you think -- you should check for errors after every call where
243 it is possible, otherwise the actual problem may be hidden because
244 some OpenSSL functions clear the error state.
245
246
247 * I just get a load of numbers for the error output, what do they mean?
248
249 The actual format is described in the ERR_print_errors() manual page.
250 You should call the function ERR_load_crypto_strings() before hand and
251 the message will be output in text form. If you can't do this (for example
252 it is a pre-compiled binary) you can use the errstr utility on the error
253 code itself (the hex digits after the second colon).
254
255
256 * Why do I get errors about unknown algorithms?
257
258 This can happen under several circumstances such as reading in an
259 encrypted private key or attempting to decrypt a PKCS#12 file. The cause
260 is forgetting to load OpenSSL's table of algorithms with
261 OpenSSL_add_all_algorithms(). See the manual page for more information.
262
263
264 * How do I create certificates or certificate requests?
265
266 Check out the CA.pl(1) manual page. This provides a simple wrapper round
267 the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
268 out the manual pages for the individual utilities and the certificate
269 extensions documentation (currently in doc/openssl.txt).
270
271
272 * Why can't I create certificate requests?
273
274 You typically get the error:
275
276         unable to find 'distinguished_name' in config
277         problems making Certificate Request
278
279 This is because it can't find the configuration file. Check out the
280 DIAGNOSTICS section of req(1) for more information.
281
282
283 * Why does <SSL program> fail with a certificate verify error?
284
285 This problem is usually indicated by log messages saying something like
286 "unable to get local issuer certificate" or "self signed certificate".
287 When a certificate is verified its root CA must be "trusted" by OpenSSL
288 this typically means that the CA certificate must be placed in a directory
289 or file and the relevant program configured to read it. The OpenSSL program
290 'verify' behaves in a similar way and issues similar error messages: check
291 the verify(1) program manual page for more information.
292
293
294 * Why can I only use weak ciphers when I connect to a server using OpenSSL?
295
296 This is almost certainly because you are using an old "export grade" browser
297 which only supports weak encryption. Upgrade your browser to support 128 bit
298 ciphers.
299
300
301 * How can I create DSA certificates?
302
303 Check the CA.pl(1) manual page for a DSA certificate example.
304
305
306 * Why can't I make an SSL connection to a server using a DSA certificate?
307
308 Typically you'll see a message saying there are no shared ciphers when
309 the same setup works fine with an RSA certificate. There are two possible
310 causes. The client may not support connections to DSA servers most web
311 browsers (including Netscape and MSIE) only support connections to servers
312 supporting RSA cipher suites. The other cause is that a set of DH parameters
313 has not been supplied to the server. DH parameters can be created with the
314 dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example:
315 check the source to s_server in apps/s_server.c for an example.
316
317
318 * How can I remove the passphrase on a private key?
319
320 Firstly you should be really *really* sure you want to do this. Leaving
321 a private key unencrypted is a major security risk. If you decide that
322 you do have to do this check the EXAMPLES sections of the rsa(1) and
323 dsa(1) manual pages.
324
325
326 * Why can't the OpenSSH configure script detect OpenSSL?
327
328 There is a problem with OpenSSH 1.2.2p1, in that the configure script
329 can't find the installed OpenSSL libraries.  The problem is actually
330 a small glitch that is easily solved with the following patch to be
331 applied to the OpenSSH distribution:
332
333 ----- snip:start -----
334 --- openssh-1.2.2p1/configure.in.orig   Thu Mar 23 18:56:58 2000
335 +++ openssh-1.2.2p1/configure.in        Thu Mar 23 18:55:05 2000
336 @@ -152,10 +152,10 @@
337  AC_MSG_CHECKING([for OpenSSL/SSLeay directory])
338  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
339         if test ! -z "$ssldir" ; then
340 -               LIBS="$saved_LIBS -L$ssldir"
341 +               LIBS="$saved_LIBS -L$ssldir/lib"
342                 CFLAGS="$CFLAGS -I$ssldir/include"
343                 if test "x$need_dash_r" = "x1" ; then
344 -                       LIBS="$LIBS -R$ssldir"
345 +                       LIBS="$LIBS -R$ssldir/lib"
346                 fi
347         fi
348         LIBS="$LIBS -lcrypto"
349 --- openssh-1.2.2p1/configure.orig      Thu Mar 23 18:55:02 2000
350 +++ openssh-1.2.2p1/configure   Thu Mar 23 18:57:08 2000
351 @@ -1890,10 +1890,10 @@
352  echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5
353  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
354         if test ! -z "$ssldir" ; then
355 -               LIBS="$saved_LIBS -L$ssldir"
356 +               LIBS="$saved_LIBS -L$ssldir/lib"
357                 CFLAGS="$CFLAGS -I$ssldir/include"
358                 if test "x$need_dash_r" = "x1" ; then
359 -                       LIBS="$LIBS -R$ssldir"
360 +                       LIBS="$LIBS -R$ssldir/lib"
361                 fi
362         fi
363         LIBS="$LIBS -lcrypto"
364 ----- snip:end -----
365
366
367 * Why does the OpenSSL test fail with "bc: command not found"?
368
369 You didn't install "bc", the Unix calculator.  If you want to run the
370 tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor.
371
372
373 * Why does the OpenSSL test fail with "bc: 1 no implemented"?
374
375 On some SCO installations or versions, bc has a bug that gets triggered when
376 you run the test suite (using "make test").  The message returned is "bc:
377 1 not implemented".  The best way to deal with this is to find another
378 implementation of bc and compile/install it.  For example, GNU bc (see
379 http://www.gnu.org/software/software.html for download instructions) can
380 be safely used.
381
382
383 * Why does the OpenSSL compilation fail on Alpha True64 Unix?
384
385 On some Alpha installations running True64 Unix and Compaq C, the compilation
386 of crypto/sha/sha_dgst.c fails with the message 'Fatal:  Insufficient virtual
387 memory to continue compilation.'  As far as the tests have shown, this may be
388 a compiler bug.  What happens is that it eats up a lot of resident memory
389 to build something, probably a table.  The problem is clearly in the
390 optimization code, because if one eliminates optimization completely (-O0),
391 the compilation goes through (and the compiler consumes about 2MB of resident
392 memory instead of 240MB or whatever one's limit is currently).
393
394 There are three options to solve this problem:
395
396 1. set your current data segment size soft limit higher.  Experience shows
397 that about 241000 kbytes seems to be enough on an AlphaServer DS10.  You do
398 this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
399 kbytes to set the limit to.
400
401 2. If you have a hard limit that is lower than what you need and you can't
402 get it changed, you can compile all of OpenSSL with -O0 as optimization
403 level.  This is however not a very nice thing to do for those who expect to
404 get the best result from OpenSSL.  A bit more complicated solution is the
405 following:
406
407 ----- snip:start -----
408   make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
409        sed -e 's/ -O[0-9] / -O0 /'`"
410   rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'`
411   make
412 ----- snip:end -----
413
414 This will only compile sha_dgst.c with -O0, the rest with the optimization
415 level chosen by the configuration process.  When the above is done, do the
416 test and installation and you're set.
417
418
419 * Why does the OpenSSL compilation fail with "ar: command not found"?
420
421 Getting this message is quite usual on Solaris 2, because Sun has hidden
422 away 'ar' and other development commands in directories that aren't in
423 $PATH by default.  One of those directories is '/usr/ccs/bin'.  The
424 quickest way to fix this is to do the following (it assumes you use sh
425 or any sh-compatible shell):
426
427 ----- snip:start -----
428   PATH=${PATH}:/usr/ccs/bin; export PATH
429 ----- snip:end -----
430
431 and then redo the compilation.  What you should really do is make sure
432 '/usr/ccs/bin' is permanently in your $PATH, for example through your
433 '.profile' (again, assuming you use a sh-compatible shell).
434
435
436 * Why does the OpenSSL compilation fail on Win32 with VC++?
437
438 Sometimes, you may get reports from VC++ command line (cl) that it
439 can't find standard include files like stdio.h and other weirdnesses.
440 One possible cause is that the environment isn't correctly set up.
441 To solve that problem, one should run VCVARS32.BAT which is found in
442 the 'bin' subdirectory of the VC++ installation directory (somewhere
443 under 'Program Files').  This needs to be done prior to running NMAKE,
444 and the changes are only valid for the current DOS session.
445
446
447 * Why aren't tools like 'autoconf' and 'libtool' used?
448
449 autoconf is a nice tool, but is unfortunately very Unix-centric.
450 Although one can come up with solution to have ports keep in track,
451 there's also some work needed for that, and can be quite painful at
452 times.  If there was a 'autoconf'-like tool that generated perl
453 scripts or something similarly general, it would probably be used
454 in OpenSSL much earlier.
455
456 libtool has repeatadly been reported by some members of the OpenSSL
457 development and others to be a pain to use.  So far, those in the
458 development team who have said anything about this have expressed
459 a wish to avoid libtool for that reason.
460