Make sure we get the definition of OPENSSL_NO_FP_API.
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index bea8fcf..1b129bc 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -9,6 +9,7 @@ OpenSSL  -  Frequently Asked Questions
 * Where can I get a compiled version of OpenSSL?
 * Why aren't tools like 'autoconf' and 'libtool' used?
 * What is an 'engine' version?
+* How do I check the authenticity of the OpenSSL distribution?
 
 [LEGAL] Legal questions
 
@@ -36,9 +37,15 @@ OpenSSL  -  Frequently Asked Questions
 * 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 test fail with "bc: stack empty"?
 * 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 compilation fail on MacOS X?
+* Why does the OpenSSL test suite fail on MacOS X?
+* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]?
+* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
 
 [PROG] Questions about programming with OpenSSL
 
@@ -52,6 +59,7 @@ OpenSSL  -  Frequently Asked Questions
 * 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?
+* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier?
 
 ===============================================================================
 
@@ -60,7 +68,7 @@ OpenSSL  -  Frequently Asked Questions
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 0.9.6d was released on May 9, 2002.
+OpenSSL 0.9.7a was released on February 19, 2003.
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
@@ -131,6 +139,19 @@ 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.
 
+* How do I check the authenticity of the OpenSSL distribution?
+
+We provide MD5 digests and ASC signatures of each tarball.
+Use MD5 to check that a tarball from a mirror site is identical:
+
+   md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5
+
+You can check authenticity using pgp or gpg. You need the OpenSSL team
+member public key used to sign it (download it from a key server). Then
+just do:
+
+   pgp TARBALL.asc
+
 [LEGAL] =======================================================================
 
 * Do I need patent licenses to use OpenSSL?
@@ -168,18 +189,30 @@ for permission to use their software with OpenSSL.
 
 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.
+device" (/dev/urandom or /dev/random) that serves this purpose.
+All OpenSSL versions try to use /dev/urandom by default; starting with
+version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not
+available.
+
+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 and
+is not discussed in the documentation of the application you are
+using, please contact the author of that application; 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.
+
+If you are using Solaris 8, you can add /dev/urandom and /dev/random
+devices by installing patch 112438 (Sparc) or 112439 (x86), which are
+available via the Patchfinder at <URL: http://sunsolve.sun.com>
+(Solaris 9 includes these devices by default). For /dev/random support
+for earlier Solaris versions, see Sun's statement at
+<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski>
+(the SUNWski package is available in patch 105710).
 
 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
@@ -212,13 +245,6 @@ 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.  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?
 
@@ -395,6 +421,17 @@ 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 test fail with "bc: stack empty"?
+
+On some DG/ux versions, bc seems to have a too small stack for calculations
+that the OpenSSL bntest throws at it.  This gets triggered when you run the
+test suite (using "make test").  The message returned is "bc: stack empty".
+
+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
@@ -453,11 +490,103 @@ and then redo the compilation.  What you should really do is make sure
 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.
-
+To solve that problem for VC++ versions up to 6, one should run
+VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++
+installation directory (somewhere under 'Program Files').  For VC++
+version 7 (and up?), which is also called VS.NET, the file is called
+VSVARS32.BAT instead.
+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 compilation fail on MacOS X?
+
+If the failure happens when trying to build the "openssl" binary, with
+a large number of undefined symbols, 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.7 or newer.  The problem is that the loader ('ld') in
+MacOS X has a misfeature that's quite difficult to go around.
+Look in the file PROBLEMS for a more detailed explanation and for possible
+solutions.
+
+
+* 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.
+
+* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]?
+
+Failure in BN_sqr test is most likely caused by a failure to configure the
+toolkit for current platform or lack of support for the platform in question.
+Run './config -t' and './apps/openssl version -p'. Do these platform
+identifiers match? If they don't, then you most likely failed to run
+./config and you're hereby advised to do so before filing a bug report.
+If ./config itself fails to run, then it's most likely problem with your
+local environment and you should turn to your system administrator (or
+similar). If identifiers match (and/or no alternative identifier is
+suggested by ./config script), then the platform is unsupported. There might
+or might not be a workaround. Most notably on SPARC64 platforms with GNU
+C compiler you should be able to produce a working build by running
+'./config -m32'. I understand that -m32 might not be what you want/need,
+but the build should be operational. For further details turn to
+<openssl-dev@openssl.org>.
+
+* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
+
+As of 0.9.7 assembler routines were overhauled for position independence
+of the machine code, which is essential for shared library support. For
+some reason OpenBSD is equipped with an out-of-date GNU assembler which
+finds the new code offensive. To work around the problem, configure with
+no-asm (and sacrifice a great deal of performance) or patch your assembler
+according to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>.
+For your convenience a pre-compiled replacement binary is provided at
+<URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>.
+Reportedly elder *BSD a.out platforms also suffer from this problem and
+remedy should be same. Provided binary is statically linked and should be
+working across wider range of *BSD branches, not just OpenBSD.
 
 [PROG] ========================================================================
 
@@ -603,6 +732,7 @@ 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!
@@ -624,5 +754,13 @@ 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.
 
 
+* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier?
+
+For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier
+versions, uniqueIdentifier was incorrectly used for X.509 certificates.
+The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier.
+Change your code to use the new name when compiling against OpenSSL 0.9.7.
+
+
 ===============================================================================