1: OpenSSL  -  Frequently Asked Questions
    2: --------------------------------------
    3: 
    4: [MISC] Miscellaneous questions
    5: 
    6: * Which is the current version of OpenSSL?
    7: * Where is the documentation?
    8: * How can I contact the OpenSSL developers?
    9: * Where can I get a compiled version of OpenSSL?
   10: * Why aren't tools like 'autoconf' and 'libtool' used?
   11: * What is an 'engine' version?
   12: * How do I check the authenticity of the OpenSSL distribution?
   13: 
   14: [LEGAL] Legal questions
   15: 
   16: * Do I need patent licenses to use OpenSSL?
   17: * Can I use OpenSSL with GPL software? 
   18: 
   19: [USER] Questions on using the OpenSSL applications
   20: 
   21: * Why do I get a "PRNG not seeded" error message?
   22: * Why do I get an "unable to write 'random state'" error message?
   23: * How do I create certificates or certificate requests?
   24: * Why can't I create certificate requests?
   25: * Why does <SSL program> fail with a certificate verify error?
   26: * Why can I only use weak ciphers when I connect to a server using OpenSSL?
   27: * How can I create DSA certificates?
   28: * Why can't I make an SSL connection using a DSA certificate?
   29: * How can I remove the passphrase on a private key?
   30: * Why can't I use OpenSSL certificates with SSL client authentication?
   31: * Why does my browser give a warning about a mismatched hostname?
   32: * How do I install a CA certificate into a browser?
   33: * Why is OpenSSL x509 DN output not conformant to RFC2253?
   34: * What is a "128 bit certificate"? Can I create one with OpenSSL?
   35: 
   36: [BUILD] Questions about building and testing OpenSSL
   37: 
   38: * Why does the linker complain about undefined symbols?
   39: * Why does the OpenSSL test fail with "bc: command not found"?
   40: * Why does the OpenSSL test fail with "bc: 1 no implemented"?
   41: * Why does the OpenSSL test fail with "bc: stack empty"?
   42: * Why does the OpenSSL compilation fail on Alpha Tru64 Unix?
   43: * Why does the OpenSSL compilation fail with "ar: command not found"?
   44: * Why does the OpenSSL compilation fail on Win32 with VC++?
   45: * What is special about OpenSSL on Redhat?
   46: * Why does the OpenSSL compilation fail on MacOS X?
   47: * Why does the OpenSSL test suite fail on MacOS X?
   48: * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]?
   49: * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
   50: * Why does the OpenSSL test suite fail in sha512t on x86 CPU?
   51: * Why does compiler fail to compile sha512.c?
   52: * Test suite still fails, what to do?
   53: 
   54: [PROG] Questions about programming with OpenSSL
   55: 
   56: * Is OpenSSL thread-safe?
   57: * I've compiled a program under Windows and it crashes: why?
   58: * How do I read or write a DER encoded buffer using the ASN1 functions?
   59: * OpenSSL uses DER but I need BER format: does OpenSSL support BER?
   60: * I've tried using <M_some_evil_pkcs12_macro> and I get errors why?
   61: * I've called <some function> and it fails, why?
   62: * I just get a load of numbers for the error output, what do they mean?
   63: * Why do I get errors about unknown algorithms?
   64: * Why can't the OpenSSH configure script detect OpenSSL?
   65: * Can I use OpenSSL's SSL library with non-blocking I/O?
   66: * Why doesn't my server application receive a client certificate?
   67: * Why does compilation fail due to an undefined symbol NID_uniqueIdentifier?
   68: * I think I've detected a memory leak, is this a bug?
   69: * Why does Valgrind complain about the use of uninitialized data?
   70: 
   71: ===============================================================================
   72: 
   73: [MISC] ========================================================================
   74: 
   75: * Which is the current version of OpenSSL?
   76: 
   77: The current version is available from <URL: http://www.openssl.org>.
   78: OpenSSL 0.9.8g was released on October 19th, 2007.
   79: 
   80: In addition to the current stable release, you can also access daily
   81: snapshots of the OpenSSL development version at <URL:
   82: ftp://ftp.openssl.org/snapshot/>, or get it by anonymous CVS access.
   83: 
   84: 
   85: * Where is the documentation?
   86: 
   87: OpenSSL is a library that provides cryptographic functionality to
   88: applications such as secure web servers.  Be sure to read the
   89: documentation of the application you want to use.  The INSTALL file
   90: explains how to install this library.
   91: 
   92: OpenSSL includes a command line utility that can be used to perform a
   93: variety of cryptographic functions.  It is described in the openssl(1)
   94: manpage.  Documentation for developers is currently being written.  A
   95: few manual pages already are available; overviews over libcrypto and
   96: libssl are given in the crypto(3) and ssl(3) manpages.
   97: 
   98: The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a
   99: different directory if you specified one as described in INSTALL).
  100: In addition, you can read the most current versions at
  101: <URL: http://www.openssl.org/docs/>.
  102: 
  103: For information on parts of libcrypto that are not yet documented, you
  104: might want to read Ariel Glenn's documentation on SSLeay 0.9, OpenSSL's
  105: predecessor, at <URL: http://www.columbia.edu/~ariel/ssleay/>.  Much
  106: of this still applies to OpenSSL.
  107: 
  108: There is some documentation about certificate extensions and PKCS#12
  109: in doc/openssl.txt
  110: 
  111: The original SSLeay documentation is included in OpenSSL as
  112: doc/ssleay.txt.  It may be useful when none of the other resources
  113: help, but please note that it reflects the obsolete version SSLeay
  114: 0.6.6.
  115: 
  116: 
  117: * How can I contact the OpenSSL developers?
  118: 
  119: The README file describes how to submit bug reports and patches to
  120: OpenSSL.  Information on the OpenSSL mailing lists is available from
  121: <URL: http://www.openssl.org>.
  122: 
  123: 
  124: * Where can I get a compiled version of OpenSSL?
  125: 
  126: You can finder pointers to binary distributions in
  127: http://www.openssl.org/related/binaries.html .
  128: 
  129: Some applications that use OpenSSL are distributed in binary form.
  130: When using such an application, you don't need to install OpenSSL
  131: yourself; the application will include the required parts (e.g. DLLs).
  132: 
  133: If you want to build OpenSSL on a Windows system and you don't have
  134: a C compiler, read the "Mingw32" section of INSTALL.W32 for information
  135: on how to obtain and install the free GNU C compiler.
  136: 
  137: A number of Linux and *BSD distributions include OpenSSL.
  138: 
  139: 
  140: * Why aren't tools like 'autoconf' and 'libtool' used?
  141: 
  142: autoconf will probably be used in future OpenSSL versions. If it was
  143: less Unix-centric, it might have been used much earlier.
  144: 
  145: * What is an 'engine' version?
  146: 
  147: With version 0.9.6 OpenSSL was extended to interface to external crypto
  148: hardware. This was realized in a special release '0.9.6-engine'. With
  149: version 0.9.7 the changes were merged into the main development line,
  150: so that the special release is no longer necessary.
  151: 
  152: * How do I check the authenticity of the OpenSSL distribution?
  153: 
  154: We provide MD5 digests and ASC signatures of each tarball.
  155: Use MD5 to check that a tarball from a mirror site is identical:
  156: 
  157:    md5sum TARBALL | awk '{print $1;}' | cmp - TARBALL.md5
  158: 
  159: You can check authenticity using pgp or gpg. You need the OpenSSL team
  160: member public key used to sign it (download it from a key server, see a
  161: list of keys at <URL: http://www.openssl.org/about/>). Then
  162: just do:
  163: 
  164:    pgp TARBALL.asc
  165: 
  166: [LEGAL] =======================================================================
  167: 
  168: * Do I need patent licenses to use OpenSSL?
  169: 
  170: The patents section of the README file lists patents that may apply to
  171: you if you want to use OpenSSL.  For information on intellectual
  172: property rights, please consult a lawyer.  The OpenSSL team does not
  173: offer legal advice.
  174: 
  175: You can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using
  176:  ./config no-idea no-mdc2 no-rc5
  177: 
  178: 
  179: * Can I use OpenSSL with GPL software?
  180: 
  181: On many systems including the major Linux and BSD distributions, yes (the
  182: GPL does not place restrictions on using libraries that are part of the
  183: normal operating system distribution).
  184: 
  185: On other systems, the situation is less clear. Some GPL software copyright
  186: holders claim that you infringe on their rights if you use OpenSSL with
  187: their software on operating systems that don't normally include OpenSSL.
  188: 
  189: If you develop open source software that uses OpenSSL, you may find it
  190: useful to choose an other license than the GPL, or state explicitly that
  191: "This program is released under the GPL with the additional exemption that
  192: compiling, linking, and/or using OpenSSL is allowed."  If you are using
  193: GPL software developed by others, you may want to ask the copyright holder
  194: for permission to use their software with OpenSSL.
  195: 
  196: 
  197: [USER] ========================================================================
  198: 
  199: * Why do I get a "PRNG not seeded" error message?
  200: 
  201: Cryptographic software needs a source of unpredictable data to work
  202: correctly.  Many open source operating systems provide a "randomness
  203: device" (/dev/urandom or /dev/random) that serves this purpose.
  204: All OpenSSL versions try to use /dev/urandom by default; starting with
  205: version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not
  206: available.
  207: 
  208: On other systems, applications have to call the RAND_add() or
  209: RAND_seed() function with appropriate data before generating keys or
  210: performing public key encryption. (These functions initialize the
  211: pseudo-random number generator, PRNG.)  Some broken applications do
  212: not do this.  As of version 0.9.5, the OpenSSL functions that need
  213: randomness report an error if the random number generator has not been
  214: seeded with at least 128 bits of randomness.  If this error occurs and
  215: is not discussed in the documentation of the application you are
  216: using, please contact the author of that application; it is likely
  217: that it never worked correctly.  OpenSSL 0.9.5 and later make the
  218: error visible by refusing to perform potentially insecure encryption.
  219: 
  220: If you are using Solaris 8, you can add /dev/urandom and /dev/random
  221: devices by installing patch 112438 (Sparc) or 112439 (x86), which are
  222: available via the Patchfinder at <URL: http://sunsolve.sun.com>
  223: (Solaris 9 includes these devices by default). For /dev/random support
  224: for earlier Solaris versions, see Sun's statement at
  225: <URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski>
  226: (the SUNWski package is available in patch 105710).
  227: 
  228: On systems without /dev/urandom and /dev/random, it is a good idea to
  229: use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for
  230: details.  Starting with version 0.9.7, OpenSSL will automatically look
  231: for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and
  232: /etc/entropy.
  233: 
  234: Most components of the openssl command line utility automatically try
  235: to seed the random number generator from a file.  The name of the
  236: default seeding file is determined as follows: If environment variable
  237: RANDFILE is set, then it names the seeding file.  Otherwise if
  238: environment variable HOME is set, then the seeding file is $HOME/.rnd.
  239: If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will
  240: use file .rnd in the current directory while OpenSSL 0.9.6a uses no
  241: default seeding file at all.  OpenSSL 0.9.6b and later will behave
  242: similarly to 0.9.6a, but will use a default of "C:\" for HOME on
  243: Windows systems if the environment variable has not been set.
  244: 
  245: If the default seeding file does not exist or is too short, the "PRNG
  246: not seeded" error message may occur.
  247: 
  248: The openssl command line utility will write back a new state to the
  249: default seeding file (and create this file if necessary) unless
  250: there was no sufficient seeding.
  251: 
  252: Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work.
  253: Use the "-rand" option of the OpenSSL command line tools instead.
  254: The $RANDFILE environment variable and $HOME/.rnd are only used by the
  255: OpenSSL command line tools. Applications using the OpenSSL library
  256: provide their own configuration options to specify the entropy source,
  257: please check out the documentation coming the with application.
  258: 
  259: 
  260: * Why do I get an "unable to write 'random state'" error message?
  261: 
  262: 
  263: Sometimes the openssl command line utility does not abort with
  264: a "PRNG not seeded" error message, but complains that it is
  265: "unable to write 'random state'".  This message refers to the
  266: default seeding file (see previous answer).  A possible reason
  267: is that no default filename is known because neither RANDFILE
  268: nor HOME is set.  (Versions up to 0.9.6 used file ".rnd" in the
  269: current directory in this case, but this has changed with 0.9.6a.)
  270: 
  271: 
  272: * How do I create certificates or certificate requests?
  273: 
  274: Check out the CA.pl(1) manual page. This provides a simple wrapper round
  275: the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check
  276: out the manual pages for the individual utilities and the certificate
  277: extensions documentation (currently in doc/openssl.txt).
  278: 
  279: 
  280: * Why can't I create certificate requests?
  281: 
  282: You typically get the error:
  283: 
  284:         unable to find 'distinguished_name' in config
  285:         problems making Certificate Request
  286: 
  287: This is because it can't find the configuration file. Check out the
  288: DIAGNOSTICS section of req(1) for more information.
  289: 
  290: 
  291: * Why does <SSL program> fail with a certificate verify error?
  292: 
  293: This problem is usually indicated by log messages saying something like
  294: "unable to get local issuer certificate" or "self signed certificate".
  295: When a certificate is verified its root CA must be "trusted" by OpenSSL
  296: this typically means that the CA certificate must be placed in a directory
  297: or file and the relevant program configured to read it. The OpenSSL program
  298: 'verify' behaves in a similar way and issues similar error messages: check
  299: the verify(1) program manual page for more information.
  300: 
  301: 
  302: * Why can I only use weak ciphers when I connect to a server using OpenSSL?
  303: 
  304: This is almost certainly because you are using an old "export grade" browser
  305: which only supports weak encryption. Upgrade your browser to support 128 bit
  306: ciphers.
  307: 
  308: 
  309: * How can I create DSA certificates?
  310: 
  311: Check the CA.pl(1) manual page for a DSA certificate example.
  312: 
  313: 
  314: * Why can't I make an SSL connection to a server using a DSA certificate?
  315: 
  316: Typically you'll see a message saying there are no shared ciphers when
  317: the same setup works fine with an RSA certificate. There are two possible
  318: causes. The client may not support connections to DSA servers most web
  319: browsers (including Netscape and MSIE) only support connections to servers
  320: supporting RSA cipher suites. The other cause is that a set of DH parameters
  321: has not been supplied to the server. DH parameters can be created with the
  322: dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example:
  323: check the source to s_server in apps/s_server.c for an example.
  324: 
  325: 
  326: * How can I remove the passphrase on a private key?
  327: 
  328: Firstly you should be really *really* sure you want to do this. Leaving
  329: a private key unencrypted is a major security risk. If you decide that
  330: you do have to do this check the EXAMPLES sections of the rsa(1) and
  331: dsa(1) manual pages.
  332: 
  333: 
  334: * Why can't I use OpenSSL certificates with SSL client authentication?
  335: 
  336: What will typically happen is that when a server requests authentication
  337: it will either not include your certificate or tell you that you have
  338: no client certificates (Netscape) or present you with an empty list box
  339: (MSIE). The reason for this is that when a server requests a client
  340: certificate it includes a list of CAs names which it will accept. Browsers
  341: will only let you select certificates from the list on the grounds that
  342: there is little point presenting a certificate which the server will
  343: reject.
  344: 
  345: The solution is to add the relevant CA certificate to your servers "trusted
  346: CA list". How you do this depends on the server software in uses. You can
  347: print out the servers list of acceptable CAs using the OpenSSL s_client tool:
  348: 
  349: openssl s_client -connect www.some.host:443 -prexit
  350: 
  351: If your server only requests certificates on certain URLs then you may need
  352: to manually issue an HTTP GET command to get the list when s_client connects:
  353: 
  354: GET /some/page/needing/a/certificate.html
  355: 
  356: If your CA does not appear in the list then this confirms the problem.
  357: 
  358: 
  359: * Why does my browser give a warning about a mismatched hostname?
  360: 
  361: Browsers expect the server's hostname to match the value in the commonName
  362: (CN) field of the certificate. If it does not then you get a warning.
  363: 
  364: 
  365: * How do I install a CA certificate into a browser?
  366: 
  367: The usual way is to send the DER encoded certificate to the browser as
  368: MIME type application/x-x509-ca-cert, for example by clicking on an appropriate
  369: link. On MSIE certain extensions such as .der or .cacert may also work, or you
  370: can import the certificate using the certificate import wizard.
  371: 
  372: You can convert a certificate to DER form using the command:
  373: 
  374: openssl x509 -in ca.pem -outform DER -out ca.der
  375: 
  376: Occasionally someone suggests using a command such as:
  377: 
  378: openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem
  379: 
  380: DO NOT DO THIS! This command will give away your CAs private key and
  381: reduces its security to zero: allowing anyone to forge certificates in
  382: whatever name they choose.
  383: 
  384: * Why is OpenSSL x509 DN output not conformant to RFC2253?
  385: 
  386: The ways to print out the oneline format of the DN (Distinguished Name) have
  387: been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex()
  388: interface, the "-nameopt" option could be introduded. See the manual
  389: page of the "openssl x509" commandline tool for details. The old behaviour
  390: has however been left as default for the sake of compatibility.
  391: 
  392: * What is a "128 bit certificate"? Can I create one with OpenSSL?
  393: 
  394: The term "128 bit certificate" is a highly misleading marketing term. It does
  395: *not* refer to the size of the public key in the certificate! A certificate
  396: containing a 128 bit RSA key would have negligible security.
  397: 
  398: There were various other names such as "magic certificates", "SGC
  399: certificates", "step up certificates" etc.
  400: 
  401: You can't generally create such a certificate using OpenSSL but there is no
  402: need to any more. Nowadays web browsers using unrestricted strong encryption
  403: are generally available.
  404: 
  405: When there were tight export restrictions on the export of strong encryption
  406: software from the US only weak encryption algorithms could be freely exported
  407: (initially 40 bit and then 56 bit). It was widely recognised that this was
  408: inadequate. A relaxation the rules allowed the use of strong encryption but
  409: only to an authorised server.
  410: 
  411: Two slighly different techniques were developed to support this, one used by
  412: Netscape was called "step up", the other used by MSIE was called "Server Gated
  413: Cryptography" (SGC). When a browser initially connected to a server it would
  414: check to see if the certificate contained certain extensions and was issued by
  415: an authorised authority. If these test succeeded it would reconnect using
  416: strong encryption.
  417: 
  418: Only certain (initially one) certificate authorities could issue the
  419: certificates and they generally cost more than ordinary certificates.
  420: 
  421: Although OpenSSL can create certificates containing the appropriate extensions
  422: the certificate would not come from a permitted authority and so would not
  423: be recognized.
  424: 
  425: The export laws were later changed to allow almost unrestricted use of strong
  426: encryption so these certificates are now obsolete.
  427: 
  428: 
  429: [BUILD] =======================================================================
  430: 
  431: * Why does the linker complain about undefined symbols?
  432: 
  433: Maybe the compilation was interrupted, and make doesn't notice that
  434: something is missing.  Run "make clean; make".
  435: 
  436: If you used ./Configure instead of ./config, make sure that you
  437: selected the right target.  File formats may differ slightly between
  438: OS versions (for example sparcv8/sparcv9, or a.out/elf).
  439: 
  440: In case you get errors about the following symbols, use the config
  441: option "no-asm", as described in INSTALL:
  442: 
  443:  BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt,
  444:  CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt,
  445:  RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words,
  446:  bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4,
  447:  bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3,
  448:  des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3,
  449:  des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order
  450: 
  451: If none of these helps, you may want to try using the current snapshot.
  452: If the problem persists, please submit a bug report.
  453: 
  454: 
  455: * Why does the OpenSSL test fail with "bc: command not found"?
  456: 
  457: You didn't install "bc", the Unix calculator.  If you want to run the
  458: tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor.
  459: 
  460: 
  461: * Why does the OpenSSL test fail with "bc: 1 no implemented"?
  462: 
  463: On some SCO installations or versions, bc has a bug that gets triggered
  464: when you run the test suite (using "make test").  The message returned is
  465: "bc: 1 not implemented".
  466: 
  467: The best way to deal with this is to find another implementation of bc
  468: and compile/install it.  GNU bc (see http://www.gnu.org/software/software.html
  469: for download instructions) can be safely used, for example.
  470: 
  471: 
  472: * Why does the OpenSSL test fail with "bc: stack empty"?
  473: 
  474: On some DG/ux versions, bc seems to have a too small stack for calculations
  475: that the OpenSSL bntest throws at it.  This gets triggered when you run the
  476: test suite (using "make test").  The message returned is "bc: stack empty".
  477: 
  478: The best way to deal with this is to find another implementation of bc
  479: and compile/install it.  GNU bc (see http://www.gnu.org/software/software.html
  480: for download instructions) can be safely used, for example.
  481: 
  482: 
  483: * Why does the OpenSSL compilation fail on Alpha Tru64 Unix?
  484: 
  485: On some Alpha installations running Tru64 Unix and Compaq C, the compilation
  486: of crypto/sha/sha_dgst.c fails with the message 'Fatal:  Insufficient virtual
  487: memory to continue compilation.'  As far as the tests have shown, this may be
  488: a compiler bug.  What happens is that it eats up a lot of resident memory
  489: to build something, probably a table.  The problem is clearly in the
  490: optimization code, because if one eliminates optimization completely (-O0),
  491: the compilation goes through (and the compiler consumes about 2MB of resident
  492: memory instead of 240MB or whatever one's limit is currently).
  493: 
  494: There are three options to solve this problem:
  495: 
  496: 1. set your current data segment size soft limit higher.  Experience shows
  497: that about 241000 kbytes seems to be enough on an AlphaServer DS10.  You do
  498: this with the command 'ulimit -Sd nnnnnn', where 'nnnnnn' is the number of
  499: kbytes to set the limit to.
  500: 
  501: 2. If you have a hard limit that is lower than what you need and you can't
  502: get it changed, you can compile all of OpenSSL with -O0 as optimization
  503: level.  This is however not a very nice thing to do for those who expect to
  504: get the best result from OpenSSL.  A bit more complicated solution is the
  505: following:
  506: 
  507: ----- snip:start -----
  508:   make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \
  509:        sed -e 's/ -O[0-9] / -O0 /'`"
  510:   rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'`
  511:   make
  512: ----- snip:end -----
  513: 
  514: This will only compile sha_dgst.c with -O0, the rest with the optimization
  515: level chosen by the configuration process.  When the above is done, do the
  516: test and installation and you're set.
  517: 
  518: 3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It 
  519: should not be used and is not used in SSL/TLS nor any other recognized
  520: protocol in either case.
  521: 
  522: 
  523: * Why does the OpenSSL compilation fail with "ar: command not found"?
  524: 
  525: Getting this message is quite usual on Solaris 2, because Sun has hidden
  526: away 'ar' and other development commands in directories that aren't in
  527: $PATH by default.  One of those directories is '/usr/ccs/bin'.  The
  528: quickest way to fix this is to do the following (it assumes you use sh
  529: or any sh-compatible shell):
  530: 
  531: ----- snip:start -----
  532:   PATH=${PATH}:/usr/ccs/bin; export PATH
  533: ----- snip:end -----
  534: 
  535: and then redo the compilation.  What you should really do is make sure
  536: '/usr/ccs/bin' is permanently in your $PATH, for example through your
  537: '.profile' (again, assuming you use a sh-compatible shell).
  538: 
  539: 
  540: * Why does the OpenSSL compilation fail on Win32 with VC++?
  541: 
  542: Sometimes, you may get reports from VC++ command line (cl) that it
  543: can't find standard include files like stdio.h and other weirdnesses.
  544: One possible cause is that the environment isn't correctly set up.
  545: To solve that problem for VC++ versions up to 6, one should run
  546: VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++
  547: installation directory (somewhere under 'Program Files').  For VC++
  548: version 7 (and up?), which is also called VS.NET, the file is called
  549: VSVARS32.BAT instead.
  550: This needs to be done prior to running NMAKE, and the changes are only
  551: valid for the current DOS session.
  552: 
  553: 
  554: * What is special about OpenSSL on Redhat?
  555: 
  556: Red Hat Linux (release 7.0 and later) include a preinstalled limited
  557: version of OpenSSL. For patent reasons, support for IDEA, RC5 and MDC2
  558: is disabled in this version. The same may apply to other Linux distributions.
  559: Users may therefore wish to install more or all of the features left out.
  560: 
  561: To do this you MUST ensure that you do not overwrite the openssl that is in
  562: /usr/bin on your Red Hat machine. Several packages depend on this file,
  563: including sendmail and ssh. /usr/local/bin is a good alternative choice. The
  564: libraries that come with Red Hat 7.0 onwards have different names and so are
  565: not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and
  566: /lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and
  567: /lib/libcrypto.so.2 respectively).
  568: 
  569: Please note that we have been advised by Red Hat attempting to recompile the
  570: openssl rpm with all the cryptography enabled will not work. All other
  571: packages depend on the original Red Hat supplied openssl package. It is also
  572: worth noting that due to the way Red Hat supplies its packages, updates to
  573: openssl on each distribution never change the package version, only the
  574: build number. For example, on Red Hat 7.1, the latest openssl package has
  575: version number 0.9.6 and build number 9 even though it contains all the
  576: relevant updates in packages up to and including 0.9.6b.
  577: 
  578: A possible way around this is to persuade Red Hat to produce a non-US
  579: version of Red Hat Linux.
  580: 
  581: FYI: Patent numbers and expiry dates of US patents:
  582: MDC-2: 4,908,861 13/03/2007
  583: IDEA:  5,214,703 25/05/2010
  584: RC5:   5,724,428 03/03/2015
  585: 
  586: 
  587: * Why does the OpenSSL compilation fail on MacOS X?
  588: 
  589: If the failure happens when trying to build the "openssl" binary, with
  590: a large number of undefined symbols, it's very probable that you have
  591: OpenSSL 0.9.6b delivered with the operating system (you can find out by
  592: running '/usr/bin/openssl version') and that you were trying to build
  593: OpenSSL 0.9.7 or newer.  The problem is that the loader ('ld') in
  594: MacOS X has a misfeature that's quite difficult to go around.
  595: Look in the file PROBLEMS for a more detailed explanation and for possible
  596: solutions.
  597: 
  598: 
  599: * Why does the OpenSSL test suite fail on MacOS X?
  600: 
  601: If the failure happens when running 'make test' and the RC4 test fails,
  602: it's very probable that you have OpenSSL 0.9.6b delivered with the
  603: operating system (you can find out by running '/usr/bin/openssl version')
  604: and that you were trying to build OpenSSL 0.9.6d.  The problem is that
  605: the loader ('ld') in MacOS X has a misfeature that's quite difficult to
  606: go around and has linked the programs "openssl" and the test programs
  607: with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the
  608: libraries you just built.
  609: Look in the file PROBLEMS for a more detailed explanation and for possible
  610: solutions.
  611: 
  612: * Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]?
  613: 
  614: Failure in BN_sqr test is most likely caused by a failure to configure the
  615: toolkit for current platform or lack of support for the platform in question.
  616: Run './config -t' and './apps/openssl version -p'. Do these platform
  617: identifiers match? If they don't, then you most likely failed to run
  618: ./config and you're hereby advised to do so before filing a bug report.
  619: If ./config itself fails to run, then it's most likely problem with your
  620: local environment and you should turn to your system administrator (or
  621: similar). If identifiers match (and/or no alternative identifier is
  622: suggested by ./config script), then the platform is unsupported. There might
  623: or might not be a workaround. Most notably on SPARC64 platforms with GNU
  624: C compiler you should be able to produce a working build by running
  625: './config -m32'. I understand that -m32 might not be what you want/need,
  626: but the build should be operational. For further details turn to
  627: <openssl-dev@openssl.org>.
  628: 
  629: * Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"?
  630: 
  631: As of 0.9.7 assembler routines were overhauled for position independence
  632: of the machine code, which is essential for shared library support. For
  633: some reason OpenBSD is equipped with an out-of-date GNU assembler which
  634: finds the new code offensive. To work around the problem, configure with
  635: no-asm (and sacrifice a great deal of performance) or patch your assembler
  636: according to <URL: http://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>.
  637: For your convenience a pre-compiled replacement binary is provided at
  638: <URL: http://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>.
  639: Reportedly elder *BSD a.out platforms also suffer from this problem and
  640: remedy should be same. Provided binary is statically linked and should be
  641: working across wider range of *BSD branches, not just OpenBSD.
  642: 
  643: * Why does the OpenSSL test suite fail in sha512t on x86 CPU?
  644: 
  645: If the test program in question fails withs SIGILL, Illegal Instruction
  646: exception, then you more than likely to run SSE2-capable CPU, such as
  647: Intel P4, under control of kernel which does not support SSE2
  648: instruction extentions. See accompanying INSTALL file and
  649: OPENSSL_ia32cap(3) documentation page for further information.
  650: 
  651: * Why does compiler fail to compile sha512.c?
  652: 
  653: OpenSSL SHA-512 implementation depends on compiler support for 64-bit
  654: integer type. Few elder compilers [ULTRIX cc, SCO compiler to mention a
  655: couple] lack support for this and therefore are incapable of compiling
  656: the module in question. The recommendation is to disable SHA-512 by
  657: adding no-sha512 to ./config [or ./Configure] command line. Another
  658: possible alternative might be to switch to GCC.
  659: 
  660: * Test suite still fails, what to do?
  661: 
  662: Another common reason for failure to complete some particular test is
  663: simply bad code generated by a buggy component in toolchain or deficiency
  664: in run-time environment. There are few cases documented in PROBLEMS file,
  665: consult it for possible workaround before you beat the drum. Even if you
  666: don't find solution or even mention there, do reserve for possibility of
  667: a compiler bug. Compiler bugs might appear in rather bizarre ways, they
  668: never make sense, and tend to emerge when you least expect them. In order
  669: to identify one, drop optimization level, e.g. by editing CFLAG line in
  670: top-level Makefile, recompile and re-run the test.
  671: 
  672: [PROG] ========================================================================
  673: 
  674: * Is OpenSSL thread-safe?
  675: 
  676: Yes (with limitations: an SSL connection may not concurrently be used
  677: by multiple threads).  On Windows and many Unix systems, OpenSSL
  678: automatically uses the multi-threaded versions of the standard
  679: libraries.  If your platform is not one of these, consult the INSTALL
  680: file.
  681: 
  682: Multi-threaded applications must provide two callback functions to
  683: OpenSSL by calling CRYPTO_set_locking_callback() and
  684: CRYPTO_set_id_callback().  This is described in the threads(3)
  685: manpage.
  686: 
  687: * I've compiled a program under Windows and it crashes: why?
  688: 
  689: This is usually because you've missed the comment in INSTALL.W32.
  690: Your application must link against the same version of the Win32
  691: C-Runtime against which your openssl libraries were linked.  The
  692: default version for OpenSSL is /MD - "Multithreaded DLL".
  693: 
  694: If you are using Microsoft Visual C++'s IDE (Visual Studio), in
  695: many cases, your new project most likely defaulted to "Debug
  696: Singlethreaded" - /ML.  This is NOT interchangeable with /MD and your
  697: program will crash, typically on the first BIO related read or write
  698: operation.
  699: 
  700: For each of the six possible link stage configurations within Win32,
  701: your application must link  against the same by which OpenSSL was
  702: built.  If you are using MS Visual C++ (Studio) this can be changed
  703: by:
  704: 
  705:  1. Select Settings... from the Project Menu.
  706:  2. Select the C/C++ Tab.
  707:  3. Select "Code Generation from the "Category" drop down list box
  708:  4. Select the Appropriate library (see table below) from the "Use
  709:     run-time library" drop down list box.  Perform this step for both
  710:     your debug and release versions of your application (look at the
  711:     top left of the settings panel to change between the two)
  712: 
  713:     Single Threaded           /ML        -  MS VC++ often defaults to
  714:                                             this for the release
  715:                                             version of a new project.
  716:     Debug Single Threaded     /MLd       -  MS VC++ often defaults to
  717:                                             this for the debug version
  718:                                             of a new project.
  719:     Multithreaded             /MT
  720:     Debug Multithreaded       /MTd
  721:     Multithreaded DLL         /MD        -  OpenSSL defaults to this.
  722:     Debug Multithreaded DLL   /MDd
  723: 
  724: Note that debug and release libraries are NOT interchangeable.  If you
  725: built OpenSSL with /MD your application must use /MD and cannot use /MDd.
  726: 
  727: As per 0.9.8 the above limitation is eliminated for .DLLs. OpenSSL
  728: .DLLs compiled with some specific run-time option [we insist on the
  729: default /MD] can be deployed with application compiled with different
  730: option or even different compiler. But there is a catch! Instead of
  731: re-compiling OpenSSL toolkit, as you would have to with prior versions,
  732: you have to compile small C snippet with compiler and/or options of
  733: your choice. The snippet gets installed as
  734: <install-root>/include/openssl/applink.c and should be either added to
  735: your application project or simply #include-d in one [and only one]
  736: of your application source files. Failure to link this shim module
  737: into your application manifests itself as fatal "no OPENSSL_Applink"
  738: run-time error. An explicit reminder is due that in this situation
  739: [mixing compiler options] it is as important to add CRYPTO_malloc_init
  740: prior first call to OpenSSL.
  741: 
  742: * How do I read or write a DER encoded buffer using the ASN1 functions?
  743: 
  744: You have two options. You can either use a memory BIO in conjunction
  745: with the i2d_*_bio() or d2i_*_bio() functions or you can use the
  746: i2d_*(), d2i_*() functions directly. Since these are often the
  747: cause of grief here are some code fragments using PKCS7 as an example:
  748: 
  749:  unsigned char *buf, *p;
  750:  int len;
  751: 
  752:  len = i2d_PKCS7(p7, NULL);
  753:  buf = OPENSSL_malloc(len); /* or Malloc, error checking omitted */
  754:  p = buf;
  755:  i2d_PKCS7(p7, &p);
  756: 
  757: At this point buf contains the len bytes of the DER encoding of
  758: p7.
  759: 
  760: The opposite assumes we already have len bytes in buf:
  761: 
  762:  unsigned char *p;
  763:  p = buf;
  764:  p7 = d2i_PKCS7(NULL, &p, len);
  765: 
  766: At this point p7 contains a valid PKCS7 structure of NULL if an error
  767: occurred. If an error occurred ERR_print_errors(bio) should give more
  768: information.
  769: 
  770: The reason for the temporary variable 'p' is that the ASN1 functions
  771: increment the passed pointer so it is ready to read or write the next
  772: st