]>
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? | |
9c11a0e5 | 11 | * What is an 'engine' version? |
d4e573f3 | 12 | * How do I check the authenticity of the OpenSSL distribution? |
0ae485dc RL |
13 | |
14 | [LEGAL] Legal questions | |
15 | ||
c1ce32f1 | 16 | * Do I need patent licenses to use OpenSSL? |
17e75747 | 17 | * Can I use OpenSSL with GPL software? |
0ae485dc RL |
18 | |
19 | [USER] Questions on using the OpenSSL applications | |
20 | ||
f9a7c34f | 21 | * Why do I get a "PRNG not seeded" error message? |
24cc290b | 22 | * Why do I get an "unable to write 'random state'" error message? |
46e80a30 DSH |
23 | * How do I create certificates or certificate requests? |
24 | * Why can't I create certificate requests? | |
afee764c | 25 | * Why does <SSL program> fail with a certificate verify error? |
a331a305 | 26 | * Why can I only use weak ciphers when I connect to a server using OpenSSL? |
afee764c DSH |
27 | * How can I create DSA certificates? |
28 | * Why can't I make an SSL connection using a DSA certificate? | |
a331a305 | 29 | * How can I remove the passphrase on a private key? |
1a7b2d33 | 30 | * Why can't I use OpenSSL certificates with SSL client authentication? |
7522254b | 31 | * Why does my browser give a warning about a mismatched hostname? |
0b33bc6b | 32 | * How do I install a CA certificate into a browser? |
17e2c77a | 33 | * Why is OpenSSL x509 DN output not conformant to RFC2253? |
0ae485dc RL |
34 | |
35 | [BUILD] Questions about building and testing OpenSSL | |
36 | ||
37 | * Why does the linker complain about undefined symbols? | |
c32364f5 | 38 | * Why does the OpenSSL test fail with "bc: command not found"? |
a6ed5dd6 | 39 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
f742e497 | 40 | * Why does the OpenSSL test fail with "bc: stack empty"? |
6bc847e4 | 41 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
b364e5d2 | 42 | * Why does the OpenSSL compilation fail with "ar: command not found"? |
bf55ece1 | 43 | * Why does the OpenSSL compilation fail on Win32 with VC++? |
c4da6dd3 | 44 | * What is special about OpenSSL on Redhat? |
311e2099 RL |
45 | * Why does the OpenSSL compilation fail on MacOS X? |
46 | * Why does the OpenSSL test suite fail on MacOS X? | |
26a60b2e | 47 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
75c40285 | 48 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
f9a7c34f | 49 | |
0ae485dc RL |
50 | [PROG] Questions about programming with OpenSSL |
51 | ||
52 | * Is OpenSSL thread-safe? | |
53 | * I've compiled a program under Windows and it crashes: why? | |
54 | * How do I read or write a DER encoded buffer using the ASN1 functions? | |
55 | * I've tried using <M_some_evil_pkcs12_macro> and I get errors why? | |
56 | * I've called <some function> and it fails, why? | |
57 | * I just get a load of numbers for the error output, what do they mean? | |
58 | * Why do I get errors about unknown algorithms? | |
59 | * Why can't the OpenSSH configure script detect OpenSSL? | |
60 | * Can I use OpenSSL's SSL library with non-blocking I/O? | |
19732245 | 61 | * Why doesn't my server application receive a client certificate? |
e1f7ea25 | 62 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
0ae485dc RL |
63 | |
64 | =============================================================================== | |
65 | ||
66 | [MISC] ======================================================================== | |
f9a7c34f | 67 | |
49976df5 UM |
68 | * Which is the current version of OpenSSL? |
69 | ||
70 | The current version is available from <URL: http://www.openssl.org>. | |
08101d72 | 71 | OpenSSL 0.9.7 was released on December 31, 2002. |
49976df5 UM |
72 | |
73 | In addition to the current stable release, you can also access daily | |
74 | snapshots of the OpenSSL development version at <URL: | |
75 | ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access. | |
76 | ||
77 | ||
f9a7c34f UM |
78 | * Where is the documentation? |
79 | ||
80 | OpenSSL is a library that provides cryptographic functionality to | |
81 | applications such as secure web servers. Be sure to read the | |
82 | documentation of the application you want to use. The INSTALL file | |
83 | explains how to install this library. | |
84 | ||
85 | OpenSSL includes a command line utility that can be used to perform a | |
86 | variety of cryptographic functions. It is described in the openssl(1) | |
87 | manpage. Documentation for developers is currently being written. A | |
88 | few manual pages already are available; overviews over libcrypto and | |
89 | libssl are given in the crypto(3) and ssl(3) manpages. | |
90 | ||
91 | The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a | |
92 | different directory if you specified one as described in INSTALL). | |
93 | In addition, you can read the most current versions at | |
94 | <URL: http://www.openssl.org/docs/>. | |
95 | ||
96 | For information on parts of libcrypto that are not yet documented, you | |
97 | might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's | |
98 | predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much | |
99 | of this still applies to OpenSSL. | |
100 | ||
fbb41ae0 DSH |
101 | There is some documentation about certificate extensions and PKCS#12 |
102 | in doc/openssl.txt | |
103 | ||
f9a7c34f | 104 | The original SSLeay documentation is included in OpenSSL as |
cacbb51e | 105 | doc/ssleay.txt. It may be useful when none of the other resources |
f9a7c34f UM |
106 | help, but please note that it reflects the obsolete version SSLeay |
107 | 0.6.6. | |
108 | ||
109 | ||
110 | * How can I contact the OpenSSL developers? | |
111 | ||
112 | The README file describes how to submit bug reports and patches to | |
113 | OpenSSL. Information on the OpenSSL mailing lists is available from | |
114 | <URL: http://www.openssl.org>. | |
115 | ||
116 | ||
0ae485dc | 117 | * Where can I get a compiled version of OpenSSL? |
f9a7c34f | 118 | |
0ae485dc RL |
119 | Some applications that use OpenSSL are distributed in binary form. |
120 | When using such an application, you don't need to install OpenSSL | |
121 | yourself; the application will include the required parts (e.g. DLLs). | |
f9a7c34f | 122 | |
0ae485dc RL |
123 | If you want to install OpenSSL on a Windows system and you don't have |
124 | a C compiler, read the "Mingw32" section of INSTALL.W32 for information | |
125 | on how to obtain and install the free GNU C compiler. | |
f9a7c34f | 126 | |
0ae485dc | 127 | A number of Linux and *BSD distributions include OpenSSL. |
f9a7c34f | 128 | |
f9a7c34f | 129 | |
0ae485dc | 130 | * Why aren't tools like 'autoconf' and 'libtool' used? |
f9a7c34f | 131 | |
ba93fd6a UM |
132 | autoconf will probably be used in future OpenSSL versions. If it was |
133 | less Unix-centric, it might have been used much earlier. | |
f9a7c34f | 134 | |
a0256f46 | 135 | * What is an 'engine' version? |
679df234 LJ |
136 | |
137 | With version 0.9.6 OpenSSL was extended to interface to external crypto | |
138 | hardware. This was realized in a special release '0.9.6-engine'. With | |
a0256f46 LJ |
139 | version 0.9.7 (not yet released) the changes were merged into the main |
140 | development line, so that the special release is no longer necessary. | |
b1d6e3f5 | 141 | |
d4e573f3 RL |
142 | * How do I check the authenticity of the OpenSSL distribution? |
143 | ||
144 | We provide MD5 digests and ASC signatures of each tarball. | |
145 | Use MD5 to check that a tarball from a mirror site is identical: | |
146 | ||
147 | md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 | |
148 | ||
149 | You can check authenticity using pgp or gpg. You need the OpenSSL team | |
150 | member public key used to sign it (download it from a key server). Then | |
151 | just do: | |
152 | ||
153 | pgp TARBALL.asc | |
154 | ||
0ae485dc | 155 | [LEGAL] ======================================================================= |
b1d6e3f5 | 156 | |
0ae485dc | 157 | * Do I need patent licenses to use OpenSSL? |
b1d6e3f5 | 158 | |
0ae485dc RL |
159 | The patents section of the README file lists patents that may apply to |
160 | you if you want to use OpenSSL. For information on intellectual | |
161 | property rights, please consult a lawyer. The OpenSSL team does not | |
162 | offer legal advice. | |
163 | ||
164 | You can configure OpenSSL so as not to use RC5 and IDEA by using | |
165 | ./config no-rc5 no-idea | |
166 | ||
167 | ||
17e75747 UM |
168 | * Can I use OpenSSL with GPL software? |
169 | ||
170 | On many systems including the major Linux and BSD distributions, yes (the | |
171 | GPL does not place restrictions on using libraries that are part of the | |
172 | normal operating system distribution). | |
173 | ||
174 | On other systems, the situation is less clear. Some GPL software copyright | |
175 | holders claim that you infringe on their rights if you use OpenSSL with | |
176 | their software on operating systems that don't normally include OpenSSL. | |
177 | ||
178 | If you develop open source software that uses OpenSSL, you may find it | |
e3fefbfd | 179 | useful to choose an other license than the GPL, or state explicitly that |
17e75747 UM |
180 | "This program is released under the GPL with the additional exemption that |
181 | compiling, linking, and/or using OpenSSL is allowed." If you are using | |
182 | GPL software developed by others, you may want to ask the copyright holder | |
183 | for permission to use their software with OpenSSL. | |
184 | ||
185 | ||
0ae485dc | 186 | [USER] ======================================================================== |
b1d6e3f5 | 187 | |
f9a7c34f UM |
188 | * Why do I get a "PRNG not seeded" error message? |
189 | ||
190 | Cryptographic software needs a source of unpredictable data to work | |
191 | correctly. Many open source operating systems provide a "randomness | |
192 | device" that serves this purpose. On other systems, applications have | |
193 | to call the RAND_add() or RAND_seed() function with appropriate data | |
194 | before generating keys or performing public key encryption. | |
24cc290b | 195 | (These functions initialize the pseudo-random number generator, PRNG.) |
f9a7c34f UM |
196 | |
197 | Some broken applications do not do this. As of version 0.9.5, the | |
198 | OpenSSL functions that need randomness report an error if the random | |
199 | number generator has not been seeded with at least 128 bits of | |
200 | randomness. If this error occurs, please contact the author of the | |
201 | application you are using. It is likely that it never worked | |
8311d323 UM |
202 | correctly. OpenSSL 0.9.5 and later make the error visible by refusing |
203 | to perform potentially insecure encryption. | |
204 | ||
d9a770e6 BM |
205 | On systems without /dev/urandom and /dev/random, it is a good idea to |
206 | use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for | |
207 | details. Starting with version 0.9.7, OpenSSL will automatically look | |
208 | for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and | |
209 | /etc/entropy. | |
2b670ea2 | 210 | |
24cc290b BM |
211 | Most components of the openssl command line utility automatically try |
212 | to seed the random number generator from a file. The name of the | |
213 | default seeding file is determined as follows: If environment variable | |
214 | RANDFILE is set, then it names the seeding file. Otherwise if | |
215 | environment variable HOME is set, then the seeding file is $HOME/.rnd. | |
216 | If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will | |
217 | use file .rnd in the current directory while OpenSSL 0.9.6a uses no | |
218 | default seeding file at all. OpenSSL 0.9.6b and later will behave | |
6af59bc0 | 219 | similarly to 0.9.6a, but will use a default of "C:\" for HOME on |
24cc290b BM |
220 | Windows systems if the environment variable has not been set. |
221 | ||
222 | If the default seeding file does not exist or is too short, the "PRNG | |
223 | not seeded" error message may occur. | |
224 | ||
225 | The openssl command line utility will write back a new state to the | |
226 | default seeding file (and create this file if necessary) unless | |
227 | there was no sufficient seeding. | |
228 | ||
35feed50 LJ |
229 | Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. |
230 | Use the "-rand" option of the OpenSSL command line tools instead. | |
231 | The $RANDFILE environment variable and $HOME/.rnd are only used by the | |
232 | OpenSSL command line tools. Applications using the OpenSSL library | |
233 | provide their own configuration options to specify the entropy source, | |
234 | please check out the documentation coming the with application. | |
8311d323 | 235 | |
9b296157 RL |
236 | For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested |
237 | installing the SUNski package from Sun patch 105710-01 (Sparc) which | |
238 | adds a /dev/random device and make sure it gets used, usually through | |
239 | $RANDFILE. There are probably similar patches for the other Solaris | |
0c4d9b2f LJ |
240 | versions. An official statement from Sun with respect to /dev/random |
241 | support can be found at | |
242 | http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski | |
243 | However, be warned that /dev/random is usually a blocking device, which | |
244 | may have some effects on OpenSSL. | |
96c930dd LJ |
245 | A third party /dev/random solution for Solaris is available at |
246 | http://www.cosy.sbg.ac.at/~andi/ | |
9b296157 | 247 | |
2b670ea2 | 248 | |
24cc290b BM |
249 | * Why do I get an "unable to write 'random state'" error message? |
250 | ||
251 | ||
252 | Sometimes the openssl command line utility does not abort with | |
253 | a "PRNG not seeded" error message, but complains that it is | |
254 | "unable to write 'random state'". This message refers to the | |
255 | default seeding file (see previous answer). A possible reason | |
256 | is that no default filename is known because neither RANDFILE | |
257 | nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the | |
258 | current directory in this case, but this has changed with 0.9.6a.) | |
259 | ||
260 | ||
0ae485dc RL |
261 | * How do I create certificates or certificate requests? |
262 | ||
263 | Check out the CA.pl(1) manual page. This provides a simple wrapper round | |
264 | the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check | |
265 | out the manual pages for the individual utilities and the certificate | |
266 | extensions documentation (currently in doc/openssl.txt). | |
267 | ||
268 | ||
269 | * Why can't I create certificate requests? | |
270 | ||
271 | You typically get the error: | |
272 | ||
273 | unable to find 'distinguished_name' in config | |
274 | problems making Certificate Request | |
275 | ||
276 | This is because it can't find the configuration file. Check out the | |
277 | DIAGNOSTICS section of req(1) for more information. | |
278 | ||
279 | ||
280 | * Why does <SSL program> fail with a certificate verify error? | |
281 | ||
282 | This problem is usually indicated by log messages saying something like | |
283 | "unable to get local issuer certificate" or "self signed certificate". | |
284 | When a certificate is verified its root CA must be "trusted" by OpenSSL | |
285 | this typically means that the CA certificate must be placed in a directory | |
286 | or file and the relevant program configured to read it. The OpenSSL program | |
287 | 'verify' behaves in a similar way and issues similar error messages: check | |
288 | the verify(1) program manual page for more information. | |
289 | ||
290 | ||
291 | * Why can I only use weak ciphers when I connect to a server using OpenSSL? | |
292 | ||
293 | This is almost certainly because you are using an old "export grade" browser | |
294 | which only supports weak encryption. Upgrade your browser to support 128 bit | |
295 | ciphers. | |
296 | ||
297 | ||
298 | * How can I create DSA certificates? | |
299 | ||
300 | Check the CA.pl(1) manual page for a DSA certificate example. | |
301 | ||
302 | ||
303 | * Why can't I make an SSL connection to a server using a DSA certificate? | |
304 | ||
305 | Typically you'll see a message saying there are no shared ciphers when | |
306 | the same setup works fine with an RSA certificate. There are two possible | |
307 | causes. The client may not support connections to DSA servers most web | |
308 | browsers (including Netscape and MSIE) only support connections to servers | |
309 | supporting RSA cipher suites. The other cause is that a set of DH parameters | |
310 | has not been supplied to the server. DH parameters can be created with the | |
311 | dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: | |
312 | check the source to s_server in apps/s_server.c for an example. | |
313 | ||
314 | ||
315 | * How can I remove the passphrase on a private key? | |
316 | ||
317 | Firstly you should be really *really* sure you want to do this. Leaving | |
318 | a private key unencrypted is a major security risk. If you decide that | |
319 | you do have to do this check the EXAMPLES sections of the rsa(1) and | |
320 | dsa(1) manual pages. | |
321 | ||
322 | ||
1a7b2d33 DSH |
323 | * Why can't I use OpenSSL certificates with SSL client authentication? |
324 | ||
325 | What will typically happen is that when a server requests authentication | |
326 | it will either not include your certificate or tell you that you have | |
327 | no client certificates (Netscape) or present you with an empty list box | |
328 | (MSIE). The reason for this is that when a server requests a client | |
329 | certificate it includes a list of CAs names which it will accept. Browsers | |
330 | will only let you select certificates from the list on the grounds that | |
331 | there is little point presenting a certificate which the server will | |
332 | reject. | |
333 | ||
334 | The solution is to add the relevant CA certificate to your servers "trusted | |
e3fefbfd | 335 | CA list". How you do this depends on the server software in uses. You can |
1a7b2d33 DSH |
336 | print out the servers list of acceptable CAs using the OpenSSL s_client tool: |
337 | ||
338 | openssl s_client -connect www.some.host:443 -prexit | |
339 | ||
959f67d6 | 340 | If your server only requests certificates on certain URLs then you may need |
1a7b2d33 DSH |
341 | to manually issue an HTTP GET command to get the list when s_client connects: |
342 | ||
343 | GET /some/page/needing/a/certificate.html | |
344 | ||
345 | If your CA does not appear in the list then this confirms the problem. | |
346 | ||
347 | ||
348 | * Why does my browser give a warning about a mismatched hostname? | |
349 | ||
350 | Browsers expect the server's hostname to match the value in the commonName | |
351 | (CN) field of the certificate. If it does not then you get a warning. | |
352 | ||
353 | ||
0b33bc6b DSH |
354 | * How do I install a CA certificate into a browser? |
355 | ||
356 | The usual way is to send the DER encoded certificate to the browser as | |
357 | MIME type application/x-x509-ca-cert, for example by clicking on an appropriate | |
358 | link. On MSIE certain extensions such as .der or .cacert may also work, or you | |
359 | can import the certificate using the certificate import wizard. | |
360 | ||
361 | You can convert a certificate to DER form using the command: | |
362 | ||
363 | openssl x509 -in ca.pem -outform DER -out ca.der | |
364 | ||
365 | Occasionally someone suggests using a command such as: | |
366 | ||
367 | openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem | |
368 | ||
369 | DO NOT DO THIS! This command will give away your CAs private key and | |
370 | reduces its security to zero: allowing anyone to forge certificates in | |
371 | whatever name they choose. | |
372 | ||
17e2c77a LJ |
373 | * Why is OpenSSL x509 DN output not conformant to RFC2253? |
374 | ||
375 | The ways to print out the oneline format of the DN (Distinguished Name) have | |
376 | been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() | |
377 | interface, the "-nameopt" option could be introduded. See the manual | |
378 | page of the "openssl x509" commandline tool for details. The old behaviour | |
379 | has however been left as default for the sake of compatibility. | |
0b33bc6b | 380 | |
0ae485dc RL |
381 | [BUILD] ======================================================================= |
382 | ||
49976df5 UM |
383 | * Why does the linker complain about undefined symbols? |
384 | ||
cacbb51e | 385 | Maybe the compilation was interrupted, and make doesn't notice that |
49976df5 UM |
386 | something is missing. Run "make clean; make". |
387 | ||
388 | If you used ./Configure instead of ./config, make sure that you | |
389 | selected the right target. File formats may differ slightly between | |
390 | OS versions (for example sparcv8/sparcv9, or a.out/elf). | |
391 | ||
0816bc22 UM |
392 | In case you get errors about the following symbols, use the config |
393 | option "no-asm", as described in INSTALL: | |
394 | ||
395 | BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, | |
396 | CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, | |
397 | RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, | |
398 | bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, | |
399 | bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, | |
400 | des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, | |
401 | des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order | |
402 | ||
569be071 | 403 | If none of these helps, you may want to try using the current snapshot. |
49976df5 UM |
404 | If the problem persists, please submit a bug report. |
405 | ||
406 | ||
0ae485dc | 407 | * Why does the OpenSSL test fail with "bc: command not found"? |
2b670ea2 | 408 | |
0ae485dc RL |
409 | You didn't install "bc", the Unix calculator. If you want to run the |
410 | tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. | |
2b670ea2 | 411 | |
2b670ea2 | 412 | |
a6ed5dd6 | 413 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
0ae485dc | 414 | |
1417f2dc RL |
415 | On some SCO installations or versions, bc has a bug that gets triggered |
416 | when you run the test suite (using "make test"). The message returned is | |
a6ed5dd6 | 417 | "bc: 1 not implemented". |
1417f2dc RL |
418 | |
419 | The best way to deal with this is to find another implementation of bc | |
420 | and compile/install it. GNU bc (see http://www.gnu.org/software/software.html | |
421 | for download instructions) can be safely used, for example. | |
f742e497 RL |
422 | |
423 | ||
424 | * Why does the OpenSSL test fail with "bc: stack empty"? | |
425 | ||
426 | On some DG/ux versions, bc seems to have a too small stack for calculations | |
427 | that the OpenSSL bntest throws at it. This gets triggered when you run the | |
428 | test suite (using "make test"). The message returned is "bc: stack empty". | |
429 | ||
430 | The best way to deal with this is to find another implementation of bc | |
431 | and compile/install it. GNU bc (see http://www.gnu.org/software/software.html | |
432 | for download instructions) can be safely used, for example. | |
0ae485dc RL |
433 | |
434 | ||
6bc847e4 | 435 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
0ae485dc | 436 | |
6bc847e4 | 437 | On some Alpha installations running Tru64 Unix and Compaq C, the compilation |
0ae485dc RL |
438 | of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual |
439 | memory to continue compilation.' As far as the tests have shown, this may be | |
440 | a compiler bug. What happens is that it eats up a lot of resident memory | |
441 | to build something, probably a table. The problem is clearly in the | |
442 | optimization code, because if one eliminates optimization completely (-O0), | |
443 | the compilation goes through (and the compiler consumes about 2MB of resident | |
444 | memory instead of 240MB or whatever one's limit is currently). | |
445 | ||
446 | There are three options to solve this problem: | |
447 | ||
448 | 1. set your current data segment size soft limit higher. Experience shows | |
449 | that about 241000 kbytes seems to be enough on an AlphaServer DS10. You do | |
450 | this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of | |
451 | kbytes to set the limit to. | |
452 | ||
453 | 2. If you have a hard limit that is lower than what you need and you can't | |
454 | get it changed, you can compile all of OpenSSL with -O0 as optimization | |
455 | level. This is however not a very nice thing to do for those who expect to | |
456 | get the best result from OpenSSL. A bit more complicated solution is the | |
457 | following: | |
458 | ||
459 | ----- snip:start ----- | |
460 | make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ | |
461 | sed -e 's/ -O[0-9] / -O0 /'`" | |
462 | rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` | |
463 | make | |
464 | ----- snip:end ----- | |
465 | ||
466 | This will only compile sha_dgst.c with -O0, the rest with the optimization | |
467 | level chosen by the configuration process. When the above is done, do the | |
468 | test and installation and you're set. | |
469 | ||
470 | ||
471 | * Why does the OpenSSL compilation fail with "ar: command not found"? | |
472 | ||
473 | Getting this message is quite usual on Solaris 2, because Sun has hidden | |
474 | away 'ar' and other development commands in directories that aren't in | |
475 | $PATH by default. One of those directories is '/usr/ccs/bin'. The | |
476 | quickest way to fix this is to do the following (it assumes you use sh | |
477 | or any sh-compatible shell): | |
478 | ||
479 | ----- snip:start ----- | |
480 | PATH=${PATH}:/usr/ccs/bin; export PATH | |
481 | ----- snip:end ----- | |
482 | ||
483 | and then redo the compilation. What you should really do is make sure | |
484 | '/usr/ccs/bin' is permanently in your $PATH, for example through your | |
485 | '.profile' (again, assuming you use a sh-compatible shell). | |
486 | ||
487 | ||
488 | * Why does the OpenSSL compilation fail on Win32 with VC++? | |
489 | ||
490 | Sometimes, you may get reports from VC++ command line (cl) that it | |
491 | can't find standard include files like stdio.h and other weirdnesses. | |
492 | One possible cause is that the environment isn't correctly set up. | |
3d6a84c4 RL |
493 | To solve that problem for VC++ versions up to 6, one should run |
494 | VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ | |
495 | installation directory (somewhere under 'Program Files'). For VC++ | |
496 | version 7 (and up?), which is also called VS.NET, the file is called | |
497 | VSVARS32.BAT instead. | |
498 | This needs to be done prior to running NMAKE, and the changes are only | |
499 | valid for the current DOS session. | |
0ae485dc RL |
500 | |
501 | ||
c4da6dd3 LJ |
502 | * What is special about OpenSSL on Redhat? |
503 | ||
876811e2 LJ |
504 | Red Hat Linux (release 7.0 and later) include a preinstalled limited |
505 | version of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2 | |
506 | is disabled in this version. The same may apply to other Linux distributions. | |
507 | Users may therefore wish to install more or all of the features left out. | |
c4da6dd3 LJ |
508 | |
509 | To do this you MUST ensure that you do not overwrite the openssl that is in | |
510 | /usr/bin on your Red Hat machine. Several packages depend on this file, | |
511 | including sendmail and ssh. /usr/local/bin is a good alternative choice. The | |
512 | libraries that come with Red Hat 7.0 onwards have different names and so are | |
513 | not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and | |
514 | /lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and | |
515 | /lib/libcrypto.so.2 respectively). | |
516 | ||
517 | Please note that we have been advised by Red Hat attempting to recompile the | |
518 | openssl rpm with all the cryptography enabled will not work. All other | |
519 | packages depend on the original Red Hat supplied openssl package. It is also | |
520 | worth noting that due to the way Red Hat supplies its packages, updates to | |
521 | openssl on each distribution never change the package version, only the | |
522 | build number. For example, on Red Hat 7.1, the latest openssl package has | |
523 | version number 0.9.6 and build number 9 even though it contains all the | |
524 | relevant updates in packages up to and including 0.9.6b. | |
525 | ||
526 | A possible way around this is to persuade Red Hat to produce a non-US | |
527 | version of Red Hat Linux. | |
528 | ||
876811e2 LJ |
529 | FYI: Patent numbers and expiry dates of US patents: |
530 | MDC-2: 4,908,861 13/03/2007 | |
531 | IDEA: 5,214,703 25/05/2010 | |
532 | RC5: 5,724,428 03/03/2015 | |
533 | ||
311e2099 RL |
534 | |
535 | * Why does the OpenSSL compilation fail on MacOS X? | |
536 | ||
537 | If the failure happens when trying to build the "openssl" binary, with | |
538 | a large number of undefined symbols, it's very probable that you have | |
539 | OpenSSL 0.9.6b delivered with the operating system (you can find out by | |
540 | running '/usr/bin/openssl version') and that you were trying to build | |
541 | OpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in | |
542 | MacOS X has a misfeature that's quite difficult to go around. | |
543 | Look in the file PROBLEMS for a more detailed explanation and for possible | |
544 | solutions. | |
545 | ||
546 | ||
547 | * Why does the OpenSSL test suite fail on MacOS X? | |
548 | ||
549 | If the failure happens when running 'make test' and the RC4 test fails, | |
550 | it's very probable that you have OpenSSL 0.9.6b delivered with the | |
551 | operating system (you can find out by running '/usr/bin/openssl version') | |
552 | and that you were trying to build OpenSSL 0.9.6d. The problem is that | |
553 | the loader ('ld') in MacOS X has a misfeature that's quite difficult to | |
554 | go around and has linked the programs "openssl" and the test programs | |
555 | with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the | |
556 | libraries you just built. | |
557 | Look in the file PROBLEMS for a more detailed explanation and for possible | |
558 | solutions. | |
559 | ||
26a60b2e | 560 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
e0b2073f AP |
561 | |
562 | Failure in BN_sqr test is most likely caused by a failure to configure the | |
26a60b2e AP |
563 | toolkit for current platform or lack of support for the platform in question. |
564 | Run './config -t' and './apps/openssl version -p'. Do these platform | |
565 | identifiers match? If they don't, then you most likely failed to run | |
566 | ./config and you're hereby advised to do so before filing a bug report. | |
567 | If ./config itself fails to run, then it's most likely problem with your | |
568 | local environment and you should turn to your system administrator (or | |
76a03d56 AP |
569 | similar). If identifiers match (and/or no alternative identifier is |
570 | suggested by ./config script), then the platform is unsupported. There might | |
571 | or might not be a workaround. Most notably on SPARC64 platforms with GNU | |
572 | C compiler you should be able to produce a working build by running | |
573 | './config -m32'. I understand that -m32 might not be what you want/need, | |
85f258d1 AP |
574 | but the build should be operational. For further details turn to |
575 | <openssl-dev@openssl.org>. | |
576 | ||
75c40285 | 577 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
85f258d1 | 578 | |
75c40285 AP |
579 | As of 0.9.7 assembler routines were overhauled for position independence |
580 | of the machine code, which is essential for shared library support. For | |
581 | some reason OpenBSD is equipped with an out-of-date GNU assembler which | |
582 | finds the new code offensive. To work around the problem, configure with | |
0382c95e AP |
583 | no-asm (and sacrifice a great deal of performance) or patch your assembler |
584 | according to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. | |
75c40285 | 585 | For your convenience a pre-compiled replacement binary is provided at |
1a6356b2 AP |
586 | <URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. |
587 | Reportedly elder *BSD a.out platforms also suffer from this problem and | |
588 | remedy should be same. Provided binary is statically linked and should be | |
589 | working across wider range of *BSD branches, not just OpenBSD. | |
e0b2073f | 590 | |
0ae485dc RL |
591 | [PROG] ======================================================================== |
592 | ||
593 | * Is OpenSSL thread-safe? | |
594 | ||
595 | Yes (with limitations: an SSL connection may not concurrently be used | |
596 | by multiple threads). On Windows and many Unix systems, OpenSSL | |
597 | automatically uses the multi-threaded versions of the standard | |
598 | libraries. If your platform is not one of these, consult the INSTALL | |
599 | file. | |
600 | ||
601 | Multi-threaded applications must provide two callback functions to | |
602 | OpenSSL. This is described in the threads(3) manpage. | |
e8dbc159 | 603 | |
afee764c | 604 | |
46e80a30 DSH |
605 | * I've compiled a program under Windows and it crashes: why? |
606 | ||
a542db90 RL |
607 | This is usually because you've missed the comment in INSTALL.W32. |
608 | Your application must link against the same version of the Win32 | |
609 | C-Runtime against which your openssl libraries were linked. The | |
610 | default version for OpenSSL is /MD - "Multithreaded DLL". | |
611 | ||
612 | If you are using Microsoft Visual C++'s IDE (Visual Studio), in | |
613 | many cases, your new project most likely defaulted to "Debug | |
614 | Singlethreaded" - /ML. This is NOT interchangeable with /MD and your | |
615 | program will crash, typically on the first BIO related read or write | |
616 | operation. | |
617 | ||
618 | For each of the six possible link stage configurations within Win32, | |
619 | your application must link against the same by which OpenSSL was | |
620 | built. If you are using MS Visual C++ (Studio) this can be changed | |
621 | by: | |
622 | ||
623 | 1. Select Settings... from the Project Menu. | |
624 | 2. Select the C/C++ Tab. | |
625 | 3. Select "Code Generation from the "Category" drop down list box | |
626 | 4. Select the Appropriate library (see table below) from the "Use | |
627 | run-time library" drop down list box. Perform this step for both | |
628 | your debug and release versions of your application (look at the | |
629 | top left of the settings panel to change between the two) | |
630 | ||
631 | Single Threaded /ML - MS VC++ often defaults to | |
632 | this for the release | |
633 | version of a new project. | |
634 | Debug Single Threaded /MLd - MS VC++ often defaults to | |
635 | this for the debug version | |
636 | of a new project. | |
637 | Multithreaded /MT | |
638 | Debug Multithreaded /MTd | |
639 | Multithreaded DLL /MD - OpenSSL defaults to this. | |
640 | Debug Multithreaded DLL /MDd | |
641 | ||
642 | Note that debug and release libraries are NOT interchangeable. If you | |
643 | built OpenSSL with /MD your application must use /MD and cannot use /MDd. | |
46e80a30 DSH |
644 | |
645 | ||
c5a3b7e7 DSH |
646 | * How do I read or write a DER encoded buffer using the ASN1 functions? |
647 | ||
648 | You have two options. You can either use a memory BIO in conjunction | |
649 | with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the | |
650 | i2d_XXX(), d2i_XXX() functions directly. Since these are often the | |
651 | cause of grief here are some code fragments using PKCS7 as an example: | |
652 | ||
653 | unsigned char *buf, *p; | |
654 | int len; | |
655 | ||
656 | len = i2d_PKCS7(p7, NULL); | |
7cae5f9f | 657 | buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ |
c5a3b7e7 DSH |
658 | p = buf; |
659 | i2d_PKCS7(p7, &p); | |
660 | ||
661 | At this point buf contains the len bytes of the DER encoding of | |
662 | p7. | |
663 | ||
664 | The opposite assumes we already have len bytes in buf: | |
665 | ||
666 | unsigned char *p; | |
667 | p = buf; | |
668 | p7 = d2i_PKCS7(NULL, &p, len); | |
669 | ||
670 | At this point p7 contains a valid PKCS7 structure of NULL if an error | |
671 | occurred. If an error occurred ERR_print_errors(bio) should give more | |
672 | information. | |
673 | ||
674 | The reason for the temporary variable 'p' is that the ASN1 functions | |
675 | increment the passed pointer so it is ready to read or write the next | |
676 | structure. This is often a cause of problems: without the temporary | |
677 | variable the buffer pointer is changed to point just after the data | |
678 | that has been read or written. This may well be uninitialized data | |
679 | and attempts to free the buffer will have unpredictable results | |
680 | because it no longer points to the same address. | |
681 | ||
682 | ||
84b65340 DSH |
683 | * I've tried using <M_some_evil_pkcs12_macro> and I get errors why? |
684 | ||
685 | This usually happens when you try compiling something using the PKCS#12 | |
686 | macros with a C++ compiler. There is hardly ever any need to use the | |
687 | PKCS#12 macros in a program, it is much easier to parse and create | |
688 | PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions | |
689 | documented in doc/openssl.txt and with examples in demos/pkcs12. The | |
690 | 'pkcs12' application has to use the macros because it prints out | |
691 | debugging information. | |
692 | ||
693 | ||
35af460f DSH |
694 | * I've called <some function> and it fails, why? |
695 | ||
02859fb7 BM |
696 | Before submitting a report or asking in one of the mailing lists, you |
697 | should try to determine the cause. In particular, you should call | |
35af460f | 698 | ERR_print_errors() or ERR_print_errors_fp() after the failed call |
02859fb7 BM |
699 | and see if the message helps. Note that the problem may occur earlier |
700 | than you think -- you should check for errors after every call where | |
701 | it is possible, otherwise the actual problem may be hidden because | |
702 | some OpenSSL functions clear the error state. | |
35af460f DSH |
703 | |
704 | ||
705 | * I just get a load of numbers for the error output, what do they mean? | |
706 | ||
707 | The actual format is described in the ERR_print_errors() manual page. | |
708 | You should call the function ERR_load_crypto_strings() before hand and | |
709 | the message will be output in text form. If you can't do this (for example | |
710 | it is a pre-compiled binary) you can use the errstr utility on the error | |
711 | code itself (the hex digits after the second colon). | |
712 | ||
713 | ||
46e80a30 DSH |
714 | * Why do I get errors about unknown algorithms? |
715 | ||
716 | This can happen under several circumstances such as reading in an | |
717 | encrypted private key or attempting to decrypt a PKCS#12 file. The cause | |
718 | is forgetting to load OpenSSL's table of algorithms with | |
719 | OpenSSL_add_all_algorithms(). See the manual page for more information. | |
720 | ||
721 | ||
e8dbc159 RL |
722 | * Why can't the OpenSSH configure script detect OpenSSL? |
723 | ||
a116afa4 LJ |
724 | Several reasons for problems with the automatic detection exist. |
725 | OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. | |
726 | Sometimes the distribution has installed an older version in the system | |
727 | locations that is detected instead of a new one installed. The OpenSSL | |
728 | library might have been compiled for another CPU or another mode (32/64 bits). | |
729 | Permissions might be wrong. | |
730 | ||
731 | The general answer is to check the config.log file generated when running | |
732 | the OpenSSH configure script. It should contain the detailed information | |
733 | on why the OpenSSL library was not detected or considered incompatible. | |
31efc3a7 | 734 | |
0ae485dc | 735 | * Can I use OpenSSL's SSL library with non-blocking I/O? |
bf55ece1 | 736 | |
0ae485dc | 737 | Yes; make sure to read the SSL_get_error(3) manual page! |
bf55ece1 | 738 | |
0ae485dc RL |
739 | A pitfall to avoid: Don't assume that SSL_read() will just read from |
740 | the underlying transport or that SSL_write() will just write to it -- | |
741 | it is also possible that SSL_write() cannot do any useful work until | |
742 | there is data to read, or that SSL_read() cannot do anything until it | |
743 | is possible to send data. One reason for this is that the peer may | |
744 | request a new TLS/SSL handshake at any time during the protocol, | |
745 | requiring a bi-directional message exchange; both SSL_read() and | |
746 | SSL_write() will try to continue any pending handshake. | |
bf55ece1 | 747 | |
bf55ece1 | 748 | |
19732245 LJ |
749 | * Why doesn't my server application receive a client certificate? |
750 | ||
751 | Due to the TLS protocol definition, a client will only send a certificate, | |
e3fefbfd | 752 | if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the |
19732245 LJ |
753 | SSL_CTX_set_verify() function to enable the use of client certificates. |
754 | ||
755 | ||
e1f7ea25 LJ |
756 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
757 | ||
e8233e69 LJ |
758 | For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier |
759 | versions, uniqueIdentifier was incorrectly used for X.509 certificates. | |
760 | The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. | |
761 | Change your code to use the new name when compiling against OpenSSL 0.9.7. | |
e1f7ea25 LJ |
762 | |
763 | ||
0ae485dc | 764 | =============================================================================== |
bf55ece1 | 765 |