672 lines
28 KiB
Plaintext
672 lines
28 KiB
Plaintext
OpenSSL - Frequently Asked Questions
|
|
--------------------------------------
|
|
|
|
[MISC] Miscellaneous questions
|
|
|
|
* Which is the current version of OpenSSL?
|
|
* Where is the documentation?
|
|
* How can I contact the OpenSSL developers?
|
|
* Where can I get a compiled version of OpenSSL?
|
|
* Why aren't tools like 'autoconf' and 'libtool' used?
|
|
* What is an 'engine' version?
|
|
|
|
[LEGAL] Legal questions
|
|
|
|
* Do I need patent licenses to use OpenSSL?
|
|
* Can I use OpenSSL with GPL software?
|
|
|
|
[USER] Questions on using the OpenSSL applications
|
|
|
|
* Why do I get a "PRNG not seeded" error message?
|
|
* Why do I get an "unable to write 'random state'" error message?
|
|
* How do I create certificates or certificate requests?
|
|
* Why can't I create certificate requests?
|
|
* Why does <SSL program> fail with a certificate verify error?
|
|
* Why can I only use weak ciphers when I connect to a server using OpenSSL?
|
|
* How can I create DSA certificates?
|
|
* Why can't I make an SSL connection using a DSA certificate?
|
|
* How can I remove the passphrase on a private key?
|
|
* Why can't I use OpenSSL certificates with SSL client authentication?
|
|
* Why does my browser give a warning about a mismatched hostname?
|
|
* How do I install a CA certificate into a browser?
|
|
|
|
[BUILD] Questions about building and testing OpenSSL
|
|
|
|
* Why does the linker complain about undefined symbols?
|
|
* Why does the OpenSSL test fail with "bc: command not found"?
|
|
* Why does the OpenSSL test fail with "bc: 1 no implemented"?
|
|
* Why does the OpenSSL compilation fail on Alpha Tru64 Unix?
|
|
* Why does the OpenSSL compilation fail with "ar: command not found"?
|
|
* Why does the OpenSSL compilation fail on Win32 with VC++?
|
|
* What is special about OpenSSL on Redhat?
|
|
* Why does the OpenSSL test suite fail on MacOS X?
|
|
|
|
[PROG] Questions about programming with OpenSSL
|
|
|
|
* Is OpenSSL thread-safe?
|
|
* I've compiled a program under Windows and it crashes: why?
|
|
* How do I read or write a DER encoded buffer using the ASN1 functions?
|
|
* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
|
|
* I've called <some function> and it fails, why?
|
|
* I just get a load of numbers for the error output, what do they mean?
|
|
* Why do I get errors about unknown algorithms?
|
|
* Why can't the OpenSSH configure script detect OpenSSL?
|
|
* Can I use OpenSSL's SSL library with non-blocking I/O?
|
|
* Why doesn't my server application receive a client certificate?
|
|
|
|
===============================================================================
|
|
|
|
[MISC] ========================================================================
|
|
|
|
* Which is the current version of OpenSSL?
|
|
|
|
The current version is available from <URL: http://www.openssl.org>.
|
|
OpenSSL 0.9.6e was released on 30 May, 2002.
|
|
|
|
In addition to the current stable release, you can also access daily
|
|
snapshots of the OpenSSL development version at <URL:
|
|
ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access.
|
|
|
|
|
|
* Where is the documentation?
|
|
|
|
OpenSSL is a library that provides cryptographic functionality to
|
|
applications such as secure web servers. Be sure to read the
|
|
documentation of the application you want to use. The INSTALL file
|
|
explains how to install this library.
|
|
|
|
OpenSSL includes a command line utility that can be used to perform a
|
|
variety of cryptographic functions. It is described in the openssl(1)
|
|
manpage. Documentation for developers is currently being written. A
|
|
few manual pages already are available; overviews over libcrypto and
|
|
libssl are given in the crypto(3) and ssl(3) manpages.
|
|
|
|
The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a
|
|
different directory if you specified one as described in INSTALL).
|
|
In addition, you can read the most current versions at
|
|
<URL: http://www.openssl.org/docs/>.
|
|
|
|
For information on parts of libcrypto that are not yet documented, you
|
|
might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's
|
|
predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>. Much
|
|
of this still applies to OpenSSL.
|
|
|
|
There is some documentation about certificate extensions and PKCS#12
|
|
in doc/openssl.txt
|
|
|
|
The original SSLeay documentation is included in OpenSSL as
|
|
doc/ssleay.txt. It may be useful when none of the other resources
|
|
help, but please note that it reflects the obsolete version SSLeay
|
|
0.6.6.
|
|
|
|
|
|
* How can I contact the OpenSSL developers?
|
|
|
|
The README file describes how to submit bug reports and patches to
|
|
OpenSSL. Information on the OpenSSL mailing lists is available from
|
|
<URL: http://www.openssl.org>.
|
|
|
|
|
|
* Where can I get a compiled version of OpenSSL?
|
|
|
|
Some applications that use OpenSSL are distributed in binary form.
|
|
When using such an application, you don't need to install OpenSSL
|
|
yourself; the application will include the required parts (e.g. DLLs).
|
|
|
|
If you want to install OpenSSL on a Windows system and you don't have
|
|
a C compiler, read the "Mingw32" section of INSTALL.W32 for information
|
|
on how to obtain and install the free GNU C compiler.
|
|
|
|
A number of Linux and *BSD distributions include OpenSSL.
|
|
|
|
|
|
* Why aren't tools like 'autoconf' and 'libtool' used?
|
|
|
|
autoconf will probably be used in future OpenSSL versions. If it was
|
|
less Unix-centric, it might have been used much earlier.
|
|
|
|
* What is an 'engine' version?
|
|
|
|
With version 0.9.6 OpenSSL was extended to interface to external crypto
|
|
hardware. This was realized in a special release '0.9.6-engine'. With
|
|
version 0.9.7 (not yet released) the changes were merged into the main
|
|
development line, so that the special release is no longer necessary.
|
|
|
|
[LEGAL] =======================================================================
|
|
|
|
* Do I need patent licenses to use OpenSSL?
|
|
|
|
The patents section of the README file lists patents that may apply to
|
|
you if you want to use OpenSSL. For information on intellectual
|
|
property rights, please consult a lawyer. The OpenSSL team does not
|
|
offer legal advice.
|
|
|
|
You can configure OpenSSL so as not to use RC5 and IDEA by using
|
|
./config no-rc5 no-idea
|
|
|
|
|
|
* Can I use OpenSSL with GPL software?
|
|
|
|
On many systems including the major Linux and BSD distributions, yes (the
|
|
GPL does not place restrictions on using libraries that are part of the
|
|
normal operating system distribution).
|
|
|
|
On other systems, the situation is less clear. Some GPL software copyright
|
|
holders claim that you infringe on their rights if you use OpenSSL with
|
|
their software on operating systems that don't normally include OpenSSL.
|
|
|
|
If you develop open source software that uses OpenSSL, you may find it
|
|
useful to choose an other license than the GPL, or state explicitly that
|
|
"This program is released under the GPL with the additional exemption that
|
|
compiling, linking, and/or using OpenSSL is allowed." If you are using
|
|
GPL software developed by others, you may want to ask the copyright holder
|
|
for permission to use their software with OpenSSL.
|
|
|
|
|
|
[USER] ========================================================================
|
|
|
|
* Why do I get a "PRNG not seeded" error message?
|
|
|
|
Cryptographic software needs a source of unpredictable data to work
|
|
correctly. Many open source operating systems provide a "randomness
|
|
device" that serves this purpose. On other systems, applications have
|
|
to call the RAND_add() or RAND_seed() function with appropriate data
|
|
before generating keys or performing public key encryption.
|
|
(These functions initialize the pseudo-random number generator, PRNG.)
|
|
|
|
Some broken applications do not do this. As of version 0.9.5, the
|
|
OpenSSL functions that need randomness report an error if the random
|
|
number generator has not been seeded with at least 128 bits of
|
|
randomness. If this error occurs, please contact the author of the
|
|
application you are using. It is likely that it never worked
|
|
correctly. OpenSSL 0.9.5 and later make the error visible by refusing
|
|
to perform potentially insecure encryption.
|
|
|
|
On systems without /dev/urandom and /dev/random, it is a good idea to
|
|
use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for
|
|
details. Starting with version 0.9.7, OpenSSL will automatically look
|
|
for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and
|
|
/etc/entropy.
|
|
|
|
Most components of the openssl command line utility automatically try
|
|
to seed the random number generator from a file. The name of the
|
|
default seeding file is determined as follows: If environment variable
|
|
RANDFILE is set, then it names the seeding file. Otherwise if
|
|
environment variable HOME is set, then the seeding file is $HOME/.rnd.
|
|
If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will
|
|
use file .rnd in the current directory while OpenSSL 0.9.6a uses no
|
|
default seeding file at all. OpenSSL 0.9.6b and later will behave
|
|
similarly to 0.9.6a, but will use a default of "C:\" for HOME on
|
|
Windows systems if the environment variable has not been set.
|
|
|
|
If the default seeding file does not exist or is too short, the "PRNG
|
|
not seeded" error message may occur.
|
|
|
|
The openssl command line utility will write back a new state to the
|
|
default seeding file (and create this file if necessary) unless
|
|
there was no sufficient seeding.
|
|
|
|
Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work.
|
|
Use the "-rand" option of the OpenSSL command line tools instead.
|
|
The $RANDFILE environment variable and $HOME/.rnd are only used by the
|
|
OpenSSL command line tools. Applications using the OpenSSL library
|
|
provide their own configuration options to specify the entropy source,
|
|
please check out the documentation coming the with application.
|
|
|
|
For Solaris 2.6, Tim Nibbe <tnibbe@sprint.net> and others have suggested
|
|
installing the SUNski package from Sun patch 105710-01 (Sparc) which
|
|
adds a /dev/random device and make sure it gets used, usually through
|
|
$RANDFILE. There are probably similar patches for the other Solaris
|
|
versions. An official statement from Sun with respect to /dev/random
|
|
support can be found at
|
|
http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski
|
|
However, be warned that /dev/random is usually a blocking device, which
|
|
may have some effects on OpenSSL.
|
|
|
|
|
|
* Why do I get an "unable to write 'random state'" error message?
|
|
|
|
|
|
Sometimes the openssl command line utility does not abort with
|
|
a "PRNG not seeded" error message, but complains that it is
|
|
"unable to write 'random state'". This message refers to the
|
|
default seeding file (see previous answer). A possible reason
|
|
is that no default filename is known because neither RANDFILE
|
|
nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the
|
|
current directory in this case, but this has changed with 0.9.6a.)
|
|
|
|
|
|
* How do I create certificates or certificate requests?
|
|
|
|
Check out the CA.pl(1) manual page. This provides a simple wrapper round
|
|
the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
|
|
out the manual pages for the individual utilities and the certificate
|
|
extensions documentation (currently in doc/openssl.txt).
|
|
|
|
|
|
* Why can't I create certificate requests?
|
|
|
|
You typically get the error:
|
|
|
|
unable to find 'distinguished_name' in config
|
|
problems making Certificate Request
|
|
|
|
This is because it can't find the configuration file. Check out the
|
|
DIAGNOSTICS section of req(1) for more information.
|
|
|
|
|
|
* Why does <SSL program> fail with a certificate verify error?
|
|
|
|
This problem is usually indicated by log messages saying something like
|
|
"unable to get local issuer certificate" or "self signed certificate".
|
|
When a certificate is verified its root CA must be "trusted" by OpenSSL
|
|
this typically means that the CA certificate must be placed in a directory
|
|
or file and the relevant program configured to read it. The OpenSSL program
|
|
'verify' behaves in a similar way and issues similar error messages: check
|
|
the verify(1) program manual page for more information.
|
|
|
|
|
|
* Why can I only use weak ciphers when I connect to a server using OpenSSL?
|
|
|
|
This is almost certainly because you are using an old "export grade" browser
|
|
which only supports weak encryption. Upgrade your browser to support 128 bit
|
|
ciphers.
|
|
|
|
|
|
* How can I create DSA certificates?
|
|
|
|
Check the CA.pl(1) manual page for a DSA certificate example.
|
|
|
|
|
|
* Why can't I make an SSL connection to a server using a DSA certificate?
|
|
|
|
Typically you'll see a message saying there are no shared ciphers when
|
|
the same setup works fine with an RSA certificate. There are two possible
|
|
causes. The client may not support connections to DSA servers most web
|
|
browsers (including Netscape and MSIE) only support connections to servers
|
|
supporting RSA cipher suites. The other cause is that a set of DH parameters
|
|
has not been supplied to the server. DH parameters can be created with the
|
|
dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example:
|
|
check the source to s_server in apps/s_server.c for an example.
|
|
|
|
|
|
* How can I remove the passphrase on a private key?
|
|
|
|
Firstly you should be really *really* sure you want to do this. Leaving
|
|
a private key unencrypted is a major security risk. If you decide that
|
|
you do have to do this check the EXAMPLES sections of the rsa(1) and
|
|
dsa(1) manual pages.
|
|
|
|
|
|
* Why can't I use OpenSSL certificates with SSL client authentication?
|
|
|
|
What will typically happen is that when a server requests authentication
|
|
it will either not include your certificate or tell you that you have
|
|
no client certificates (Netscape) or present you with an empty list box
|
|
(MSIE). The reason for this is that when a server requests a client
|
|
certificate it includes a list of CAs names which it will accept. Browsers
|
|
will only let you select certificates from the list on the grounds that
|
|
there is little point presenting a certificate which the server will
|
|
reject.
|
|
|
|
The solution is to add the relevant CA certificate to your servers "trusted
|
|
CA list". How you do this depends on the server software in uses. You can
|
|
print out the servers list of acceptable CAs using the OpenSSL s_client tool:
|
|
|
|
openssl s_client -connect www.some.host:443 -prexit
|
|
|
|
If your server only requests certificates on certain URLs then you may need
|
|
to manually issue an HTTP GET command to get the list when s_client connects:
|
|
|
|
GET /some/page/needing/a/certificate.html
|
|
|
|
If your CA does not appear in the list then this confirms the problem.
|
|
|
|
|
|
* Why does my browser give a warning about a mismatched hostname?
|
|
|
|
Browsers expect the server's hostname to match the value in the commonName
|
|
(CN) field of the certificate. If it does not then you get a warning.
|
|
|
|
|
|
* How do I install a CA certificate into a browser?
|
|
|
|
The usual way is to send the DER encoded certificate to the browser as
|
|
MIME type application/x-x509-ca-cert, for example by clicking on an appropriate
|
|
link. On MSIE certain extensions such as .der or .cacert may also work, or you
|
|
can import the certificate using the certificate import wizard.
|
|
|
|
You can convert a certificate to DER form using the command:
|
|
|
|
openssl x509 -in ca.pem -outform DER -out ca.der
|
|
|
|
Occasionally someone suggests using a command such as:
|
|
|
|
openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem
|
|
|
|
DO NOT DO THIS! This command will give away your CAs private key and
|
|
reduces its security to zero: allowing anyone to forge certificates in
|
|
whatever name they choose.
|
|
|
|
|
|
[BUILD] =======================================================================
|
|
|
|
* Why does the linker complain about undefined symbols?
|
|
|
|
Maybe the compilation was interrupted, and make doesn't notice that
|
|
something is missing. Run "make clean; make".
|
|
|
|
If you used ./Configure instead of ./config, make sure that you
|
|
selected the right target. File formats may differ slightly between
|
|
OS versions (for example sparcv8/sparcv9, or a.out/elf).
|
|
|
|
In case you get errors about the following symbols, use the config
|
|
option "no-asm", as described in INSTALL:
|
|
|
|
BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt,
|
|
CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt,
|
|
RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words,
|
|
bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4,
|
|
bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3,
|
|
des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3,
|
|
des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order
|
|
|
|
If none of these helps, you may want to try using the current snapshot.
|
|
If the problem persists, please submit a bug report.
|
|
|
|
|
|
* Why does the OpenSSL test fail with "bc: command not found"?
|
|
|
|
You didn't install "bc", the Unix calculator. If you want to run the
|
|
tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor.
|
|
|
|
|
|
* Why does the OpenSSL test fail with "bc: 1 no implemented"?
|
|
|
|
On some SCO installations or versions, bc has a bug that gets triggered
|
|
when you run the test suite (using "make test"). The message returned is
|
|
"bc: 1 not implemented".
|
|
|
|
The best way to deal with this is to find another implementation of bc
|
|
and compile/install it. GNU bc (see http://www.gnu.org/software/software.html
|
|
for download instructions) can be safely used, for example.
|
|
|
|
|
|
* Why does the OpenSSL compilation fail on Alpha Tru64 Unix?
|
|
|
|
On some Alpha installations running Tru64 Unix and Compaq C, the compilation
|
|
of crypto/sha/sha_dgst.c fails with the message 'Fatal: Insufficient virtual
|
|
memory to continue compilation.' As far as the tests have shown, this may be
|
|
a compiler bug. What happens is that it eats up a lot of resident memory
|
|
to build something, probably a table. The problem is clearly in the
|
|
optimization code, because if one eliminates optimization completely (-O0),
|
|
the compilation goes through (and the compiler consumes about 2MB of resident
|
|
memory instead of 240MB or whatever one's limit is currently).
|
|
|
|
There are three options to solve this problem:
|
|
|
|
1. set your current data segment size soft limit higher. Experience shows
|
|
that about 241000 kbytes seems to be enough on an AlphaServer DS10. You do
|
|
this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
|
|
kbytes to set the limit to.
|
|
|
|
2. If you have a hard limit that is lower than what you need and you can't
|
|
get it changed, you can compile all of OpenSSL with -O0 as optimization
|
|
level. This is however not a very nice thing to do for those who expect to
|
|
get the best result from OpenSSL. A bit more complicated solution is the
|
|
following:
|
|
|
|
----- snip:start -----
|
|
make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
|
|
sed -e 's/ -O[0-9] / -O0 /'`"
|
|
rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'`
|
|
make
|
|
----- snip:end -----
|
|
|
|
This will only compile sha_dgst.c with -O0, the rest with the optimization
|
|
level chosen by the configuration process. When the above is done, do the
|
|
test and installation and you're set.
|
|
|
|
|
|
* Why does the OpenSSL compilation fail with "ar: command not found"?
|
|
|
|
Getting this message is quite usual on Solaris 2, because Sun has hidden
|
|
away 'ar' and other development commands in directories that aren't in
|
|
$PATH by default. One of those directories is '/usr/ccs/bin'. The
|
|
quickest way to fix this is to do the following (it assumes you use sh
|
|
or any sh-compatible shell):
|
|
|
|
----- snip:start -----
|
|
PATH=${PATH}:/usr/ccs/bin; export PATH
|
|
----- snip:end -----
|
|
|
|
and then redo the compilation. What you should really do is make sure
|
|
'/usr/ccs/bin' is permanently in your $PATH, for example through your
|
|
'.profile' (again, assuming you use a sh-compatible shell).
|
|
|
|
|
|
* Why does the OpenSSL compilation fail on Win32 with VC++?
|
|
|
|
Sometimes, you may get reports from VC++ command line (cl) that it
|
|
can't find standard include files like stdio.h and other weirdnesses.
|
|
One possible cause is that the environment isn't correctly set up.
|
|
To solve that problem, one should run VCVARS32.BAT which is found in
|
|
the 'bin' subdirectory of the VC++ installation directory (somewhere
|
|
under 'Program Files'). This needs to be done prior to running NMAKE,
|
|
and the changes are only valid for the current DOS session.
|
|
|
|
|
|
* What is special about OpenSSL on Redhat?
|
|
|
|
Red Hat Linux (release 7.0 and later) include a preinstalled limited
|
|
version of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2
|
|
is disabled in this version. The same may apply to other Linux distributions.
|
|
Users may therefore wish to install more or all of the features left out.
|
|
|
|
To do this you MUST ensure that you do not overwrite the openssl that is in
|
|
/usr/bin on your Red Hat machine. Several packages depend on this file,
|
|
including sendmail and ssh. /usr/local/bin is a good alternative choice. The
|
|
libraries that come with Red Hat 7.0 onwards have different names and so are
|
|
not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and
|
|
/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and
|
|
/lib/libcrypto.so.2 respectively).
|
|
|
|
Please note that we have been advised by Red Hat attempting to recompile the
|
|
openssl rpm with all the cryptography enabled will not work. All other
|
|
packages depend on the original Red Hat supplied openssl package. It is also
|
|
worth noting that due to the way Red Hat supplies its packages, updates to
|
|
openssl on each distribution never change the package version, only the
|
|
build number. For example, on Red Hat 7.1, the latest openssl package has
|
|
version number 0.9.6 and build number 9 even though it contains all the
|
|
relevant updates in packages up to and including 0.9.6b.
|
|
|
|
A possible way around this is to persuade Red Hat to produce a non-US
|
|
version of Red Hat Linux.
|
|
|
|
FYI: Patent numbers and expiry dates of US patents:
|
|
MDC-2: 4,908,861 13/03/2007
|
|
IDEA: 5,214,703 25/05/2010
|
|
RC5: 5,724,428 03/03/2015
|
|
|
|
|
|
* Why does the OpenSSL test suite fail on MacOS X?
|
|
|
|
If the failure happens when running 'make test' and the RC4 test fails,
|
|
it's very probable that you have OpenSSL 0.9.6b delivered with the
|
|
operating system (you can find out by running '/usr/bin/openssl version')
|
|
and that you were trying to build OpenSSL 0.9.6d. The problem is that
|
|
the loader ('ld') in MacOS X has a misfeature that's quite difficult to
|
|
go around and has linked the programs "openssl" and the test programs
|
|
with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the
|
|
libraries you just built.
|
|
Look in the file PROBLEMS for a more detailed explanation and for possible
|
|
solutions.
|
|
|
|
[PROG] ========================================================================
|
|
|
|
* Is OpenSSL thread-safe?
|
|
|
|
Yes (with limitations: an SSL connection may not concurrently be used
|
|
by multiple threads). On Windows and many Unix systems, OpenSSL
|
|
automatically uses the multi-threaded versions of the standard
|
|
libraries. If your platform is not one of these, consult the INSTALL
|
|
file.
|
|
|
|
Multi-threaded applications must provide two callback functions to
|
|
OpenSSL. This is described in the threads(3) manpage.
|
|
|
|
|
|
* I've compiled a program under Windows and it crashes: why?
|
|
|
|
This is usually because you've missed the comment in INSTALL.W32.
|
|
Your application must link against the same version of the Win32
|
|
C-Runtime against which your openssl libraries were linked. The
|
|
default version for OpenSSL is /MD - "Multithreaded DLL".
|
|
|
|
If you are using Microsoft Visual C++'s IDE (Visual Studio), in
|
|
many cases, your new project most likely defaulted to "Debug
|
|
Singlethreaded" - /ML. This is NOT interchangeable with /MD and your
|
|
program will crash, typically on the first BIO related read or write
|
|
operation.
|
|
|
|
For each of the six possible link stage configurations within Win32,
|
|
your application must link against the same by which OpenSSL was
|
|
built. If you are using MS Visual C++ (Studio) this can be changed
|
|
by:
|
|
|
|
1. Select Settings... from the Project Menu.
|
|
2. Select the C/C++ Tab.
|
|
3. Select "Code Generation from the "Category" drop down list box
|
|
4. Select the Appropriate library (see table below) from the "Use
|
|
run-time library" drop down list box. Perform this step for both
|
|
your debug and release versions of your application (look at the
|
|
top left of the settings panel to change between the two)
|
|
|
|
Single Threaded /ML - MS VC++ often defaults to
|
|
this for the release
|
|
version of a new project.
|
|
Debug Single Threaded /MLd - MS VC++ often defaults to
|
|
this for the debug version
|
|
of a new project.
|
|
Multithreaded /MT
|
|
Debug Multithreaded /MTd
|
|
Multithreaded DLL /MD - OpenSSL defaults to this.
|
|
Debug Multithreaded DLL /MDd
|
|
|
|
Note that debug and release libraries are NOT interchangeable. If you
|
|
built OpenSSL with /MD your application must use /MD and cannot use /MDd.
|
|
|
|
|
|
* How do I read or write a DER encoded buffer using the ASN1 functions?
|
|
|
|
You have two options. You can either use a memory BIO in conjunction
|
|
with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the
|
|
i2d_XXX(), d2i_XXX() functions directly. Since these are often the
|
|
cause of grief here are some code fragments using PKCS7 as an example:
|
|
|
|
unsigned char *buf, *p;
|
|
int len;
|
|
|
|
len = i2d_PKCS7(p7, NULL);
|
|
buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
|
|
p = buf;
|
|
i2d_PKCS7(p7, &p);
|
|
|
|
At this point buf contains the len bytes of the DER encoding of
|
|
p7.
|
|
|
|
The opposite assumes we already have len bytes in buf:
|
|
|
|
unsigned char *p;
|
|
p = buf;
|
|
p7 = d2i_PKCS7(NULL, &p, len);
|
|
|
|
At this point p7 contains a valid PKCS7 structure of NULL if an error
|
|
occurred. If an error occurred ERR_print_errors(bio) should give more
|
|
information.
|
|
|
|
The reason for the temporary variable 'p' is that the ASN1 functions
|
|
increment the passed pointer so it is ready to read or write the next
|
|
structure. This is often a cause of problems: without the temporary
|
|
variable the buffer pointer is changed to point just after the data
|
|
that has been read or written. This may well be uninitialized data
|
|
and attempts to free the buffer will have unpredictable results
|
|
because it no longer points to the same address.
|
|
|
|
|
|
* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
|
|
|
|
This usually happens when you try compiling something using the PKCS#12
|
|
macros with a C++ compiler. There is hardly ever any need to use the
|
|
PKCS#12 macros in a program, it is much easier to parse and create
|
|
PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions
|
|
documented in doc/openssl.txt and with examples in demos/pkcs12. The
|
|
'pkcs12' application has to use the macros because it prints out
|
|
debugging information.
|
|
|
|
|
|
* I've called <some function> and it fails, why?
|
|
|
|
Before submitting a report or asking in one of the mailing lists, you
|
|
should try to determine the cause. In particular, you should call
|
|
ERR_print_errors() or ERR_print_errors_fp() after the failed call
|
|
and see if the message helps. Note that the problem may occur earlier
|
|
than you think -- you should check for errors after every call where
|
|
it is possible, otherwise the actual problem may be hidden because
|
|
some OpenSSL functions clear the error state.
|
|
|
|
|
|
* I just get a load of numbers for the error output, what do they mean?
|
|
|
|
The actual format is described in the ERR_print_errors() manual page.
|
|
You should call the function ERR_load_crypto_strings() before hand and
|
|
the message will be output in text form. If you can't do this (for example
|
|
it is a pre-compiled binary) you can use the errstr utility on the error
|
|
code itself (the hex digits after the second colon).
|
|
|
|
|
|
* Why do I get errors about unknown algorithms?
|
|
|
|
This can happen under several circumstances such as reading in an
|
|
encrypted private key or attempting to decrypt a PKCS#12 file. The cause
|
|
is forgetting to load OpenSSL's table of algorithms with
|
|
OpenSSL_add_all_algorithms(). See the manual page for more information.
|
|
|
|
|
|
* Why can't the OpenSSH configure script detect OpenSSL?
|
|
|
|
Several reasons for problems with the automatic detection exist.
|
|
OpenSSH requires at least version 0.9.5a of the OpenSSL libraries.
|
|
Sometimes the distribution has installed an older version in the system
|
|
locations that is detected instead of a new one installed. The OpenSSL
|
|
library might have been compiled for another CPU or another mode (32/64 bits).
|
|
Permissions might be wrong.
|
|
|
|
The general answer is to check the config.log file generated when running
|
|
the OpenSSH configure script. It should contain the detailed information
|
|
on why the OpenSSL library was not detected or considered incompatible.
|
|
|
|
* Can I use OpenSSL's SSL library with non-blocking I/O?
|
|
|
|
Yes; make sure to read the SSL_get_error(3) manual page!
|
|
|
|
A pitfall to avoid: Don't assume that SSL_read() will just read from
|
|
the underlying transport or that SSL_write() will just write to it --
|
|
it is also possible that SSL_write() cannot do any useful work until
|
|
there is data to read, or that SSL_read() cannot do anything until it
|
|
is possible to send data. One reason for this is that the peer may
|
|
request a new TLS/SSL handshake at any time during the protocol,
|
|
requiring a bi-directional message exchange; both SSL_read() and
|
|
SSL_write() will try to continue any pending handshake.
|
|
|
|
|
|
* Why doesn't my server application receive a client certificate?
|
|
|
|
Due to the TLS protocol definition, a client will only send a certificate,
|
|
if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the
|
|
SSL_CTX_set_verify() function to enable the use of client certificates.
|
|
|
|
|
|
===============================================================================
|
|
|