Use -I to add to @INC, and use -w to produce warnings

[openssl.git] / FAQ

diff --git a/FAQ b/FAQ
index 3e23e23de86647b11631e4b36f09d15b6b38df2e..0ff792bbc39ca37735ab864c78c72bea89f750a2 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -133,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
 * 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
 
 Some applications that use OpenSSL are distributed in binary form.
 When using such an application, you don't need to install OpenSSL


@@ -412,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
 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?
 has however been left as default for the sake of compatibility.
 
 * What is a "128 bit certificate"? Can I create one with OpenSSL?


@@ -434,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.
 
 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
 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


@@ -723,16 +723,15 @@ possible alternative might be to switch to GCC.
 
 * Test suite still fails, what to do?
 
 
 * 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?
 
 
 * I think I've found a bug, what should I do?
 


@@ -790,18 +789,15 @@ considered to be security issues.
 
 * Is OpenSSL thread-safe?
 
 
 * 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?
 
 
 * I've compiled a program under Windows and it crashes: why?
 


@@ -865,22 +861,25 @@ with the i2d_*_bio() or d2i_*_bio() functions or you can use the
 i2d_*(), d2i_*() functions directly. Since these are often the
 cause of grief here are some code fragments using PKCS7 as an example:
 
 i2d_*(), d2i_*() functions directly. Since these are often the
 cause of grief here are some code fragments using PKCS7 as an example:
 

+----- snip:start -----

  unsigned char *buf, *p;
  unsigned char *buf, *p;

- int len;
+ int len = i2d_PKCS7(p7, NULL);

 
 

- len = i2d_PKCS7(p7, NULL);
- buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
+ buf = OPENSSL_malloc(len); /* error checking omitted */

  p = buf;
  i2d_PKCS7(p7, &p);
  p = buf;
  i2d_PKCS7(p7, &p);

+----- snip:end -----

 
 At this point buf contains the len bytes of the DER encoding of
 p7.
 
 The opposite assumes we already have len bytes in buf:
 
 
 At this point buf contains the len bytes of the DER encoding of
 p7.
 
 The opposite assumes we already have len bytes in buf:
 

- unsigned char *p;
- p = buf;
+----- snip:start -----
+ unsigned char *p = buf;
+

  p7 = d2i_PKCS7(NULL, &p, len);
  p7 = d2i_PKCS7(NULL, &p, len);

+----- snip:end -----

 
 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
 
 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


@@ -897,14 +896,17 @@ 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:
 
 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 */
+----- snip:start -----
+ unsigned char *buf = NULL;
+ int len = i2d_PKCS7(p7, &buf);
+
+ if (len < 0) {
+     /* Error */
+ }

  /* Do some things with 'buf' */
  /* Finished with buf: free it */
  OPENSSL_free(buf);
  /* Do some things with 'buf' */
  /* Finished with buf: free it */
  OPENSSL_free(buf);

+----- snip:end -----

 
 In this special case the "buf" parameter is *not* incremented, it points
 to the start of the encoding.
 
 In this special case the "buf" parameter is *not* incremented, it points
 to the start of the encoding.