update NEWS
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index c01365d..550a998 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -35,6 +35,7 @@ OpenSSL  -  Frequently Asked Questions
 * What is a "128 bit certificate"? Can I create one with OpenSSL?
 * Why does OpenSSL set the authority key identifier extension incorrectly?
 * How can I set up a bundle of commercial root CA certificates?
+* Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug?
 
 [BUILD] Questions about building and testing OpenSSL
 
@@ -75,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?
 
 ===============================================================================
 
@@ -83,7 +85,7 @@ 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.1c was released on May 10, 2012.
+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:
@@ -189,14 +191,18 @@ Therefore the answer to the common question "when will feature X be
 backported to OpenSSL 1.0.0/0.9.8?" is "never" but it could appear
 in the next minor release.
 
+* What happens when the letter release reaches z?
+
+It was decided after the release of OpenSSL 0.9.8y the next version should
+be 0.9.8za then 0.9.8zb and so on.
+
+
 [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.
+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 IDEA, MDC2 and RC5 by using
  ./config no-idea no-mdc2 no-rc5
@@ -485,6 +491,16 @@ bundle used by Mozilla and/or modssl as described in this article:
   <URL: http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html>
 
 
+* Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug?
+
+OpenSSL 1.0.1 is the first release to support TLS 1.2, among other things,
+this increases the size of the default ClientHello message to more than
+255 bytes in length. Some software cannot handle this and hangs. For more
+details and workarounds see:
+
+  <URL: http://rt.openssl.org/Ticket/Display.html?user=guest&pass=guest&id=2771>
+
+
 [BUILD] =======================================================================
 
 * Why does the linker complain about undefined symbols?
@@ -613,8 +629,8 @@ 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.
+version of OpenSSL. Red Hat has chosen to disable support for IDEA, RC5 and
+MDC2 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
@@ -637,11 +653,6 @@ 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?
 
@@ -704,7 +715,7 @@ working across wider range of *BSD branches, not just OpenBSD.
 If the test program in question fails withs SIGILL, Illegal Instruction
 exception, then you more than likely to run SSE2-capable CPU, such as
 Intel P4, under control of kernel which does not support SSE2
-instruction extentions. See accompanying INSTALL file and
+instruction extensions. See accompanying INSTALL file and
 OPENSSL_ia32cap(3) documentation page for further information.
 
 * Why does compiler fail to compile sha512.c?
@@ -728,6 +739,7 @@ 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.
 
+
 * I think I've found a bug, what should I do?
 
 If you are a new user then it is quite likely you haven't found a bug and
@@ -736,6 +748,10 @@ 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?
 
@@ -766,7 +782,9 @@ 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/>
 
 [PROG] ========================================================================
 
@@ -864,7 +882,7 @@ The opposite assumes we already have len bytes in buf:
  p = buf;
  p7 = d2i_PKCS7(NULL, &p, len);
 
-At this point p7 contains a valid PKCS7 structure of NULL if an error
+At this point p7 contains a valid PKCS7 structure or NULL if an error
 occurred. If an error occurred ERR_print_errors(bio) should give more
 information.
 
@@ -876,6 +894,21 @@ 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.
 
+Memory allocation and encoding can also be combined in a single
+operation by the ASN1 routines:
+
+ unsigned char *buf = NULL;    /* mandatory */
+ int len;
+ len = i2d_PKCS7(p7, &buf);
+ if (len < 0)
+       /* Error */
+ /* Do some things with 'buf' */
+ /* Finished with buf: free it */
+ OPENSSL_free(buf);
+
+In this special case the "buf" parameter is *not* incremented, it points
+to the start of the encoding.
+
 
 * OpenSSL uses DER but I need BER format: does OpenSSL support BER?
 
@@ -1037,5 +1070,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.
 
 ===============================================================================