1 | OpenSSL - Frequently Asked Questions |
---|
2 | -------------------------------------- |
---|
3 | |
---|
4 | [MISC] Miscellaneous questions |
---|
5 | |
---|
6 | * Which is the current version of OpenSSL? |
---|
7 | * Where is the documentation? |
---|
8 | * How can I contact the OpenSSL developers? |
---|
9 | * Where can I get a compiled version of OpenSSL? |
---|
10 | * Why aren't tools like 'autoconf' and 'libtool' used? |
---|
11 | * What is an 'engine' version? |
---|
12 | * How do I check the authenticity of the OpenSSL distribution? |
---|
13 | |
---|
14 | [LEGAL] Legal questions |
---|
15 | |
---|
16 | * Do I need patent licenses to use OpenSSL? |
---|
17 | * Can I use OpenSSL with GPL software? |
---|
18 | |
---|
19 | [USER] Questions on using the OpenSSL applications |
---|
20 | |
---|
21 | * Why do I get a "PRNG not seeded" error message? |
---|
22 | * Why do I get an "unable to write 'random state'" error message? |
---|
23 | * How do I create certificates or certificate requests? |
---|
24 | * Why can't I create certificate requests? |
---|
25 | * Why does <SSL program> fail with a certificate verify error? |
---|
26 | * Why can I only use weak ciphers when I connect to a server using OpenSSL? |
---|
27 | * How can I create DSA certificates? |
---|
28 | * Why can't I make an SSL connection using a DSA certificate? |
---|
29 | * How can I remove the passphrase on a private key? |
---|
30 | * Why can't I use OpenSSL certificates with SSL client authentication? |
---|
31 | * Why does my browser give a warning about a mismatched hostname? |
---|
32 | * How do I install a CA certificate into a browser? |
---|
33 | * Why is OpenSSL x509 DN output not conformant to RFC2253? |
---|
34 | |
---|
35 | [BUILD] Questions about building and testing OpenSSL |
---|
36 | |
---|
37 | * Why does the linker complain about undefined symbols? |
---|
38 | * Why does the OpenSSL test fail with "bc: command not found"? |
---|
39 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
---|
40 | * Why does the OpenSSL test fail with "bc: stack empty"? |
---|
41 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
---|
42 | * Why does the OpenSSL compilation fail with "ar: command not found"? |
---|
43 | * Why does the OpenSSL compilation fail on Win32 with VC++? |
---|
44 | * What is special about OpenSSL on Redhat? |
---|
45 | * Why does the OpenSSL compilation fail on MacOS X? |
---|
46 | * Why does the OpenSSL test suite fail on MacOS X? |
---|
47 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
---|
48 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
---|
49 | |
---|
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? |
---|
61 | * Why doesn't my server application receive a client certificate? |
---|
62 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
---|
63 | |
---|
64 | =============================================================================== |
---|
65 | |
---|
66 | [MISC] ======================================================================== |
---|
67 | |
---|
68 | * Which is the current version of OpenSSL? |
---|
69 | |
---|
70 | The current version is available from <URL: http://www.openssl.org>. |
---|
71 | OpenSSL 0.9.7c was released on September 30, 2003. |
---|
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 | |
---|
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 | |
---|
101 | There is some documentation about certificate extensions and PKCS#12 |
---|
102 | in doc/openssl.txt |
---|
103 | |
---|
104 | The original SSLeay documentation is included in OpenSSL as |
---|
105 | doc/ssleay.txt. It may be useful when none of the other resources |
---|
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 | |
---|
117 | * Where can I get a compiled version of OpenSSL? |
---|
118 | |
---|
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). |
---|
122 | |
---|
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. |
---|
126 | |
---|
127 | A number of Linux and *BSD distributions include OpenSSL. |
---|
128 | |
---|
129 | |
---|
130 | * Why aren't tools like 'autoconf' and 'libtool' used? |
---|
131 | |
---|
132 | autoconf will probably be used in future OpenSSL versions. If it was |
---|
133 | less Unix-centric, it might have been used much earlier. |
---|
134 | |
---|
135 | * What is an 'engine' version? |
---|
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 |
---|
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. |
---|
141 | |
---|
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 | |
---|
155 | [LEGAL] ======================================================================= |
---|
156 | |
---|
157 | * Do I need patent licenses to use OpenSSL? |
---|
158 | |
---|
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 | |
---|
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 |
---|
179 | useful to choose an other license than the GPL, or state explicitly that |
---|
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 | |
---|
186 | [USER] ======================================================================== |
---|
187 | |
---|
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" (/dev/urandom or /dev/random) that serves this purpose. |
---|
193 | All OpenSSL versions try to use /dev/urandom by default; starting with |
---|
194 | version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not |
---|
195 | available. |
---|
196 | |
---|
197 | On other systems, applications have to call the RAND_add() or |
---|
198 | RAND_seed() function with appropriate data before generating keys or |
---|
199 | performing public key encryption. (These functions initialize the |
---|
200 | pseudo-random number generator, PRNG.) Some broken applications do |
---|
201 | not do this. As of version 0.9.5, the OpenSSL functions that need |
---|
202 | randomness report an error if the random number generator has not been |
---|
203 | seeded with at least 128 bits of randomness. If this error occurs and |
---|
204 | is not discussed in the documentation of the application you are |
---|
205 | using, please contact the author of that application; it is likely |
---|
206 | that it never worked correctly. OpenSSL 0.9.5 and later make the |
---|
207 | error visible by refusing to perform potentially insecure encryption. |
---|
208 | |
---|
209 | If you are using Solaris 8, you can add /dev/urandom and /dev/random |
---|
210 | devices by installing patch 112438 (Sparc) or 112439 (x86), which are |
---|
211 | available via the Patchfinder at <URL: http://sunsolve.sun.com> |
---|
212 | (Solaris 9 includes these devices by default). For /dev/random support |
---|
213 | for earlier Solaris versions, see Sun's statement at |
---|
214 | <URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> |
---|
215 | (the SUNWski package is available in patch 105710). |
---|
216 | |
---|
217 | On systems without /dev/urandom and /dev/random, it is a good idea to |
---|
218 | use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for |
---|
219 | details. Starting with version 0.9.7, OpenSSL will automatically look |
---|
220 | for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and |
---|
221 | /etc/entropy. |
---|
222 | |
---|
223 | Most components of the openssl command line utility automatically try |
---|
224 | to seed the random number generator from a file. The name of the |
---|
225 | default seeding file is determined as follows: If environment variable |
---|
226 | RANDFILE is set, then it names the seeding file. Otherwise if |
---|
227 | environment variable HOME is set, then the seeding file is $HOME/.rnd. |
---|
228 | If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will |
---|
229 | use file .rnd in the current directory while OpenSSL 0.9.6a uses no |
---|
230 | default seeding file at all. OpenSSL 0.9.6b and later will behave |
---|
231 | similarly to 0.9.6a, but will use a default of "C:\" for HOME on |
---|
232 | Windows systems if the environment variable has not been set. |
---|
233 | |
---|
234 | If the default seeding file does not exist or is too short, the "PRNG |
---|
235 | not seeded" error message may occur. |
---|
236 | |
---|
237 | The openssl command line utility will write back a new state to the |
---|
238 | default seeding file (and create this file if necessary) unless |
---|
239 | there was no sufficient seeding. |
---|
240 | |
---|
241 | Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. |
---|
242 | Use the "-rand" option of the OpenSSL command line tools instead. |
---|
243 | The $RANDFILE environment variable and $HOME/.rnd are only used by the |
---|
244 | OpenSSL command line tools. Applications using the OpenSSL library |
---|
245 | provide their own configuration options to specify the entropy source, |
---|
246 | please check out the documentation coming the with application. |
---|
247 | |
---|
248 | |
---|
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 | |
---|
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 | |
---|
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 |
---|
335 | CA list". How you do this depends on the server software in uses. You can |
---|
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 | |
---|
340 | If your server only requests certificates on certain URLs then you may need |
---|
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 | |
---|
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 | |
---|
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. |
---|
380 | |
---|
381 | [BUILD] ======================================================================= |
---|
382 | |
---|
383 | * Why does the linker complain about undefined symbols? |
---|
384 | |
---|
385 | Maybe the compilation was interrupted, and make doesn't notice that |
---|
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 | |
---|
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 | |
---|
403 | If none of these helps, you may want to try using the current snapshot. |
---|
404 | If the problem persists, please submit a bug report. |
---|
405 | |
---|
406 | |
---|
407 | * Why does the OpenSSL test fail with "bc: command not found"? |
---|
408 | |
---|
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. |
---|
411 | |
---|
412 | |
---|
413 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
---|
414 | |
---|
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 |
---|
417 | "bc: 1 not implemented". |
---|
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. |
---|
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. |
---|
433 | |
---|
434 | |
---|
435 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
---|
436 | |
---|
437 | On some Alpha installations running Tru64 Unix and Compaq C, the compilation |
---|
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. |
---|
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. |
---|
500 | |
---|
501 | |
---|
502 | * What is special about OpenSSL on Redhat? |
---|
503 | |
---|
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. |
---|
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 | |
---|
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 | |
---|
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 | |
---|
560 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
---|
561 | |
---|
562 | Failure in BN_sqr test is most likely caused by a failure to configure the |
---|
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 |
---|
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, |
---|
574 | but the build should be operational. For further details turn to |
---|
575 | <openssl-dev@openssl.org>. |
---|
576 | |
---|
577 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
---|
578 | |
---|
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 |
---|
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>. |
---|
585 | For your convenience a pre-compiled replacement binary is provided at |
---|
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. |
---|
590 | |
---|
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. |
---|
603 | |
---|
604 | |
---|
605 | * I've compiled a program under Windows and it crashes: why? |
---|
606 | |
---|
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. |
---|
644 | |
---|
645 | |
---|
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); |
---|
657 | buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ |
---|
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 | |
---|
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 | |
---|
694 | * I've called <some function> and it fails, why? |
---|
695 | |
---|
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 |
---|
698 | ERR_print_errors() or ERR_print_errors_fp() after the failed call |
---|
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. |
---|
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 | |
---|
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 | |
---|
722 | * Why can't the OpenSSH configure script detect OpenSSL? |
---|
723 | |
---|
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. |
---|
734 | |
---|
735 | |
---|
736 | * Can I use OpenSSL's SSL library with non-blocking I/O? |
---|
737 | |
---|
738 | Yes; make sure to read the SSL_get_error(3) manual page! |
---|
739 | |
---|
740 | A pitfall to avoid: Don't assume that SSL_read() will just read from |
---|
741 | the underlying transport or that SSL_write() will just write to it -- |
---|
742 | it is also possible that SSL_write() cannot do any useful work until |
---|
743 | there is data to read, or that SSL_read() cannot do anything until it |
---|
744 | is possible to send data. One reason for this is that the peer may |
---|
745 | request a new TLS/SSL handshake at any time during the protocol, |
---|
746 | requiring a bi-directional message exchange; both SSL_read() and |
---|
747 | SSL_write() will try to continue any pending handshake. |
---|
748 | |
---|
749 | |
---|
750 | * Why doesn't my server application receive a client certificate? |
---|
751 | |
---|
752 | Due to the TLS protocol definition, a client will only send a certificate, |
---|
753 | if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the |
---|
754 | SSL_CTX_set_verify() function to enable the use of client certificates. |
---|
755 | |
---|
756 | |
---|
757 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
---|
758 | |
---|
759 | For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier |
---|
760 | versions, uniqueIdentifier was incorrectly used for X.509 certificates. |
---|
761 | The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. |
---|
762 | Change your code to use the new name when compiling against OpenSSL 0.9.7. |
---|
763 | |
---|
764 | |
---|
765 | =============================================================================== |
---|
766 | |
---|