Import OpenSSL 0.9.8h.
[dragonfly.git] / crypto / openssl-0.9 / FAQ
index 82d8a6f..09f700c 100644 (file)
@@ -31,6 +31,8 @@ OpenSSL  -  Frequently Asked Questions
 * Why does my browser give a warning about a mismatched hostname?
 * How do I install a CA certificate into a browser?
 * Why is OpenSSL x509 DN output not conformant to RFC2253?
 * Why does my browser give a warning about a mismatched hostname?
 * How do I install a CA certificate into a browser?
 * Why is OpenSSL x509 DN output not conformant to RFC2253?
+* What is a "128 bit certificate"? Can I create one with OpenSSL?
+* How can I set up a bundle of commercial root CA certificates?
 
 [BUILD] Questions about building and testing OpenSSL
 
 
 [BUILD] Questions about building and testing OpenSSL
 
@@ -48,6 +50,7 @@ OpenSSL  -  Frequently Asked Questions
 * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
 * Why does the OpenSSL test suite fail in sha512t on x86 CPU?
 * Why does compiler fail to compile sha512.c?
 * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
 * Why does the OpenSSL test suite fail in sha512t on x86 CPU?
 * Why does compiler fail to compile sha512.c?
+* Test suite still fails, what to do?
 
 [PROG] Questions about programming with OpenSSL
 
 
 [PROG] Questions about programming with OpenSSL
 
@@ -64,6 +67,7 @@ OpenSSL  -  Frequently Asked Questions
 * Why doesn't my server application receive a client certificate?
 * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier?
 * I think I've detected a memory leak, is this a bug?
 * Why doesn't my server application receive a client certificate?
 * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier?
 * I think I've detected a memory leak, is this a bug?
+* Why does Valgrind complain about the use of uninitialized data?
 
 ===============================================================================
 
 
 ===============================================================================
 
@@ -72,7 +76,7 @@ OpenSSL  -  Frequently Asked Questions
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 0.9.8 was released on July 5th, 2005.
+OpenSSL 0.9.8h was released on May 28th, 2008.
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
@@ -386,6 +390,57 @@ interface, the "-nameopt" option could be introduded. See the manual
 page of the "openssl x509" commandline tool for details. The old behaviour
 has however been left as default for the sake of compatibility.
 
 page of the "openssl x509" commandline 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?
+
+The term "128 bit certificate" is a highly misleading marketing term. It does
+*not* refer to the size of the public key in the certificate! A certificate
+containing a 128 bit RSA key would have negligible security.
+
+There were various other names such as "magic certificates", "SGC
+certificates", "step up certificates" etc.
+
+You can't generally create such a certificate using OpenSSL but there is no
+need to any more. Nowadays web browsers using unrestricted strong encryption
+are generally available.
+
+When there were tight export restrictions on the export of strong encryption
+software from the US only weak encryption algorithms could be freely exported
+(initially 40 bit and then 56 bit). It was widely recognised that this was
+inadequate. A relaxation 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
+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
+an authorised authority. If these test succeeded it would reconnect using
+strong encryption.
+
+Only certain (initially one) certificate authorities could issue the
+certificates and they generally cost more than ordinary certificates.
+
+Although OpenSSL can create certificates containing the appropriate extensions
+the certificate would not come from a permitted authority and so would not
+be recognized.
+
+The export laws were later changed to allow almost unrestricted use of strong
+encryption so these certificates are now obsolete.
+
+
+* How can I set up a bundle of commercial root CA certificates?
+
+The OpenSSL software is shipped without any root CA certificate as the
+OpenSSL project does not have any policy on including or excluding
+any specific CA and does not intend to set up such a policy. Deciding
+about which CAs to support is up to application developers or
+administrators.
+
+Other projects do have other policies so you can for example extract the CA
+bundle used by Mozilla and/or modssl as described in this article:
+
+  http://www.mail-archive.com/modssl-users@modssl.org/msg16980.html
+
+
 [BUILD] =======================================================================
 
 * Why does the linker complain about undefined symbols?
 [BUILD] =======================================================================
 
 * Why does the linker complain about undefined symbols?
@@ -617,6 +672,18 @@ the module in question. The recommendation is to disable SHA-512 by
 adding no-sha512 to ./config [or ./Configure] command line. Another
 possible alternative might be to switch to GCC.
 
 adding no-sha512 to ./config [or ./Configure] command line. Another
 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.
+
 [PROG] ========================================================================
 
 * Is OpenSSL thread-safe?
 [PROG] ========================================================================
 
 * Is OpenSSL thread-safe?
@@ -628,8 +695,9 @@ libraries.  If your platform is not one of these, consult the INSTALL
 file.
 
 Multi-threaded applications must provide two callback functions to
 file.
 
 Multi-threaded applications must provide two callback functions to
-OpenSSL.  This is described in the threads(3) manpage.
-
+OpenSSL by calling CRYPTO_set_locking_callback() and
+CRYPTO_set_id_callback().  This is described in the threads(3)
+manpage.
 
 * I've compiled a program under Windows and it crashes: why?
 
 
 * I've compiled a program under Windows and it crashes: why?
 
@@ -649,10 +717,10 @@ 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:
 
 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
+ 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)
     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)
@@ -672,16 +740,19 @@ Note that debug and release libraries are NOT interchangeable.  If you
 built OpenSSL with /MD your application must use /MD and cannot use /MDd.
 
 As per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL
 built OpenSSL with /MD your application must use /MD and cannot use /MDd.
 
 As per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL
-.DLLs compiled with some specific run-time option [we recommend the
+.DLLs compiled with some specific run-time option [we insist on the
 default /MD] can be deployed with application compiled with different
 option or even different compiler. But there is a catch! Instead of
 re-compiling OpenSSL toolkit, as you would have to with prior versions,
 you have to compile small C snippet with compiler and/or options of
 your choice. The snippet gets installed as
 <install-root>/include/openssl/applink.c and should be either added to
 default /MD] can be deployed with application compiled with different
 option or even different compiler. But there is a catch! Instead of
 re-compiling OpenSSL toolkit, as you would have to with prior versions,
 you have to compile small C snippet with compiler and/or options of
 your choice. The snippet gets installed as
 <install-root>/include/openssl/applink.c and should be either added to
-your project or simply #include-d in one [and only one] of your source
-files. Failure to do either manifests itself as fatal "no
-OPENSSL_Applink" error.
+your application project or simply #include-d in one [and only one]
+of your application source files. Failure to link this shim module
+into your application manifests itself as fatal "no OPENSSL_Applink"
+run-time error. An explicit reminder is due that in this situation
+[mixing compiler options] it is as important to add CRYPTO_malloc_init
+prior first call to OpenSSL.
 
 * How do I read or write a DER encoded buffer using the ASN1 functions?
 
 
 * How do I read or write a DER encoded buffer using the ASN1 functions?
 
@@ -767,11 +838,11 @@ code itself (the hex digits after the second colon).
 
 * Why do I get errors about unknown algorithms?
 
 
 * 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.
-
+The cause is forgetting to load OpenSSL's table of algorithms with
+OpenSSL_add_all_algorithms(). See the manual page for more information. This
+can cause several problems such as being unable to read in an encrypted
+PEM file, unable to decrypt a PKCS#12 file or signature failure when
+verifying certificates.
 
 * Why can't the OpenSSH configure script detect OpenSSL?
 
 
 * Why can't the OpenSSH configure script detect OpenSSL?
 
@@ -839,5 +910,15 @@ thread-safe):
   ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data().
 
 
   ERR_free_strings(), EVP_cleanup() and CRYPTO_cleanup_all_ex_data().
 
 
+* Why does Valgrind complain about the use of uninitialized data?
+
+When OpenSSL's PRNG routines are called to generate random numbers the supplied
+buffer contents are mixed into the entropy pool: so it technically does not
+matter whether the buffer is initialized at this point or not.  Valgrind (and
+other test tools) will complain about this. When using Valgrind, make sure the
+OpenSSL library has been compiled with the PURIFY macro defined (-DPURIFY)
+to get rid of these warnings.
+
+
 ===============================================================================
 
 ===============================================================================