More secure storage of key material.
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index d42f60b..2579d51 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -76,6 +76,7 @@ OpenSSL  -  Frequently Asked Questions
 * Why does Valgrind complain about the use of uninitialized data?
 * Why doesn't a memory BIO work when a file does?
 * Where are the declarations and implementations of d2i_X509() etc?
+* When debugging I observe SIGILL during OpenSSL initialization: why?
 
 ===============================================================================
 
@@ -84,7 +85,6 @@ OpenSSL  -  Frequently Asked Questions
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 1.0.1e was released on Feb 11, 2013.
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
@@ -114,11 +114,6 @@ that came with the version of OpenSSL you are using. The pod format
 documentation is included in each OpenSSL distribution under the docs
 directory.
 
-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
 
@@ -138,7 +133,7 @@ OpenSSL.  Information on the OpenSSL mailing lists is available from
 * Where can I get a compiled version of OpenSSL?
 
 You can finder pointers to binary distributions in
-<URL: http://www.openssl.org/related/binaries.html> .
+<URL: http://www.openssl.org/about/binaries.html> .
 
 Some applications that use OpenSSL are distributed in binary form.
 When using such an application, you don't need to install OpenSSL
@@ -417,7 +412,7 @@ whatever name they choose.
 The ways to print out the oneline format of the DN (Distinguished Name) have
 been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex()
 interface, the "-nameopt" option could be introduded. See the manual
-page of the "openssl x509" commandline tool for details. The old behaviour
+page of the "openssl x509" command line tool for details. The old behaviour
 has however been left as default for the sake of compatibility.
 
 * What is a "128 bit certificate"? Can I create one with OpenSSL?
@@ -439,7 +434,7 @@ software from the US only weak encryption algorithms could be freely exported
 inadequate. A relaxation of the rules allowed the use of strong encryption but
 only to an authorised server.
 
-Two slighly different techniques were developed to support this, one used by
+Two slightly different techniques were developed to support this, one used by
 Netscape was called "step up", the other used by MSIE was called "Server Gated
 Cryptography" (SGC). When a browser initially connected to a server it would
 check to see if the certificate contained certain extensions and was issued by
@@ -728,15 +723,15 @@ possible alternative might be to switch to GCC.
 
 * Test suite still fails, what to do?
 
-Another common reason for failure to complete some particular test is
-simply bad code generated by a buggy component in toolchain or deficiency
-in run-time environment. There are few cases documented in PROBLEMS file,
-consult it for possible workaround before you beat the drum. Even if you
-don't find solution or even mention there, do reserve for possibility of
-a compiler bug. Compiler bugs might appear in rather bizarre ways, they
-never make sense, and tend to emerge when you least expect them. In order
-to identify one, drop optimization level, e.g. by editing CFLAG line in
-top-level Makefile, recompile and re-run the test.
+Another common reason for test failures is bugs in the toolchain
+or run-time environment.  Known cases of this are documented in the
+PROBLEMS file, please review it before you beat the drum. Even if you
+don't find anything in that file, please do consider the possibility
+of a compiler bug. Compiler bugs often appear in rather bizarre ways,
+they never make sense, and tend to emerge when you least expect
+them. One thing to try is to reduce the level of optimization (such
+as by editing the CFLAG variable line in the top-level Makefile),
+and then recompile and re-run the test.
 
 * I think I've found a bug, what should I do?
 
@@ -746,9 +741,16 @@ documentation and the mailing lists for similar queries. If you are still
 unsure whether it is a bug or not submit a query to the openssl-users mailing
 list.
 
+If you think you have found a bug based on the output of static analysis tools
+then please manually check the issue is genuine. Such tools can produce a
+LOT of false positives.
+
 
 * I'm SURE I've found a bug, how do I report it?
 
+To avoid duplicated reports check the mailing lists and release notes for the
+relevant version of OpenSSL to see if the problem has been reported already.
+
 Bug reports with no security implications should be sent to the request
 tracker. This can be done by mailing the report to <rt@openssl.org> (or its
 alias <openssl-bugs@openssl.org>), please note that messages sent to the
@@ -776,24 +778,26 @@ See also <URL: http://www.openssl.org/support/rt.html>
 If you think your bug has security implications then please send it to
 openssl-security@openssl.org if you don't get a prompt reply at least 
 acknowledging receipt then resend or mail it directly to one of the
-more active team members (e.g. Steve).
+more active team members (e.g. Steve). If you wish to use PGP to send
+in a report please use one or more of the keys of the team members listed
+at <URL: http://www.openssl.org/about/>
+
+Note that bugs only present in the openssl utility are not in general
+considered to be security issues. 
 
 [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.
+Provided an application sets up the thread callback functions, the
+answer is yes. There are limitations; for example, an SSL connection
+cannot be used concurrently by multiple threads.  This is true for
+most OpenSSL objects.
 
-Multi-threaded applications must provide two callback functions to
-OpenSSL by calling CRYPTO_set_locking_callback() and
-CRYPTO_set_id_callback(), for all versions of OpenSSL up to and
-including 0.9.8[abc...]. As of version 1.0.0, CRYPTO_set_id_callback()
-and associated APIs are deprecated by CRYPTO_THREADID_set_callback()
-and friends. This is described in the threads(3) manpage.
+To do this, your application must call CRYPTO_set_locking_callback()
+and one of the CRYPTO_THREADID_set...() API's.  See the OpenSSL threads
+manpage for details and "note on multi-threading" in the INSTALL file in
+the source distribution.
 
 * I've compiled a program under Windows and it crashes: why?
 
@@ -1062,5 +1066,20 @@ These are defined and implemented by macros of the form:
 The implementation passes an ASN1 "template" defining the structure into an
 ASN1 interpreter using generalised functions such as ASN1_item_d2i().
 
+* When debugging I observe SIGILL during OpenSSL initialization: why?
+
+OpenSSL adapts to processor it executes on and for this reason has to
+query its capabilities. Unfortunately on some processors the only way
+to achieve this for non-privileged code is to attempt instructions
+that can cause Illegal Instruction exceptions. The initialization
+procedure is coded to handle these exceptions to manipulate corresponding
+bits in capabilities vector. This normally appears transparent, except
+when you execute it under debugger, which stops prior delivering signal
+to handler. Simply resuming execution does the trick, but when debugging
+a lot it might feel counterproductive. Two options. Either set explicit
+capability environment variable in order to bypass the capability query
+(see corresponding crypto/*cap.c for details). Or configure debugger not
+to stop upon SIGILL exception, e.g. in gdb case add 'handle SIGILL nostop'
+to your .gdbinit.
 
 ===============================================================================