A compiler warning removed. Thanks to the folks at HP!
[openssl.git] / FAQ
diff --git a/FAQ b/FAQ
index fa44480..29acc8a 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -10,6 +10,8 @@ OpenSSL  -  Frequently Asked Questions
 * Why does the linker complain about undefined symbols?
 * Where can I get a compiled version of OpenSSL?
 * I've compiled a program under Windows and it crashes: why?
+* How do I read or write a DER encoded buffer using the ASN1 functions?
+* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
 * I've called <some function> and it fails, why?
 * I just get a load of numbers for the error output, what do they mean?
 * Why do I get errors about unknown algorithms?
@@ -24,12 +26,13 @@ OpenSSL  -  Frequently Asked Questions
 * 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 compilation fail on Alpha True64 Unix?
+* Why does the OpenSSL compilation fail with "ar: command not found"?
 
 
 * Which is the current version of OpenSSL?
 
 The current version is available from <URL: http://www.openssl.org>.
-OpenSSL 0.9.5a was released on April 1st, 2000.
+OpenSSL 0.9.6 was released on September 24th, 2000.
 
 In addition to the current stable release, you can also access daily
 snapshots of the OpenSSL development version at <URL:
@@ -85,12 +88,6 @@ offer legal advice.
 You can configure OpenSSL so as not to use RC5 and IDEA by using
  ./config no-rc5 no-idea
 
-Until the RSA patent expires, U.S. users may want to use
- ./config no-rc5 no-idea no-rsa
-
-Please note that you will *not* be able to communicate with most of
-the popular web browsers without RSA support.
-
 
 * Is OpenSSL thread-safe?
 
@@ -138,7 +135,7 @@ 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 som effects on OpenSSL.
+device, which may have some effects on OpenSSL.
 
 
 * Why does the linker complain about undefined symbols?
@@ -186,6 +183,54 @@ otherwise the conflict will cause a program to crash: typically on the
 first BIO related read or write operation.
 
 
+* How do I read or write a DER encoded buffer using the ASN1 functions?
+
+You have two options. You can either use a memory BIO in conjunction
+with the i2d_XXX_bio() or d2i_XXX_bio() functions or you can use the
+i2d_XXX(), d2i_XXX() functions directly. Since these are often the
+cause of grief here are some code fragments using PKCS7 as an example:
+
+unsigned char *buf, *p;
+int len;
+
+len = i2d_PKCS7(p7, NULL);
+buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
+p = buf;
+i2d_PKCS7(p7, &p);
+
+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;
+p7 = d2i_PKCS7(NULL, &p, len);
+
+At this point p7 contains a valid PKCS7 structure of NULL if an error
+occurred. If an error occurred ERR_print_errors(bio) should give more
+information.
+
+The reason for the temporary variable 'p' is that the ASN1 functions
+increment the passed pointer so it is ready to read or write the next
+structure. This is often a cause of problems: without the temporary
+variable the buffer pointer is changed to point just after the data
+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.
+
+
+* I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
+
+This usually happens when you try compiling something using the PKCS#12
+macros with a C++ compiler. There is hardly ever any need to use the
+PKCS#12 macros in a program, it is much easier to parse and create
+PKCS#12 files using the PKCS12_parse() and PKCS12_create() functions
+documented in doc/openssl.txt and with examples in demos/pkcs12. The
+'pkcs12' application has to use the macros because it prints out 
+debugging information.
+
+
 * I've called <some function> and it fails, why?
 
 Before submitting a report or asking in one of the mailing lists, you
@@ -337,16 +382,25 @@ be safely used.
 
 On some Alpha installations running True64 Unix and Compaq C, the compilation
 of crypto/sha/sha_dgst.c fails with the message 'Fatal:  Insufficient virtual
-memory to continue compilation.'  As far as the tests have shown, this is a
-compiler bug.  What happens is that it eats up resident memory (not the swap)
-until the current limit is reached and then dies with the error message given
-above.  The bug in question is clearly in the optimization code, because if
-one eliminates optimization completely (-O0), the compilation goes through
-(and the compiler consumes about 2MB of resident memory instead of 128MB or
-whatever one's limit is currently).  The very quick solution would be to
-compile everything with -O0 as optimization level, but that's not a very
-nice thing to do for those who expect to get the best result from OpenSSL.
-A bit more complicated solution is the following:
+memory to continue compilation.'  As far as the tests have shown, this may be
+a compiler bug.  What happens is that it eats up a lot of resident memory
+to build something, probably a table.  The problem is clearly in the
+optimization code, because if one eliminates optimization completely (-O0),
+the compilation goes through (and the compiler consumes about 2MB of resident
+memory instead of 240MB or whatever one's limit is currently).
+
+There are three options to solve this problem:
+
+1. set your current data segment size soft limit higher.  Experience shows
+that about 241000 kbytes seems to be enough on an AlphaServer DS10.  You do
+this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
+kbytes to set the limit to.
+
+2. If you have a hard limit that is lower than what you need and you can't
+get it changed, you can compile all of OpenSSL with -O0 as optimization
+level.  This is however not a very nice thing to do for those who expect to
+get the best result from OpenSSL.  A bit more complicated solution is the
+following:
 
 ----- snip:start -----
   make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
@@ -359,3 +413,20 @@ This will only compile sha_dgst.c with -O0, the rest with the optimization
 level chosen by the configuration process.  When the above is done, do the
 test and installation and you're set.
 
+
+* Why does the OpenSSL compilation fail with "ar: command not found"?
+
+Getting this message is quite usual on Solaris 2, because Sun has hidden
+away 'ar' and other development commands in directories that aren't in
+$PATH by default.  One of those directories is '/usr/ccs/bin'.  The
+quickest way to fix this is to do the following (it assumes you use sh
+or any sh-compatible shell):
+
+----- snip:start -----
+  PATH=${PATH}:/usr/ccs/bin; export PATH
+----- snip:end -----
+
+and then redo the compilation.  What you should really do is make sure
+'/usr/ccs/bin' is permanently in your $PATH, for example through your
+'.profile' (again, assuming you use a sh-compatible shell).
+