]>
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? |
2131ce57 | 13 | * How does the versioning scheme work? |
0ae485dc RL |
14 | |
15 | [LEGAL] Legal questions | |
16 | ||
c1ce32f1 | 17 | * Do I need patent licenses to use OpenSSL? |
17e75747 | 18 | * Can I use OpenSSL with GPL software? |
0ae485dc RL |
19 | |
20 | [USER] Questions on using the OpenSSL applications | |
21 | ||
f9a7c34f | 22 | * Why do I get a "PRNG not seeded" error message? |
24cc290b | 23 | * Why do I get an "unable to write 'random state'" error message? |
46e80a30 DSH |
24 | * How do I create certificates or certificate requests? |
25 | * Why can't I create certificate requests? | |
afee764c | 26 | * Why does <SSL program> fail with a certificate verify error? |
a331a305 | 27 | * Why can I only use weak ciphers when I connect to a server using OpenSSL? |
afee764c DSH |
28 | * How can I create DSA certificates? |
29 | * Why can't I make an SSL connection using a DSA certificate? | |
a331a305 | 30 | * How can I remove the passphrase on a private key? |
1a7b2d33 | 31 | * Why can't I use OpenSSL certificates with SSL client authentication? |
7522254b | 32 | * Why does my browser give a warning about a mismatched hostname? |
0b33bc6b | 33 | * How do I install a CA certificate into a browser? |
17e2c77a | 34 | * Why is OpenSSL x509 DN output not conformant to RFC2253? |
09b6c2ef | 35 | * What is a "128 bit certificate"? Can I create one with OpenSSL? |
a070f0da | 36 | * Why does OpenSSL set the authority key identifier extension incorrectly? |
2cd81830 | 37 | * How can I set up a bundle of commercial root CA certificates? |
5ef24a80 | 38 | * Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug? |
0ae485dc RL |
39 | |
40 | [BUILD] Questions about building and testing OpenSSL | |
41 | ||
42 | * Why does the linker complain about undefined symbols? | |
c32364f5 | 43 | * Why does the OpenSSL test fail with "bc: command not found"? |
a6ed5dd6 | 44 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
f742e497 | 45 | * Why does the OpenSSL test fail with "bc: stack empty"? |
6bc847e4 | 46 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
b364e5d2 | 47 | * Why does the OpenSSL compilation fail with "ar: command not found"? |
bf55ece1 | 48 | * Why does the OpenSSL compilation fail on Win32 with VC++? |
c4da6dd3 | 49 | * What is special about OpenSSL on Redhat? |
311e2099 RL |
50 | * Why does the OpenSSL compilation fail on MacOS X? |
51 | * Why does the OpenSSL test suite fail on MacOS X? | |
26a60b2e | 52 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
75c40285 | 53 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
851e31ff | 54 | * Why does the OpenSSL test suite fail in sha512t on x86 CPU? |
4b559868 | 55 | * Why does compiler fail to compile sha512.c? |
65613f23 | 56 | * Test suite still fails, what to do? |
c25a0aae DSH |
57 | * I think I've found a bug, what should I do? |
58 | * I'm SURE I've found a bug, how do I report it? | |
59 | * I've found a security issue, how do I report it? | |
f9a7c34f | 60 | |
0ae485dc RL |
61 | [PROG] Questions about programming with OpenSSL |
62 | ||
63 | * Is OpenSSL thread-safe? | |
64 | * I've compiled a program under Windows and it crashes: why? | |
65 | * How do I read or write a DER encoded buffer using the ASN1 functions? | |
6ef7b78e | 66 | * OpenSSL uses DER but I need BER format: does OpenSSL support BER? |
0ae485dc RL |
67 | * I've tried using <M_some_evil_pkcs12_macro> and I get errors why? |
68 | * I've called <some function> and it fails, why? | |
69 | * I just get a load of numbers for the error output, what do they mean? | |
70 | * Why do I get errors about unknown algorithms? | |
71 | * Why can't the OpenSSH configure script detect OpenSSL? | |
72 | * Can I use OpenSSL's SSL library with non-blocking I/O? | |
19732245 | 73 | * Why doesn't my server application receive a client certificate? |
e1f7ea25 | 74 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
6ef7b78e | 75 | * I think I've detected a memory leak, is this a bug? |
7bbce697 | 76 | * Why does Valgrind complain about the use of uninitialized data? |
715020e3 | 77 | * Why doesn't a memory BIO work when a file does? |
dd57b657 | 78 | * Where are the declarations and implementations of d2i_X509() etc? |
e796666d | 79 | * When debugging I observe SIGILL during OpenSSL initialization: why? |
0ae485dc RL |
80 | |
81 | =============================================================================== | |
82 | ||
83 | [MISC] ======================================================================== | |
f9a7c34f | 84 | |
49976df5 UM |
85 | * Which is the current version of OpenSSL? |
86 | ||
87 | The current version is available from <URL: http://www.openssl.org>. | |
49976df5 UM |
88 | |
89 | In addition to the current stable release, you can also access daily | |
90 | snapshots of the OpenSSL development version at <URL: | |
9fa24352 | 91 | ftp://ftp.openssl.org/snapshot/>, or get it by anonymous Git access. |
49976df5 UM |
92 | |
93 | ||
f9a7c34f UM |
94 | * Where is the documentation? |
95 | ||
96 | OpenSSL is a library that provides cryptographic functionality to | |
97 | applications such as secure web servers. Be sure to read the | |
98 | documentation of the application you want to use. The INSTALL file | |
99 | explains how to install this library. | |
100 | ||
101 | OpenSSL includes a command line utility that can be used to perform a | |
102 | variety of cryptographic functions. It is described in the openssl(1) | |
2693812d DSH |
103 | manpage. Documentation for developers is currently being written. Many |
104 | manual pages are available; overviews over libcrypto and | |
f9a7c34f UM |
105 | libssl are given in the crypto(3) and ssl(3) manpages. |
106 | ||
107 | The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a | |
108 | different directory if you specified one as described in INSTALL). | |
109 | In addition, you can read the most current versions at | |
2693812d DSH |
110 | <URL: http://www.openssl.org/docs/>. Note that the online documents refer |
111 | to the very latest development versions of OpenSSL and may include features | |
112 | not present in released versions. If in doubt refer to the documentation | |
597dab0f DSH |
113 | that came with the version of OpenSSL you are using. The pod format |
114 | documentation is included in each OpenSSL distribution under the docs | |
115 | directory. | |
f9a7c34f | 116 | |
fbb41ae0 DSH |
117 | There is some documentation about certificate extensions and PKCS#12 |
118 | in doc/openssl.txt | |
119 | ||
f9a7c34f | 120 | The original SSLeay documentation is included in OpenSSL as |
cacbb51e | 121 | doc/ssleay.txt. It may be useful when none of the other resources |
f9a7c34f UM |
122 | help, but please note that it reflects the obsolete version SSLeay |
123 | 0.6.6. | |
124 | ||
125 | ||
126 | * How can I contact the OpenSSL developers? | |
127 | ||
128 | The README file describes how to submit bug reports and patches to | |
129 | OpenSSL. Information on the OpenSSL mailing lists is available from | |
130 | <URL: http://www.openssl.org>. | |
131 | ||
132 | ||
0ae485dc | 133 | * Where can I get a compiled version of OpenSSL? |
f9a7c34f | 134 | |
d9f40bbe | 135 | You can finder pointers to binary distributions in |
616f71e4 | 136 | <URL: http://www.openssl.org/about/binaries.html> . |
d9f40bbe | 137 | |
0ae485dc RL |
138 | Some applications that use OpenSSL are distributed in binary form. |
139 | When using such an application, you don't need to install OpenSSL | |
140 | yourself; the application will include the required parts (e.g. DLLs). | |
f9a7c34f | 141 | |
d9f40bbe | 142 | If you want to build OpenSSL on a Windows system and you don't have |
0ae485dc RL |
143 | a C compiler, read the "Mingw32" section of INSTALL.W32 for information |
144 | on how to obtain and install the free GNU C compiler. | |
f9a7c34f | 145 | |
0ae485dc | 146 | A number of Linux and *BSD distributions include OpenSSL. |
f9a7c34f | 147 | |
f9a7c34f | 148 | |
0ae485dc | 149 | * Why aren't tools like 'autoconf' and 'libtool' used? |
f9a7c34f | 150 | |
ba93fd6a UM |
151 | autoconf will probably be used in future OpenSSL versions. If it was |
152 | less Unix-centric, it might have been used much earlier. | |
f9a7c34f | 153 | |
a0256f46 | 154 | * What is an 'engine' version? |
679df234 LJ |
155 | |
156 | With version 0.9.6 OpenSSL was extended to interface to external crypto | |
157 | hardware. This was realized in a special release '0.9.6-engine'. With | |
034bae10 NL |
158 | version 0.9.7 the changes were merged into the main development line, |
159 | so that the special release is no longer necessary. | |
b1d6e3f5 | 160 | |
d4e573f3 RL |
161 | * How do I check the authenticity of the OpenSSL distribution? |
162 | ||
163 | We provide MD5 digests and ASC signatures of each tarball. | |
164 | Use MD5 to check that a tarball from a mirror site is identical: | |
165 | ||
166 | md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5 | |
167 | ||
168 | You can check authenticity using pgp or gpg. You need the OpenSSL team | |
e6e1f4cb MC |
169 | member public key used to sign it (download it from a key server, see a |
170 | list of keys at <URL: http://www.openssl.org/about/>). Then | |
d4e573f3 RL |
171 | just do: |
172 | ||
173 | pgp TARBALL.asc | |
174 | ||
2131ce57 DSH |
175 | * How does the versioning scheme work? |
176 | ||
177 | After the release of OpenSSL 1.0.0 the versioning scheme changed. Letter | |
178 | releases (e.g. 1.0.1a) can only contain bug and security fixes and no | |
179 | new features. Minor releases change the last number (e.g. 1.0.2) and | |
180 | can contain new features that retain binary compatibility. Changes to | |
181 | the middle number are considered major releases and neither source nor | |
182 | binary compatibility is guaranteed. | |
183 | ||
184 | Therefore the answer to the common question "when will feature X be | |
185 | backported to OpenSSL 1.0.0/0.9.8?" is "never" but it could appear | |
186 | in the next minor release. | |
187 | ||
2527b94f DSH |
188 | * What happens when the letter release reaches z? |
189 | ||
190 | It was decided after the release of OpenSSL 0.9.8y the next version should | |
191 | be 0.9.8za then 0.9.8zb and so on. | |
192 | ||
193 | ||
0ae485dc | 194 | [LEGAL] ======================================================================= |
b1d6e3f5 | 195 | |
0ae485dc | 196 | * Do I need patent licenses to use OpenSSL? |
b1d6e3f5 | 197 | |
ce455596 DSH |
198 | For information on intellectual property rights, please consult a lawyer. |
199 | The OpenSSL team does not offer legal advice. | |
0ae485dc | 200 | |
af1048c2 BM |
201 | You can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using |
202 | ./config no-idea no-mdc2 no-rc5 | |
0ae485dc RL |
203 | |
204 | ||
17e75747 UM |
205 | * Can I use OpenSSL with GPL software? |
206 | ||
207 | On many systems including the major Linux and BSD distributions, yes (the | |
208 | GPL does not place restrictions on using libraries that are part of the | |
209 | normal operating system distribution). | |
210 | ||
211 | On other systems, the situation is less clear. Some GPL software copyright | |
212 | holders claim that you infringe on their rights if you use OpenSSL with | |
213 | their software on operating systems that don't normally include OpenSSL. | |
214 | ||
215 | If you develop open source software that uses OpenSSL, you may find it | |
e3fefbfd | 216 | useful to choose an other license than the GPL, or state explicitly that |
17e75747 UM |
217 | "This program is released under the GPL with the additional exemption that |
218 | compiling, linking, and/or using OpenSSL is allowed." If you are using | |
219 | GPL software developed by others, you may want to ask the copyright holder | |
220 | for permission to use their software with OpenSSL. | |
221 | ||
222 | ||
0ae485dc | 223 | [USER] ======================================================================== |
b1d6e3f5 | 224 | |
f9a7c34f UM |
225 | * Why do I get a "PRNG not seeded" error message? |
226 | ||
227 | Cryptographic software needs a source of unpredictable data to work | |
228 | correctly. Many open source operating systems provide a "randomness | |
c09a2978 BM |
229 | device" (/dev/urandom or /dev/random) that serves this purpose. |
230 | All OpenSSL versions try to use /dev/urandom by default; starting with | |
379e5689 | 231 | version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not |
c09a2978 BM |
232 | available. |
233 | ||
234 | On other systems, applications have to call the RAND_add() or | |
235 | RAND_seed() function with appropriate data before generating keys or | |
236 | performing public key encryption. (These functions initialize the | |
237 | pseudo-random number generator, PRNG.) Some broken applications do | |
238 | not do this. As of version 0.9.5, the OpenSSL functions that need | |
239 | randomness report an error if the random number generator has not been | |
240 | seeded with at least 128 bits of randomness. If this error occurs and | |
241 | is not discussed in the documentation of the application you are | |
242 | using, please contact the author of that application; it is likely | |
243 | that it never worked correctly. OpenSSL 0.9.5 and later make the | |
244 | error visible by refusing to perform potentially insecure encryption. | |
245 | ||
246 | If you are using Solaris 8, you can add /dev/urandom and /dev/random | |
247 | devices by installing patch 112438 (Sparc) or 112439 (x86), which are | |
248 | available via the Patchfinder at <URL: http://sunsolve.sun.com> | |
249 | (Solaris 9 includes these devices by default). For /dev/random support | |
250 | for earlier Solaris versions, see Sun's statement at | |
251 | <URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> | |
252 | (the SUNWski package is available in patch 105710). | |
8311d323 | 253 | |
d9a770e6 BM |
254 | On systems without /dev/urandom and /dev/random, it is a good idea to |
255 | use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for | |
256 | details. Starting with version 0.9.7, OpenSSL will automatically look | |
257 | for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and | |
258 | /etc/entropy. | |
2b670ea2 | 259 | |
24cc290b BM |
260 | Most components of the openssl command line utility automatically try |
261 | to seed the random number generator from a file. The name of the | |
262 | default seeding file is determined as follows: If environment variable | |
263 | RANDFILE is set, then it names the seeding file. Otherwise if | |
264 | environment variable HOME is set, then the seeding file is $HOME/.rnd. | |
265 | If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will | |
266 | use file .rnd in the current directory while OpenSSL 0.9.6a uses no | |
267 | default seeding file at all. OpenSSL 0.9.6b and later will behave | |
6af59bc0 | 268 | similarly to 0.9.6a, but will use a default of "C:\" for HOME on |
24cc290b BM |
269 | Windows systems if the environment variable has not been set. |
270 | ||
271 | If the default seeding file does not exist or is too short, the "PRNG | |
272 | not seeded" error message may occur. | |
273 | ||
274 | The openssl command line utility will write back a new state to the | |
275 | default seeding file (and create this file if necessary) unless | |
276 | there was no sufficient seeding. | |
277 | ||
35feed50 LJ |
278 | Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. |
279 | Use the "-rand" option of the OpenSSL command line tools instead. | |
280 | The $RANDFILE environment variable and $HOME/.rnd are only used by the | |
281 | OpenSSL command line tools. Applications using the OpenSSL library | |
282 | provide their own configuration options to specify the entropy source, | |
283 | please check out the documentation coming the with application. | |
8311d323 | 284 | |
2b670ea2 | 285 | |
24cc290b BM |
286 | * Why do I get an "unable to write 'random state'" error message? |
287 | ||
288 | ||
289 | Sometimes the openssl command line utility does not abort with | |
290 | a "PRNG not seeded" error message, but complains that it is | |
291 | "unable to write 'random state'". This message refers to the | |
292 | default seeding file (see previous answer). A possible reason | |
293 | is that no default filename is known because neither RANDFILE | |
294 | nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the | |
295 | current directory in this case, but this has changed with 0.9.6a.) | |
296 | ||
297 | ||
0ae485dc RL |
298 | * How do I create certificates or certificate requests? |
299 | ||
300 | Check out the CA.pl(1) manual page. This provides a simple wrapper round | |
301 | the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check | |
302 | out the manual pages for the individual utilities and the certificate | |
597dab0f | 303 | extensions documentation (in ca(1), req(1), x509v3_config(5) ) |
0ae485dc RL |
304 | |
305 | ||
306 | * Why can't I create certificate requests? | |
307 | ||
308 | You typically get the error: | |
309 | ||
310 | unable to find 'distinguished_name' in config | |
311 | problems making Certificate Request | |
312 | ||
313 | This is because it can't find the configuration file. Check out the | |
314 | DIAGNOSTICS section of req(1) for more information. | |
315 | ||
316 | ||
317 | * Why does <SSL program> fail with a certificate verify error? | |
318 | ||
319 | This problem is usually indicated by log messages saying something like | |
320 | "unable to get local issuer certificate" or "self signed certificate". | |
321 | When a certificate is verified its root CA must be "trusted" by OpenSSL | |
322 | this typically means that the CA certificate must be placed in a directory | |
323 | or file and the relevant program configured to read it. The OpenSSL program | |
324 | 'verify' behaves in a similar way and issues similar error messages: check | |
325 | the verify(1) program manual page for more information. | |
326 | ||
327 | ||
328 | * Why can I only use weak ciphers when I connect to a server using OpenSSL? | |
329 | ||
330 | This is almost certainly because you are using an old "export grade" browser | |
331 | which only supports weak encryption. Upgrade your browser to support 128 bit | |
332 | ciphers. | |
333 | ||
334 | ||
335 | * How can I create DSA certificates? | |
336 | ||
337 | Check the CA.pl(1) manual page for a DSA certificate example. | |
338 | ||
339 | ||
340 | * Why can't I make an SSL connection to a server using a DSA certificate? | |
341 | ||
342 | Typically you'll see a message saying there are no shared ciphers when | |
343 | the same setup works fine with an RSA certificate. There are two possible | |
344 | causes. The client may not support connections to DSA servers most web | |
345 | browsers (including Netscape and MSIE) only support connections to servers | |
346 | supporting RSA cipher suites. The other cause is that a set of DH parameters | |
347 | has not been supplied to the server. DH parameters can be created with the | |
348 | dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: | |
349 | check the source to s_server in apps/s_server.c for an example. | |
350 | ||
351 | ||
352 | * How can I remove the passphrase on a private key? | |
353 | ||
354 | Firstly you should be really *really* sure you want to do this. Leaving | |
355 | a private key unencrypted is a major security risk. If you decide that | |
356 | you do have to do this check the EXAMPLES sections of the rsa(1) and | |
357 | dsa(1) manual pages. | |
358 | ||
359 | ||
1a7b2d33 DSH |
360 | * Why can't I use OpenSSL certificates with SSL client authentication? |
361 | ||
362 | What will typically happen is that when a server requests authentication | |
363 | it will either not include your certificate or tell you that you have | |
364 | no client certificates (Netscape) or present you with an empty list box | |
365 | (MSIE). The reason for this is that when a server requests a client | |
366 | certificate it includes a list of CAs names which it will accept. Browsers | |
367 | will only let you select certificates from the list on the grounds that | |
368 | there is little point presenting a certificate which the server will | |
369 | reject. | |
370 | ||
371 | The solution is to add the relevant CA certificate to your servers "trusted | |
e3fefbfd | 372 | CA list". How you do this depends on the server software in uses. You can |
1a7b2d33 DSH |
373 | print out the servers list of acceptable CAs using the OpenSSL s_client tool: |
374 | ||
375 | openssl s_client -connect www.some.host:443 -prexit | |
376 | ||
959f67d6 | 377 | If your server only requests certificates on certain URLs then you may need |
1a7b2d33 DSH |
378 | to manually issue an HTTP GET command to get the list when s_client connects: |
379 | ||
380 | GET /some/page/needing/a/certificate.html | |
381 | ||
382 | If your CA does not appear in the list then this confirms the problem. | |
383 | ||
384 | ||
385 | * Why does my browser give a warning about a mismatched hostname? | |
386 | ||
387 | Browsers expect the server's hostname to match the value in the commonName | |
388 | (CN) field of the certificate. If it does not then you get a warning. | |
389 | ||
390 | ||
0b33bc6b DSH |
391 | * How do I install a CA certificate into a browser? |
392 | ||
393 | The usual way is to send the DER encoded certificate to the browser as | |
394 | MIME type application/x-x509-ca-cert, for example by clicking on an appropriate | |
395 | link. On MSIE certain extensions such as .der or .cacert may also work, or you | |
396 | can import the certificate using the certificate import wizard. | |
397 | ||
398 | You can convert a certificate to DER form using the command: | |
399 | ||
400 | openssl x509 -in ca.pem -outform DER -out ca.der | |
401 | ||
402 | Occasionally someone suggests using a command such as: | |
403 | ||
404 | openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem | |
405 | ||
406 | DO NOT DO THIS! This command will give away your CAs private key and | |
407 | reduces its security to zero: allowing anyone to forge certificates in | |
408 | whatever name they choose. | |
409 | ||
17e2c77a LJ |
410 | * Why is OpenSSL x509 DN output not conformant to RFC2253? |
411 | ||
412 | The ways to print out the oneline format of the DN (Distinguished Name) have | |
413 | been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex() | |
414 | interface, the "-nameopt" option could be introduded. See the manual | |
76b10e13 | 415 | page of the "openssl x509" command line tool for details. The old behaviour |
17e2c77a | 416 | has however been left as default for the sake of compatibility. |
0b33bc6b | 417 | |
09b6c2ef DSH |
418 | * What is a "128 bit certificate"? Can I create one with OpenSSL? |
419 | ||
420 | The term "128 bit certificate" is a highly misleading marketing term. It does | |
421 | *not* refer to the size of the public key in the certificate! A certificate | |
422 | containing a 128 bit RSA key would have negligible security. | |
423 | ||
424 | There were various other names such as "magic certificates", "SGC | |
425 | certificates", "step up certificates" etc. | |
426 | ||
427 | You can't generally create such a certificate using OpenSSL but there is no | |
428 | need to any more. Nowadays web browsers using unrestricted strong encryption | |
429 | are generally available. | |
430 | ||
f7a3296d | 431 | When there were tight restrictions on the export of strong encryption |
09b6c2ef DSH |
432 | software from the US only weak encryption algorithms could be freely exported |
433 | (initially 40 bit and then 56 bit). It was widely recognised that this was | |
f7a3296d | 434 | inadequate. A relaxation of the rules allowed the use of strong encryption but |
09b6c2ef DSH |
435 | only to an authorised server. |
436 | ||
76b10e13 | 437 | Two slightly different techniques were developed to support this, one used by |
09b6c2ef DSH |
438 | Netscape was called "step up", the other used by MSIE was called "Server Gated |
439 | Cryptography" (SGC). When a browser initially connected to a server it would | |
440 | check to see if the certificate contained certain extensions and was issued by | |
441 | an authorised authority. If these test succeeded it would reconnect using | |
442 | strong encryption. | |
443 | ||
444 | Only certain (initially one) certificate authorities could issue the | |
445 | certificates and they generally cost more than ordinary certificates. | |
446 | ||
447 | Although OpenSSL can create certificates containing the appropriate extensions | |
448 | the certificate would not come from a permitted authority and so would not | |
449 | be recognized. | |
450 | ||
451 | The export laws were later changed to allow almost unrestricted use of strong | |
452 | encryption so these certificates are now obsolete. | |
453 | ||
454 | ||
1c17d91c | 455 | * Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? |
a070f0da DSH |
456 | |
457 | It doesn't: this extension is often the cause of confusion. | |
458 | ||
246e0931 | 459 | Consider a certificate chain A->B->C so that A signs B and B signs C. Suppose |
a070f0da DSH |
460 | certificate C contains AKID. |
461 | ||
462 | The purpose of this extension is to identify the authority certificate B. This | |
463 | can be done either by including the subject key identifier of B or its issuer | |
464 | name and serial number. | |
465 | ||
466 | In this latter case because it is identifying certifcate B it must contain the | |
467 | issuer name and serial number of B. | |
468 | ||
1c17d91c | 469 | It is often wrongly assumed that it should contain the subject name of B. If it |
a070f0da DSH |
470 | did this would be redundant information because it would duplicate the issuer |
471 | name of C. | |
472 | ||
473 | ||
d18ef847 LJ |
474 | * How can I set up a bundle of commercial root CA certificates? |
475 | ||
476 | The OpenSSL software is shipped without any root CA certificate as the | |
477 | OpenSSL project does not have any policy on including or excluding | |
478 | any specific CA and does not intend to set up such a policy. Deciding | |
479 | about which CAs to support is up to application developers or | |
480 | administrators. | |
481 | ||
482 | Other projects do have other policies so you can for example extract the CA | |
483 | bundle used by Mozilla and/or modssl as described in this article: | |
484 | ||
1676bec9 | 485 | <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html> |
d18ef847 LJ |
486 | |
487 | ||
5ef24a80 DSH |
488 | * Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug? |
489 | ||
490 | OpenSSL 1.0.1 is the first release to support TLS 1.2, among other things, | |
491 | this increases the size of the default ClientHello message to more than | |
492 | 255 bytes in length. Some software cannot handle this and hangs. For more | |
493 | details and workarounds see: | |
494 | ||
495 | <URL: http://rt.openssl.org/Ticket/Display.html?user=guest&pass=guest&id=2771> | |
496 | ||
497 | ||
0ae485dc RL |
498 | [BUILD] ======================================================================= |
499 | ||
49976df5 UM |
500 | * Why does the linker complain about undefined symbols? |
501 | ||
cacbb51e | 502 | Maybe the compilation was interrupted, and make doesn't notice that |
49976df5 UM |
503 | something is missing. Run "make clean; make". |
504 | ||
505 | If you used ./Configure instead of ./config, make sure that you | |
506 | selected the right target. File formats may differ slightly between | |
507 | OS versions (for example sparcv8/sparcv9, or a.out/elf). | |
508 | ||
0816bc22 UM |
509 | In case you get errors about the following symbols, use the config |
510 | option "no-asm", as described in INSTALL: | |
511 | ||
512 | BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, | |
513 | CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, | |
514 | RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, | |
515 | bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, | |
516 | bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, | |
517 | des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, | |
518 | des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order | |
519 | ||
569be071 | 520 | If none of these helps, you may want to try using the current snapshot. |
49976df5 UM |
521 | If the problem persists, please submit a bug report. |
522 | ||
523 | ||
0ae485dc | 524 | * Why does the OpenSSL test fail with "bc: command not found"? |
2b670ea2 | 525 | |
0ae485dc RL |
526 | You didn't install "bc", the Unix calculator. If you want to run the |
527 | tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. | |
2b670ea2 | 528 | |
2b670ea2 | 529 | |
a6ed5dd6 | 530 | * Why does the OpenSSL test fail with "bc: 1 no implemented"? |
0ae485dc | 531 | |
1417f2dc RL |
532 | On some SCO installations or versions, bc has a bug that gets triggered |
533 | when you run the test suite (using "make test"). The message returned is | |
a6ed5dd6 | 534 | "bc: 1 not implemented". |
1417f2dc RL |
535 | |
536 | The best way to deal with this is to find another implementation of bc | |
1676bec9 | 537 | and compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> |
1417f2dc | 538 | for download instructions) can be safely used, for example. |
f742e497 RL |
539 | |
540 | ||
541 | * Why does the OpenSSL test fail with "bc: stack empty"? | |
542 | ||
543 | On some DG/ux versions, bc seems to have a too small stack for calculations | |
544 | that the OpenSSL bntest throws at it. This gets triggered when you run the | |
545 | test suite (using "make test"). The message returned is "bc: stack empty". | |
546 | ||
547 | The best way to deal with this is to find another implementation of bc | |
1676bec9 | 548 | and compile/install it. GNU bc (see <URL: http://www.gnu.org/software/software.html> |
f742e497 | 549 | for download instructions) can be safely used, for example. |
0ae485dc RL |
550 | |
551 | ||
6bc847e4 | 552 | * Why does the OpenSSL compilation fail on Alpha Tru64 Unix? |
0ae485dc | 553 | |
6bc847e4 | 554 | On some Alpha installations running Tru64 Unix and Compaq C, the compilation |
0ae485dc RL |
555 | of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual |
556 | memory to continue compilation.' As far as the tests have shown, this may be | |
557 | a compiler bug. What happens is that it eats up a lot of resident memory | |
558 | to build something, probably a table. The problem is clearly in the | |
559 | optimization code, because if one eliminates optimization completely (-O0), | |
560 | the compilation goes through (and the compiler consumes about 2MB of resident | |
561 | memory instead of 240MB or whatever one's limit is currently). | |
562 | ||
563 | There are three options to solve this problem: | |
564 | ||
565 | 1. set your current data segment size soft limit higher. Experience shows | |
566 | that about 241000 kbytes seems to be enough on an AlphaServer DS10. You do | |
567 | this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of | |
568 | kbytes to set the limit to. | |
569 | ||
570 | 2. If you have a hard limit that is lower than what you need and you can't | |
571 | get it changed, you can compile all of OpenSSL with -O0 as optimization | |
572 | level. This is however not a very nice thing to do for those who expect to | |
573 | get the best result from OpenSSL. A bit more complicated solution is the | |
574 | following: | |
575 | ||
576 | ----- snip:start ----- | |
577 | make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ | |
578 | sed -e 's/ -O[0-9] / -O0 /'`" | |
579 | rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` | |
580 | make | |
581 | ----- snip:end ----- | |
582 | ||
583 | This will only compile sha_dgst.c with -O0, the rest with the optimization | |
584 | level chosen by the configuration process. When the above is done, do the | |
585 | test and installation and you're set. | |
586 | ||
d9248e57 AP |
587 | 3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It |
588 | should not be used and is not used in SSL/TLS nor any other recognized | |
589 | protocol in either case. | |
590 | ||
0ae485dc RL |
591 | |
592 | * Why does the OpenSSL compilation fail with "ar: command not found"? | |
593 | ||
594 | Getting this message is quite usual on Solaris 2, because Sun has hidden | |
595 | away 'ar' and other development commands in directories that aren't in | |
596 | $PATH by default. One of those directories is '/usr/ccs/bin'. The | |
597 | quickest way to fix this is to do the following (it assumes you use sh | |
598 | or any sh-compatible shell): | |
599 | ||
600 | ----- snip:start ----- | |
601 | PATH=${PATH}:/usr/ccs/bin; export PATH | |
602 | ----- snip:end ----- | |
603 | ||
604 | and then redo the compilation. What you should really do is make sure | |
605 | '/usr/ccs/bin' is permanently in your $PATH, for example through your | |
606 | '.profile' (again, assuming you use a sh-compatible shell). | |
607 | ||
608 | ||
609 | * Why does the OpenSSL compilation fail on Win32 with VC++? | |
610 | ||
611 | Sometimes, you may get reports from VC++ command line (cl) that it | |
612 | can't find standard include files like stdio.h and other weirdnesses. | |
613 | One possible cause is that the environment isn't correctly set up. | |
3d6a84c4 RL |
614 | To solve that problem for VC++ versions up to 6, one should run |
615 | VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ | |
616 | installation directory (somewhere under 'Program Files'). For VC++ | |
617 | version 7 (and up?), which is also called VS.NET, the file is called | |
618 | VSVARS32.BAT instead. | |
619 | This needs to be done prior to running NMAKE, and the changes are only | |
620 | valid for the current DOS session. | |
0ae485dc RL |
621 | |
622 | ||
c4da6dd3 LJ |
623 | * What is special about OpenSSL on Redhat? |
624 | ||
876811e2 | 625 | Red Hat Linux (release 7.0 and later) include a preinstalled limited |
372566bd SM |
626 | version of OpenSSL. Red Hat has chosen to disable support for IDEA, RC5 and |
627 | MDC2 in this version. The same may apply to other Linux distributions. | |
876811e2 | 628 | Users may therefore wish to install more or all of the features left out. |
c4da6dd3 LJ |
629 | |
630 | To do this you MUST ensure that you do not overwrite the openssl that is in | |
631 | /usr/bin on your Red Hat machine. Several packages depend on this file, | |
632 | including sendmail and ssh. /usr/local/bin is a good alternative choice. The | |
633 | libraries that come with Red Hat 7.0 onwards have different names and so are | |
634 | not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and | |
635 | /lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and | |
636 | /lib/libcrypto.so.2 respectively). | |
637 | ||
638 | Please note that we have been advised by Red Hat attempting to recompile the | |
639 | openssl rpm with all the cryptography enabled will not work. All other | |
640 | packages depend on the original Red Hat supplied openssl package. It is also | |
641 | worth noting that due to the way Red Hat supplies its packages, updates to | |
642 | openssl on each distribution never change the package version, only the | |
643 | build number. For example, on Red Hat 7.1, the latest openssl package has | |
644 | version number 0.9.6 and build number 9 even though it contains all the | |
645 | relevant updates in packages up to and including 0.9.6b. | |
646 | ||
647 | A possible way around this is to persuade Red Hat to produce a non-US | |
648 | version of Red Hat Linux. | |
649 | ||
311e2099 RL |
650 | |
651 | * Why does the OpenSSL compilation fail on MacOS X? | |
652 | ||
653 | If the failure happens when trying to build the "openssl" binary, with | |
654 | a large number of undefined symbols, it's very probable that you have | |
655 | OpenSSL 0.9.6b delivered with the operating system (you can find out by | |
656 | running '/usr/bin/openssl version') and that you were trying to build | |
657 | OpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in | |
658 | MacOS X has a misfeature that's quite difficult to go around. | |
659 | Look in the file PROBLEMS for a more detailed explanation and for possible | |
660 | solutions. | |
661 | ||
662 | ||
663 | * Why does the OpenSSL test suite fail on MacOS X? | |
664 | ||
665 | If the failure happens when running 'make test' and the RC4 test fails, | |
666 | it's very probable that you have OpenSSL 0.9.6b delivered with the | |
667 | operating system (you can find out by running '/usr/bin/openssl version') | |
668 | and that you were trying to build OpenSSL 0.9.6d. The problem is that | |
669 | the loader ('ld') in MacOS X has a misfeature that's quite difficult to | |
670 | go around and has linked the programs "openssl" and the test programs | |
671 | with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the | |
672 | libraries you just built. | |
673 | Look in the file PROBLEMS for a more detailed explanation and for possible | |
674 | solutions. | |
675 | ||
26a60b2e | 676 | * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? |
e0b2073f AP |
677 | |
678 | Failure in BN_sqr test is most likely caused by a failure to configure the | |
26a60b2e AP |
679 | toolkit for current platform or lack of support for the platform in question. |
680 | Run './config -t' and './apps/openssl version -p'. Do these platform | |
681 | identifiers match? If they don't, then you most likely failed to run | |
682 | ./config and you're hereby advised to do so before filing a bug report. | |
683 | If ./config itself fails to run, then it's most likely problem with your | |
684 | local environment and you should turn to your system administrator (or | |
76a03d56 AP |
685 | similar). If identifiers match (and/or no alternative identifier is |
686 | suggested by ./config script), then the platform is unsupported. There might | |
687 | or might not be a workaround. Most notably on SPARC64 platforms with GNU | |
688 | C compiler you should be able to produce a working build by running | |
689 | './config -m32'. I understand that -m32 might not be what you want/need, | |
85f258d1 AP |
690 | but the build should be operational. For further details turn to |
691 | <openssl-dev@openssl.org>. | |
692 | ||
75c40285 | 693 | * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? |
85f258d1 | 694 | |
75c40285 AP |
695 | As of 0.9.7 assembler routines were overhauled for position independence |
696 | of the machine code, which is essential for shared library support. For | |
697 | some reason OpenBSD is equipped with an out-of-date GNU assembler which | |
698 | finds the new code offensive. To work around the problem, configure with | |
0382c95e AP |
699 | no-asm (and sacrifice a great deal of performance) or patch your assembler |
700 | according to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. | |
75c40285 | 701 | For your convenience a pre-compiled replacement binary is provided at |
1a6356b2 AP |
702 | <URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. |
703 | Reportedly elder *BSD a.out platforms also suffer from this problem and | |
704 | remedy should be same. Provided binary is statically linked and should be | |
705 | working across wider range of *BSD branches, not just OpenBSD. | |
e0b2073f | 706 | |
851e31ff AP |
707 | * Why does the OpenSSL test suite fail in sha512t on x86 CPU? |
708 | ||
709 | If the test program in question fails withs SIGILL, Illegal Instruction | |
710 | exception, then you more than likely to run SSE2-capable CPU, such as | |
711 | Intel P4, under control of kernel which does not support SSE2 | |
478b50cf | 712 | instruction extensions. See accompanying INSTALL file and |
851e31ff AP |
713 | OPENSSL_ia32cap(3) documentation page for further information. |
714 | ||
4b559868 AP |
715 | * Why does compiler fail to compile sha512.c? |
716 | ||
717 | OpenSSL SHA-512 implementation depends on compiler support for 64-bit | |
718 | integer type. Few elder compilers [ULTRIX cc, SCO compiler to mention a | |
719 | couple] lack support for this and therefore are incapable of compiling | |
720 | the module in question. The recommendation is to disable SHA-512 by | |
721 | adding no-sha512 to ./config [or ./Configure] command line. Another | |
722 | possible alternative might be to switch to GCC. | |
723 | ||
65613f23 AP |
724 | * Test suite still fails, what to do? |
725 | ||
76b10e13 JW |
726 | Another common reason for test failures is bugs in the toolchain |
727 | or run-time environment. Known cases of this are documented in the | |
728 | PROBLEMS file, please review it before you beat the drum. Even if you | |
729 | don't find anything in that file, please do consider the possibility | |
730 | of a compiler bug. Compiler bugs often appear in rather bizarre ways, | |
731 | they never make sense, and tend to emerge when you least expect | |
732 | them. One thing to try is to reduce the level of optimization (such | |
733 | as by editing the CFLAG variable line in the top-level Makefile), | |
734 | and then recompile and re-run the test. | |
5fad2c93 | 735 | |
c25a0aae DSH |
736 | * I think I've found a bug, what should I do? |
737 | ||
738 | If you are a new user then it is quite likely you haven't found a bug and | |
739 | something is happening you aren't familiar with. Check this FAQ, the associated | |
740 | documentation and the mailing lists for similar queries. If you are still | |
741 | unsure whether it is a bug or not submit a query to the openssl-users mailing | |
742 | list. | |
743 | ||
5fad2c93 DSH |
744 | If you think you have found a bug based on the output of static analysis tools |
745 | then please manually check the issue is genuine. Such tools can produce a | |
746 | LOT of false positives. | |
747 | ||
748 | ||
c25a0aae DSH |
749 | * I'm SURE I've found a bug, how do I report it? |
750 | ||
e0261441 DSH |
751 | To avoid duplicated reports check the mailing lists and release notes for the |
752 | relevant version of OpenSSL to see if the problem has been reported already. | |
753 | ||
c25a0aae | 754 | Bug reports with no security implications should be sent to the request |
c17171c6 | 755 | tracker. This can be done by mailing the report to <rt@openssl.org> (or its |
1676bec9 DSH |
756 | alias <openssl-bugs@openssl.org>), please note that messages sent to the |
757 | request tracker also appear in the public openssl-dev mailing list. | |
c25a0aae DSH |
758 | |
759 | The report should be in plain text. Any patches should be sent as | |
760 | plain text attachments because some mailers corrupt patches sent inline. | |
1676bec9 | 761 | If your issue affects multiple versions of OpenSSL check any patches apply |
c25a0aae DSH |
762 | cleanly and, if possible include patches to each affected version. |
763 | ||
764 | The report should be given a meaningful subject line briefly summarising the | |
765 | issue. Just "bug in OpenSSL" or "bug in OpenSSL 0.9.8n" is not very helpful. | |
766 | ||
767 | By sending reports to the request tracker the bug can then be given a priority | |
768 | and assigned to the appropriate maintainer. The history of discussions can be | |
769 | accessed and if the issue has been addressed or a reason why not. If patches | |
1676bec9 | 770 | are only sent to openssl-dev they can be mislaid if a team member has to |
c25a0aae DSH |
771 | wade through months of old messages to review the discussion. |
772 | ||
1676bec9 | 773 | See also <URL: http://www.openssl.org/support/rt.html> |
c25a0aae | 774 | |
4b0771c1 | 775 | |
c25a0aae DSH |
776 | * I've found a security issue, how do I report it? |
777 | ||
778 | If you think your bug has security implications then please send it to | |
779 | openssl-security@openssl.org if you don't get a prompt reply at least | |
780 | acknowledging receipt then resend or mail it directly to one of the | |
9b69a638 DSH |
781 | more active team members (e.g. Steve). If you wish to use PGP to send |
782 | in a report please use one or more of the keys of the team members listed | |
783 | at <URL: http://www.openssl.org/about/> | |
c25a0aae | 784 | |
6cc00684 DSH |
785 | Note that bugs only present in the openssl utility are not in general |
786 | considered to be security issues. | |
787 | ||
0ae485dc RL |
788 | [PROG] ======================================================================== |
789 | ||
790 | * Is OpenSSL thread-safe? | |
791 | ||
a28ef860 RS |
792 | Provided an application sets up the thread callback functions, the |
793 | answer is yes. There are limitations; for example, an SSL connection | |
794 | cannot be used concurrently by multiple threads. This is true for | |
795 | most OpenSSL objects. | |
796 | ||
797 | To do this, your application must call CRYPTO_set_locking_callback() | |
798 | and one of the CRYPTO_THREADID_set...() API's. See the OpenSSL threads | |
799 | manpage for details and "note on multi-threading" in the INSTALL file in | |
800 | the source distribution. | |
afee764c | 801 | |
46e80a30 DSH |
802 | * I've compiled a program under Windows and it crashes: why? |
803 | ||
a542db90 RL |
804 | This is usually because you've missed the comment in INSTALL.W32. |
805 | Your application must link against the same version of the Win32 | |
806 | C-Runtime against which your openssl libraries were linked. The | |
807 | default version for OpenSSL is /MD - "Multithreaded DLL". | |
808 | ||
809 | If you are using Microsoft Visual C++'s IDE (Visual Studio), in | |
810 | many cases, your new project most likely defaulted to "Debug | |
811 | Singlethreaded" - /ML. This is NOT interchangeable with /MD and your | |
812 | program will crash, typically on the first BIO related read or write | |
813 | operation. | |
814 | ||
815 | For each of the six possible link stage configurations within Win32, | |
816 | your application must link against the same by which OpenSSL was | |
817 | built. If you are using MS Visual C++ (Studio) this can be changed | |
818 | by: | |
819 | ||
65613f23 AP |
820 | 1. Select Settings... from the Project Menu. |
821 | 2. Select the C/C++ Tab. | |
822 | 3. Select "Code Generation from the "Category" drop down list box | |
823 | 4. Select the Appropriate library (see table below) from the "Use | |
a542db90 RL |
824 | run-time library" drop down list box. Perform this step for both |
825 | your debug and release versions of your application (look at the | |
826 | top left of the settings panel to change between the two) | |
827 | ||
828 | Single Threaded /ML - MS VC++ often defaults to | |
829 | this for the release | |
830 | version of a new project. | |
831 | Debug Single Threaded /MLd - MS VC++ often defaults to | |
832 | this for the debug version | |
833 | of a new project. | |
834 | Multithreaded /MT | |
835 | Debug Multithreaded /MTd | |
836 | Multithreaded DLL /MD - OpenSSL defaults to this. | |
837 | Debug Multithreaded DLL /MDd | |
838 | ||
839 | Note that debug and release libraries are NOT interchangeable. If you | |
840 | built OpenSSL with /MD your application must use /MD and cannot use /MDd. | |
46e80a30 | 841 | |
788e67e2 | 842 | As per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL |
2c730f6f | 843 | .DLLs compiled with some specific run-time option [we insist on the |
788e67e2 AP |
844 | default /MD] can be deployed with application compiled with different |
845 | option or even different compiler. But there is a catch! Instead of | |
846 | re-compiling OpenSSL toolkit, as you would have to with prior versions, | |
847 | you have to compile small C snippet with compiler and/or options of | |
848 | your choice. The snippet gets installed as | |
849 | <install-root>/include/openssl/applink.c and should be either added to | |
2c730f6f AP |
850 | your application project or simply #include-d in one [and only one] |
851 | of your application source files. Failure to link this shim module | |
852 | into your application manifests itself as fatal "no OPENSSL_Applink" | |
853 | run-time error. An explicit reminder is due that in this situation | |
854 | [mixing compiler options] it is as important to add CRYPTO_malloc_init | |
855 | prior first call to OpenSSL. | |
46e80a30 | 856 | |
c5a3b7e7 DSH |
857 | * How do I read or write a DER encoded buffer using the ASN1 functions? |
858 | ||
859 | You have two options. You can either use a memory BIO in conjunction | |
ec7c9ee8 DSH |
860 | with the i2d_*_bio() or d2i_*_bio() functions or you can use the |
861 | i2d_*(), d2i_*() functions directly. Since these are often the | |
c5a3b7e7 DSH |
862 | cause of grief here are some code fragments using PKCS7 as an example: |
863 | ||
ec7c9ee8 DSH |
864 | unsigned char *buf, *p; |
865 | int len; | |
c5a3b7e7 | 866 | |
ec7c9ee8 DSH |
867 | len = i2d_PKCS7(p7, NULL); |
868 | buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */ | |
869 | p = buf; | |
870 | i2d_PKCS7(p7, &p); | |
c5a3b7e7 DSH |
871 | |
872 | At this point buf contains the len bytes of the DER encoding of | |
873 | p7. | |
874 | ||
875 | The opposite assumes we already have len bytes in buf: | |
876 | ||
ec7c9ee8 DSH |
877 | unsigned char *p; |
878 | p = buf; | |
879 | p7 = d2i_PKCS7(NULL, &p, len); | |
c5a3b7e7 | 880 | |
2527b94f | 881 | At this point p7 contains a valid PKCS7 structure or NULL if an error |
c5a3b7e7 DSH |
882 | occurred. If an error occurred ERR_print_errors(bio) should give more |
883 | information. | |
884 | ||
885 | The reason for the temporary variable 'p' is that the ASN1 functions | |
886 | increment the passed pointer so it is ready to read or write the next | |
887 | structure. This is often a cause of problems: without the temporary | |
888 | variable the buffer pointer is changed to point just after the data | |
889 | that has been read or written. This may well be uninitialized data | |
890 | and attempts to free the buffer will have unpredictable results | |
891 | because it no longer points to the same address. | |
892 | ||
2527b94f DSH |
893 | Memory allocation and encoding can also be combined in a single |
894 | operation by the ASN1 routines: | |
895 | ||
896 | unsigned char *buf = NULL; /* mandatory */ | |
897 | int len; | |
898 | len = i2d_PKCS7(p7, &buf); | |
899 | if (len < 0) | |
900 | /* Error */ | |
901 | /* Do some things with 'buf' */ | |
902 | /* Finished with buf: free it */ | |
903 | OPENSSL_free(buf); | |
904 | ||
905 | In this special case the "buf" parameter is *not* incremented, it points | |
906 | to the start of the encoding. | |
907 | ||
c5a3b7e7 | 908 | |
6ef7b78e DSH |
909 | * OpenSSL uses DER but I need BER format: does OpenSSL support BER? |
910 | ||
911 | The short answer is yes, because DER is a special case of BER and OpenSSL | |
912 | ASN1 decoders can process BER. | |
913 | ||
914 | The longer answer is that ASN1 structures can be encoded in a number of | |
915 | different ways. One set of ways is the Basic Encoding Rules (BER) with various | |
916 | permissible encodings. A restriction of BER is the Distinguished Encoding | |
917 | Rules (DER): these uniquely specify how a given structure is encoded. | |
918 | ||
919 | Therefore, because DER is a special case of BER, DER is an acceptable encoding | |
920 | for BER. | |
921 | ||
922 | ||
84b65340 DSH |
923 | * I've tried using <M_some_evil_pkcs12_macro> and I get errors why? |
924 | ||
925 | This usually happens when you try compiling something using the PKCS#12 | |
926 | macros with a C++ compiler. There is hardly ever any need to use the | |
927 | PKCS#12 macros in a program, it is much easier to parse and create | |
928 | PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions | |
929 | documented in doc/openssl.txt and with examples in demos/pkcs12. The | |
930 | 'pkcs12' application has to use the macros because it prints out | |
931 | debugging information. | |
932 | ||
933 | ||
35af460f DSH |
934 | * I've called <some function> and it fails, why? |
935 | ||
02859fb7 BM |
936 | Before submitting a report or asking in one of the mailing lists, you |
937 | should try to determine the cause. In particular, you should call | |
35af460f | 938 | ERR_print_errors() or ERR_print_errors_fp() after the failed call |
02859fb7 BM |
939 | and see if the message helps. Note that the problem may occur earlier |
940 | than you think -- you should check for errors after every call where | |
941 | it is possible, otherwise the actual problem may be hidden because | |
942 | some OpenSSL functions clear the error state. | |
35af460f DSH |
943 | |
944 | ||
945 | * I just get a load of numbers for the error output, what do they mean? | |
946 | ||
947 | The actual format is described in the ERR_print_errors() manual page. | |
948 | You should call the function ERR_load_crypto_strings() before hand and | |
949 | the message will be output in text form. If you can't do this (for example | |
950 | it is a pre-compiled binary) you can use the errstr utility on the error | |
951 | code itself (the hex digits after the second colon). | |
952 | ||
953 | ||
46e80a30 DSH |
954 | * Why do I get errors about unknown algorithms? |
955 | ||
930875ef DSH |
956 | The cause is forgetting to load OpenSSL's table of algorithms with |
957 | OpenSSL_add_all_algorithms(). See the manual page for more information. This | |
958 | can cause several problems such as being unable to read in an encrypted | |
959 | PEM file, unable to decrypt a PKCS#12 file or signature failure when | |
960 | verifying certificates. | |
46e80a30 | 961 | |
e8dbc159 RL |
962 | * Why can't the OpenSSH configure script detect OpenSSL? |
963 | ||
a116afa4 LJ |
964 | Several reasons for problems with the automatic detection exist. |
965 | OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. | |
966 | Sometimes the distribution has installed an older version in the system | |
967 | locations that is detected instead of a new one installed. The OpenSSL | |
968 | library might have been compiled for another CPU or another mode (32/64 bits). | |
969 | Permissions might be wrong. | |
970 | ||
971 | The general answer is to check the config.log file generated when running | |
972 | the OpenSSH configure script. It should contain the detailed information | |
973 | on why the OpenSSL library was not detected or considered incompatible. | |
31efc3a7 | 974 | |
500df82a | 975 | |
0ae485dc | 976 | * Can I use OpenSSL's SSL library with non-blocking I/O? |
bf55ece1 | 977 | |
0ae485dc | 978 | Yes; make sure to read the SSL_get_error(3) manual page! |
bf55ece1 | 979 | |
0ae485dc RL |
980 | A pitfall to avoid: Don't assume that SSL_read() will just read from |
981 | the underlying transport or that SSL_write() will just write to it -- | |
982 | it is also possible that SSL_write() cannot do any useful work until | |
983 | there is data to read, or that SSL_read() cannot do anything until it | |
984 | is possible to send data. One reason for this is that the peer may | |
985 | request a new TLS/SSL handshake at any time during the protocol, | |
986 | requiring a bi-directional message exchange; both SSL_read() and | |
987 | SSL_write() will try to continue any pending handshake. | |
bf55ece1 | 988 | |
bf55ece1 | 989 | |
19732245 LJ |
990 | * Why doesn't my server application receive a client certificate? |
991 | ||
992 | Due to the TLS protocol definition, a client will only send a certificate, | |
e3fefbfd | 993 | if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the |
19732245 LJ |
994 | SSL_CTX_set_verify() function to enable the use of client certificates. |
995 | ||
996 | ||
e1f7ea25 LJ |
997 | * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? |
998 | ||
e8233e69 LJ |
999 | For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier |
1000 | versions, uniqueIdentifier was incorrectly used for X.509 certificates. | |
1001 | The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. | |
1002 | Change your code to use the new name when compiling against OpenSSL 0.9.7. | |
e1f7ea25 LJ |
1003 | |
1004 | ||
6ef7b78e DSH |
1005 | * I think I've detected a memory leak, is this a bug? |
1006 | ||
1007 | In most cases the cause of an apparent memory leak is an OpenSSL internal table | |
1008 | that is allocated when an application starts up. Since such tables do not grow | |
1009 | in size over time they are harmless. | |
1010 | ||
1011 | These internal tables can be freed up when an application closes using various | |
6141b86a RL |
1012 | functions. Currently these include following: |
1013 | ||
1014 | Thread-local cleanup functions: | |
1015 | ||
1016 | ERR_remove_state() | |
1017 | ||
1018 | Application-global cleanup functions that are aware of usage (and therefore | |
1019 | thread-safe): | |
1020 | ||
1021 | ENGINE_cleanup() and CONF_modules_unload() | |
1022 | ||
1023 | "Brutal" (thread-unsafe) Application-global cleanup functions: | |
1024 | ||
1025 | ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data(). | |
6ef7b78e DSH |
1026 | |
1027 | ||
7bbce697 LJ |
1028 | * Why does Valgrind complain about the use of uninitialized data? |
1029 | ||
1030 | When OpenSSL's PRNG routines are called to generate random numbers the supplied | |
1031 | buffer contents are mixed into the entropy pool: so it technically does not | |
1032 | matter whether the buffer is initialized at this point or not. Valgrind (and | |
1033 | other test tools) will complain about this. When using Valgrind, make sure the | |
1034 | OpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY) | |
1035 | to get rid of these warnings. | |
1036 | ||
1037 | ||
715020e3 DSH |
1038 | * Why doesn't a memory BIO work when a file does? |
1039 | ||
1040 | This can occur in several cases for example reading an S/MIME email message. | |
1041 | The reason is that a memory BIO can do one of two things when all the data | |
1042 | has been read from it. | |
1043 | ||
1044 | The default behaviour is to indicate that no more data is available and that | |
1045 | the call should be retried, this is to allow the application to fill up the BIO | |
1046 | again if necessary. | |
1047 | ||
1048 | Alternatively it can indicate that no more data is available and that EOF has | |
1049 | been reached. | |
1050 | ||
1051 | If a memory BIO is to behave in the same way as a file this second behaviour | |
1052 | is needed. This must be done by calling: | |
1053 | ||
1054 | BIO_set_mem_eof_return(bio, 0); | |
1055 | ||
29a1bb07 DSH |
1056 | See the manual pages for more details. |
1057 | ||
715020e3 | 1058 | |
dd57b657 DSH |
1059 | * Where are the declarations and implementations of d2i_X509() etc? |
1060 | ||
13d75246 | 1061 | These are defined and implemented by macros of the form: |
dd57b657 DSH |
1062 | |
1063 | ||
1064 | DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) | |
1065 | ||
1066 | The implementation passes an ASN1 "template" defining the structure into an | |
1067 | ASN1 interpreter using generalised functions such as ASN1_item_d2i(). | |
1068 | ||
e796666d AP |
1069 | * When debugging I observe SIGILL during OpenSSL initialization: why? |
1070 | ||
1071 | OpenSSL adapts to processor it executes on and for this reason has to | |
1072 | query its capabilities. Unfortunately on some processors the only way | |
1073 | to achieve this for non-privileged code is to attempt instructions | |
1074 | that can cause Illegal Instruction exceptions. The initialization | |
1075 | procedure is coded to handle these exceptions to manipulate corresponding | |
1076 | bits in capabilities vector. This normally appears transparent, except | |
1077 | when you execute it under debugger, which stops prior delivering signal | |
1078 | to handler. Simply resuming execution does the trick, but when debugging | |
1079 | a lot it might feel counterproductive. Two options. Either set explicit | |
1080 | capability environment variable in order to bypass the capability query | |
1081 | (see corresponding crypto/*cap.c for details). Or configure debugger not | |
1082 | to stop upon SIGILL exception, e.g. in gdb case add 'handle SIGILL nostop' | |
1083 | to your .gdbinit. | |
dd57b657 | 1084 | |
0ae485dc | 1085 | =============================================================================== |