318 lines
13 KiB
Text
318 lines
13 KiB
Text
OpenSSL - Frequently Asked Questions
|
|
--------------------------------------
|
|
|
|
* Which is the current version of OpenSSL?
|
|
* Where is the documentation?
|
|
* How can I contact the OpenSSL developers?
|
|
* Do I need patent licenses to use OpenSSL?
|
|
* Is OpenSSL thread-safe?
|
|
* Why do I get a "PRNG not seeded" error message?
|
|
* Why does the linker complain about undefined symbols?
|
|
* Where can I get a compiled version of OpenSSL?
|
|
* I've compiled a program under Windows and it crashes: 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?
|
|
* 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 the OpenSSH configure script detect OpenSSL?
|
|
* Why does the OpenSSL test fail with "bc: 1 no implemented"?
|
|
|
|
|
|
* Which is the current version of OpenSSL?
|
|
|
|
The current version is available from <URL: http://www.openssl.org>.
|
|
OpenSSL 0.9.5a was released on April 1st, 2000.
|
|
|
|
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>.
|
|
|
|
|
|
* 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
|
|
|
|
Until the RSA patent expires, U.S. users may want to use
|
|
./config no-rc5 no-idea no-rsa
|
|
|
|
Please note that you will *not* be able to communicate with most of
|
|
the popular web browsers without RSA support.
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
* 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.
|
|
|
|
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, it is a good idea to use the Entropy
|
|
Gathering Demon; see the RAND_egd() manpage for details.
|
|
|
|
Most components of the openssl command line tool try to use the
|
|
file $HOME/.rnd (or $RANDFILE, if this environment variable is set)
|
|
for seeding the PRNG. If this file does not exist or is too short,
|
|
the "PRNG not seeded" error message may occur.
|
|
|
|
[Note to OpenSSL 0.9.5 users: The command "openssl rsa" in version
|
|
0.9.5 does not do this and will fail on systems without /dev/urandom
|
|
when trying to password-encrypt an RSA key! This is a bug in the
|
|
library; try a later version instead.]
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
* I've compiled a program under Windows and it crashes: why?
|
|
|
|
This is usually because you've missed the comment in INSTALL.W32. You
|
|
must link with the multithreaded DLL version of the VC++ runtime library
|
|
otherwise the conflict will cause a program to crash: typically on the
|
|
first BIO related read or write operation.
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
* 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 the OpenSSH configure script detect OpenSSL?
|
|
|
|
There is a problem with OpenSSH 1.2.2p1, in that the configure script
|
|
can't find the installed OpenSSL libraries. The problem is actually
|
|
a small glitch that is easily solved with the following patch to be
|
|
applied to the OpenSSH distribution:
|
|
|
|
----- snip:start -----
|
|
--- openssh-1.2.2p1/configure.in.orig Thu Mar 23 18:56:58 2000
|
|
+++ openssh-1.2.2p1/configure.in Thu Mar 23 18:55:05 2000
|
|
@@ -152,10 +152,10 @@
|
|
AC_MSG_CHECKING([for OpenSSL/SSLeay directory])
|
|
for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do
|
|
if test ! -z "$ssldir" ; then
|
|
- LIBS="$saved_LIBS -L$ssldir"
|
|
+ LIBS="$saved_LIBS -L$ssldir/lib"
|
|
CFLAGS="$CFLAGS -I$ssldir/include"
|
|
if test "x$need_dash_r" = "x1" ; then
|
|
- LIBS="$LIBS -R$ssldir"
|
|
+ LIBS="$LIBS -R$ssldir/lib"
|
|
fi
|
|
fi
|
|
LIBS="$LIBS -lcrypto"
|
|
--- openssh-1.2.2p1/configure.orig Thu Mar 23 18:55:02 2000
|
|
+++ openssh-1.2.2p1/configure Thu Mar 23 18:57:08 2000
|
|
@@ -1890,10 +1890,10 @@
|
|
echo "configure:1891: checking for OpenSSL/SSLeay directory" >&5
|
|
for ssldir in "" $tryssldir /usr /usr/local/openssl /usr/lib/openssl /usr/local/ssl /usr/lib/ssl /usr/local /usr/pkg /opt /opt/openssl ; do
|
|
if test ! -z "$ssldir" ; then
|
|
- LIBS="$saved_LIBS -L$ssldir"
|
|
+ LIBS="$saved_LIBS -L$ssldir/lib"
|
|
CFLAGS="$CFLAGS -I$ssldir/include"
|
|
if test "x$need_dash_r" = "x1" ; then
|
|
- LIBS="$LIBS -R$ssldir"
|
|
+ LIBS="$LIBS -R$ssldir/lib"
|
|
fi
|
|
fi
|
|
LIBS="$LIBS -lcrypto"
|
|
----- snip:end -----
|
|
|
|
|
|
* 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. For example, GNU bc (see
|
|
http://www.gnu.org/software/software.html for download instructions) can
|
|
be safely used.
|