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