The branch master has been updated via 84a3418602e09d5592760621d3830880c0945ca6 (commit) from f40055ae5ffb492a800a430917b2b9cdd6901d03 (commit)
- Log ----------------------------------------------------------------- commit 84a3418602e09d5592760621d3830880c0945ca6 Author: Rich Salz <rs...@akamai.com> Date: Mon Jun 5 16:27:46 2017 -0400 Split FAQ source into pieces, rewrite mk-faq (Merged from https://github.com/openssl/web/pull/8) ----------------------------------------------------------------------- Summary of changes: Makefile | 4 +- bin/mk-faq | 171 ++++---- docs/faq-1-legal.txt | 28 ++ docs/faq-2-user.txt | 254 ++++++++++++ docs/faq-3-prog.txt | 285 ++++++++++++++ docs/faq-4-build.txt | 224 +++++++++++ docs/faq-5-misc.txt | 224 +++++++++++ docs/faq.txt | 1074 -------------------------------------------------- 8 files changed, 1093 insertions(+), 1171 deletions(-) create mode 100644 docs/faq-1-legal.txt create mode 100644 docs/faq-2-user.txt create mode 100644 docs/faq-3-prog.txt create mode 100644 docs/faq-4-build.txt create mode 100644 docs/faq-5-misc.txt delete mode 100644 docs/faq.txt diff --git a/Makefile b/Makefile index ec42096..34fedce 100644 --- a/Makefile +++ b/Makefile @@ -78,9 +78,9 @@ community/committers.inc: ./bin/mk-committers <Members >$@ @rm -f Members -docs/faq.inc: docs/faq.txt bin/mk-faq +docs/faq.inc: $(wildcard docs/faq-[0-9]-*.txt) bin/mk-faq @rm -f $@ - ./bin/mk-faq <$? >$@ + ./bin/mk-faq docs/faq-[0-9]-*txt >$@ docs/fips.inc: $(wildcard docs/fips/*) bin/mk-filelist @rm -f $@ ./bin/mk-filelist docs/fips fips/ '*' >$@ diff --git a/bin/mk-faq b/bin/mk-faq index 803d53a..001518b 100755 --- a/bin/mk-faq +++ b/bin/mk-faq @@ -1,107 +1,88 @@ -#! /usr/bin/perl -w +#! /usr/bin/perl use strict; +use warnings; -sub escape -{ - s/\&/\&/g; - s/\</\</g; - s/\>/\>/g; +# Filename->anchor name +my %anchors; +foreach my $f ( @ARGV ) { + next unless $f =~ /faq-[0-9]-(.*).txt/; + $anchors{$f} = uc($1); } -# TOC -my $l = ""; -my $n = 0; +my $top = ' <a href="#toc"><img src="/img/up.gif"/></a>'; print "<h3><a name='toc'>Table of Contents</a></h3>\n"; -my $dirty = 0; -while (<STDIN>) { - escape($_); - last if /^=+$/; - next if /^\w*$/; - if (/^\[([^\[]+)\] (.*)/) { - print "</ol>\n" if $dirty; - $l = $1; - $n = 0; - $dirty = 1; - print "<h4><a href=\"#$l\">$1</a> $2</h4>\n"; - print "<ol>\n"; - } elsif (/^\* (.*)/) { - $n++; - print "<li><a href=\"#$l$n\">$1</a></li>\n"; + +# Print the TOC +foreach my $f ( @ARGV ) { + my $a = $anchors{$f}; + open(IN, "<$f") || die "Can't open $f, $!"; + my $title = <IN>; + $title =~ s|\R$||; + print "\n <h4><a href='#$a'>$title</a></h4>\n"; + my $i = 1; + print " <ol>\n"; + while ( <IN> ) { + s|\R$||; + next unless /^\* /; + s/^\* //; + print " <li><a href='#$a$i'>$_</a></li>\n"; + $i++; } + print " </ol>\n"; + close(IN); } -print "</ol>\n" if $dirty; -# Contents -my $top = ' <a href="#toc"><img src="/img/up.gif"/></a>'; -$l = ""; -$n = 0; -my $pre = 0; -my $snip = 0; -while (<STDIN>) { - next if /^=+$/; - if (/^----- snip:start -----/) { - print "<pre>"; - $snip = 1; - next; - } - if ($snip) { - if (/^----- snip:end -----/) { - print "</pre>"; - $snip = 0; - } else { - escape($_); - print; - } - next; - } - if (/^ /) { - print "<pre>" unless $pre; - $pre = 1; - escape($_); - print; - next; - } - if ($pre) { - print "</pre>\n"; - $pre = 0; - } - if (/^$/) { - print "<p>"; - next; - } - if (/<URL:/ and not /<URL:.*>/) { - chomp; - $_ .= <STDIN>; - } - s/<URL: *(.*?)>/\@\@\@$1\@\@\@/; - escape($_); - s/\@\@\@(.*?)\@\@\@/<a href=\"$1\">$1<\/a>/; - if (s/\((.?)\)/XX$1XX/g) { - while (/([A-Za-z_\.]*)XX(.?)XX/) { - foreach my $section ("apps", "ssl", "crypto") { - if (-f "../docs/$section/$1.html") { - s|([A-Za-z_\.]*)XX(.?)XX|<a href=\"../docs/$section/$1.html\">$1($2)</a>|; - goto found; - } - } - s/XX(.?)XX/($1)/; - found: - } - } - if (/^\[([^\[]+)\] =+/) { - $l = $1; - $n = 0; - print "<hr>\n"; - print "<h3>[<a name=\"$l\">$1</a>] $top</h3>\n"; - } elsif (/^\* (.*)/) { - $n++; - print "\n<h4><a name=\"$l$n\">$n. $1</a>$top</h4>\n"; - } elsif (/^$/) { - print "<p>"; - } - else { - print; +# Print the contents. +foreach my $f ( @ARGV ) { + my $a = $anchors{$f}; + open(IN, "<$f") || die "Can't open $f, $!"; + my $title = <IN>; + $title =~ s|\R$||; + print "\n\n<hr>\n"; + print "<h3><a name='$a'>$title</a>$top</h3>\n"; + my $i = 1; + my $pre = 0; + while ( <IN> ) { + s|\R$||; + # Comments lines start with # + next if /^#/; + if ( /^\* / ) { + # New item: "* question text..." + s/\* //; + print "\n<h4><a name='$a$i'>$i. $_</a>$top</h4>\n"; + $i++; + } elsif ( m@<PRE>@i ) { + # Start of a <pre> section + die "Nested <PRE> in $f" if $pre != 0; + print "<pre>\n"; + $pre = 1; + } elsif ( m@</PRE>@i ) { + # End of a <pre> section + die "Unbalanced </PRE> in $f" if $pre != 1; + print "</pre>\n"; + $pre = 0; + } elsif ( $pre ) { + # If in <pre> state, just print + print "$_\n"; + } elsif ( /^$/ ) { + # Blank lines separate paragraphs + print "<p>\n"; + } elsif ( /(.*)@@@(.*)@@@(.*)/ ) { + # URL: @@@http:....@@@ + print "$1<a href='$2'>$2</a>$3\n"; + } elsif ( /(\w+)\((\d)\)/ ) { + # Manpage "foo(1)" + my ($page, $sec) = ($1, $2); + my $link = "/docs/manmaster/man$sec/$page.html"; + s|$page\($sec\)|<a href="$link">$page($sec)</a>|; + print "$_\n"; + } else { + # Ordinary line. + print "$_\n"; + } } + close(IN); + die "Unclosed <PRE> in $f" if $pre != 0; } exit(0); diff --git a/docs/faq-1-legal.txt b/docs/faq-1-legal.txt new file mode 100644 index 0000000..dc69809 --- /dev/null +++ b/docs/faq-1-legal.txt @@ -0,0 +1,28 @@ +Legal Questions + +* Do I need patent licenses to use OpenSSL? + +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 +<PRE> + ./config no-idea no-mdc2 no-rc5 +</PRE> + +* Can I use OpenSSL with GPL software? + +On many systems including the major Linux and BSD distributions, yes (the +GPL does not place restrictions on using libraries that are part of the +normal operating system distribution). + +On other systems, the situation is less clear. Some GPL software copyright +holders claim that you infringe on their rights if you use OpenSSL with +their software on operating systems that don't normally include OpenSSL. + +If you develop open source software that uses OpenSSL, you may find it +useful to choose an other license than the GPL, or state explicitly that +"This program is released under the GPL with the additional exemption that +compiling, linking, and/or using OpenSSL is allowed." If you are using +GPL software developed by others, you may want to ask the copyright holder +for permission to use their software with OpenSSL. diff --git a/docs/faq-2-user.txt b/docs/faq-2-user.txt new file mode 100644 index 0000000..fff3acc --- /dev/null +++ b/docs/faq-2-user.txt @@ -0,0 +1,254 @@ +Using the OpenSSL application + +* Why do I get a "PRNG not seeded" error message? + +Cryptographic software needs a source of unpredictable data to work +correctly. Many open source operating systems provide a "randomness +device" (/dev/urandom or /dev/random) that serves this purpose. +All OpenSSL versions try to use /dev/urandom by default; starting with +version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not +available. + +On other systems, applications have to call the RAND_add(3) or +RAND_seed(3) function with appropriate data before generating keys or +performing public key encryption. (These functions initialize the +pseudo-random number generator, PRNG.) Some broken applications do +not do this. As of version 0.9.5, the OpenSSL functions that need +randomness report an error if the random number generator has not been +seeded with at least 128 bits of randomness. If this error occurs and +is not discussed in the documentation of the application you are +using, please contact the author of that application; it is likely +that it never worked correctly. OpenSSL 0.9.5 and later make the +error visible by refusing to perform potentially insecure encryption. + +On systems without /dev/urandom and /dev/random, it is a good idea to +use the Entropy Gathering Demon (EGD); see the RAND_egd(3) manpage for +details. Starting with version 0.9.7, OpenSSL will automatically look +for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and +/etc/entropy. + +Most components of the openssl command line utility automatically try +to seed the random number generator from a file. The name of the +default seeding file is determined as follows: If environment variable +RANDFILE is set, then it names the seeding file. Otherwise if +environment variable HOME is set, then the seeding file is $HOME/.rnd. +If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will +use file .rnd in the current directory while OpenSSL 0.9.6a uses no +default seeding file at all. OpenSSL 0.9.6b and later will behave +similarly to 0.9.6a, but will use a default of "C:\" for HOME on +Windows systems if the environment variable has not been set. + +If the default seeding file does not exist or is too short, the "PRNG +not seeded" error message may occur. + +The openssl command line utility will write back a new state to the +default seeding file (and create this file if necessary) unless +there was no sufficient seeding. + +Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. +Use the "-rand" option of the OpenSSL command line tools instead. +The $RANDFILE environment variable and $HOME/.rnd are only used by the +OpenSSL command line tools. Applications using the OpenSSL library +provide their own configuration options to specify the entropy source, +please check out the documentation coming the with application. + +* Why do I get an "unable to write 'random state'" error message? + +Sometimes the openssl command line utility does not abort with +a "PRNG not seeded" error message, but complains that it is +"unable to write 'random state'". This message refers to the +default seeding file (see previous answer). A possible reason +is that no default filename is known because neither RANDFILE +nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the +current directory in this case, but this has changed with 0.9.6a.) + +* How do I create certificates or certificate requests? + +Check out the CA.pl(1) manual page. This provides a simple wrapper round +the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check +out the manual pages for the individual utilities and the certificate +extensions documentation (in ca(1), +req(1), +and x509v3_config(5) ). + +* Why can't I create certificate requests? + +You typically get the error: +<PRE> + unable to find 'distinguished_name' in config + problems making Certificate Request +</PRE> + +This is because it can't find the configuration file. Check out the +DIAGNOSTICS section of req(1) for more information. + +* Why does <SSL program> fail with a certificate verify error? + +This problem is usually indicated by log messages saying something like +"unable to get local issuer certificate" or "self signed certificate". +When a certificate is verified its root CA must be "trusted" by OpenSSL +this typically means that the CA certificate must be placed in a directory +or file and the relevant program configured to read it. The OpenSSL program +'verify' behaves in a similar way and issues similar error messages: check +the verify(1) program manual page for more information. + +* Why can I only use weak ciphers when I connect to a server using OpenSSL? + +This is almost certainly because you are using an old "export grade" browser +which only supports weak encryption. Upgrade your browser to support 128 bit +ciphers. + +* How can I create DSA certificates? + +Check the CA.pl(1) manual page for a DSA certificate example. + +* Why can't I make an SSL connection to a server using a DSA certificate? + +Typically you'll see a message saying there are no shared ciphers when +the same setup works fine with an RSA certificate. There are two possible +causes. The client may not support connections to DSA servers most web +browsers (including Netscape and MSIE) only support connections to servers +supporting RSA cipher suites. The other cause is that a set of DH parameters +has not been supplied to the server. DH parameters can be created with the +dhparam(1) command and loaded using the +SSL_CTX_set_tmp_dh(3) for example: +check the source to s_server in apps/s_server.c for an example. + +* How can I remove the passphrase on a private key? + +Firstly you should be really *really* sure you want to do this. Leaving +a private key unencrypted is a major security risk. If you decide that +you do have to do this check the EXAMPLES sections of the rsa(1) and +dsa(1) manual pages. + +* Why can't I use OpenSSL certificates with SSL client authentication? + +What will typically happen is that when a server requests authentication +it will either not include your certificate or tell you that you have +no client certificates (Netscape) or present you with an empty list box +(MSIE). The reason for this is that when a server requests a client +certificate it includes a list of CAs names which it will accept. Browsers +will only let you select certificates from the list on the grounds that +there is little point presenting a certificate which the server will +reject. + +The solution is to add the relevant CA certificate to your servers "trusted +CA list". How you do this depends on the server software in uses. You can +print out the servers list of acceptable CAs using the OpenSSL s_client tool: + +<PRE> + openssl s_client -connect www.some.host:443 -prexit +</PRE> + +If your server only requests certificates on certain URLs then you may need +to manually issue an HTTP GET command to get the list when s_client connects: + +<PRE> + GET /some/page/needing/a/certificate.html +</PRE> + +If your CA does not appear in the list then this confirms the problem. + +* Why does my browser give a warning about a mismatched hostname? + +Browsers expect the server's hostname to match the value in the commonName +(CN) field of the certificate. If it does not then you get a warning. + +* How do I install a CA certificate into a browser? + +The usual way is to send the DER encoded certificate to the browser as +MIME type application/x-x509-ca-cert, for example by clicking on an appropriate +link. On MSIE certain extensions such as .der or .cacert may also work, or you +can import the certificate using the certificate import wizard. + +You can convert a certificate to DER form using the command: + +openssl x509 -in ca.pem -outform DER -out ca.der + +Occasionally someone suggests using a command such as: + +openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem + +DO NOT DO THIS! This command will give away your CAs private key and +reduces its security to zero: allowing anyone to forge certificates in +whatever name they choose. + +* Why is OpenSSL x509 DN output not conformant to RFC2253? + +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(3) +interface, the "-nameopt" option could be introduced. See the manual +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? + +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 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 of the rules allowed the use of strong encryption but +only to an authorised server. + +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 +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. + +* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? + +It doesn't: this extension is often the cause of confusion. + +Consider a certificate chain A->B->C so that A signs B and B signs C. Suppose +certificate C contains AKID. + +The purpose of this extension is to identify the authority certificate B. This +can be done either by including the subject key identifier of B or its issuer +name and serial number. + +In this latter case because it is identifying certificate B it must contain the +issuer name and serial number of B. + +It is often wrongly assumed that it should contain the subject name of B. If it +did this would be redundant information because it would duplicate the issuer +name of C. + +* 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: +@@@https://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. diff --git a/docs/faq-3-prog.txt b/docs/faq-3-prog.txt new file mode 100644 index 0000000..f52c98f --- /dev/null +++ b/docs/faq-3-prog.txt @@ -0,0 +1,285 @@ +Programming with OpenSSL + +* Is OpenSSL thread-safe? + +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. + +To do this, your application must call CRYPTO_set_locking_callback(3) +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? + +This is usually because you've missed the comment in INSTALL.W32. +Your application must link against the same version of the Win32 +C-Runtime against which your openssl libraries were linked. The +default version for OpenSSL is /MD - "Multithreaded DLL". + +If you are using Microsoft Visual C++'s IDE (Visual Studio), in +many cases, your new project most likely defaulted to "Debug +Singlethreaded" - /ML. This is NOT interchangeable with /MD and your +program will crash, typically on the first BIO related read or write +operation. + +For each of the six possible link stage configurations within Win32, +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: + +<PRE> + 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) + + Single Threaded /ML - MS VC++ often defaults to + this for the release + version of a new project. + Debug Single Threaded /MLd - MS VC++ often defaults to + this for the debug version + of a new project. + Multithreaded /MT + Debug Multithreaded /MTd + Multithreaded DLL /MD - OpenSSL defaults to this. + Debug Multithreaded DLL /MDd +</PRE> + +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 +.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 +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? + +You have two options. You can either use a memory BIO in conjunction +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: + +<PRE> + unsigned char *buf, *p; + int len = i2d_PKCS7(p7, NULL); + + buf = OPENSSL_malloc(len); /* error checking omitted */ + p = buf; + i2d_PKCS7(p7, &p); +</PRE> + +At this point buf contains the len bytes of the DER encoding of p7. + +The opposite assumes we already have len bytes in buf: + +<PRE> + unsigned char *p = buf; + + p7 = d2i_PKCS7(NULL, &p, len); +</PRE> + +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. + +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. + +Memory allocation and encoding can also be combined in a single +operation by the ASN1 routines: + +<PRE> + 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); +</PRE> + +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? + +The short answer is yes, because DER is a special case of BER and OpenSSL +ASN1 decoders can process BER. + +The longer answer is that ASN1 structures can be encoded in a number of +different ways. One set of ways is the Basic Encoding Rules (BER) with various +permissible encodings. A restriction of BER is the Distinguished Encoding +Rules (DER): these uniquely specify how a given structure is encoded. + +Therefore, because DER is a special case of BER, DER is an acceptable encoding +for BER. + +* I've tried using <M_some_evil_pkcs12_macro> and I get errors why? + +This usually happens when you try compiling something using the PKCS12 +macros with a C++ compiler. There is hardly ever any need to use the +PKCS12 macros in a program, it is much easier to parse and create +PKCS12 files using the PKCS12_parse(3) +and PKCS12_create(3) 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 +should try to determine the cause. In particular, you should call +ERR_print_errors(3) +or ERR_print_errors_fp(3) after the failed call +and see if the message helps. Note that the problem may occur earlier +than you think -- you should check for errors after every call where +it is possible, otherwise the actual problem may be hidden because +some OpenSSL functions clear the error state. + +* I just get a load of numbers for the error output, what do they mean? + +The actual format is described in the ERR_print_errors(3) manual page. +You should call the function ERR_load_crypto_strings(3) before hand and +the message will be output in text form. If you can't do this (for example +it is a pre-compiled binary) you can use the errstr(1) utility on the error +code itself (the hex digits after the second colon). + +* Why do I get errors about unknown algorithms? + +The cause is forgetting to load OpenSSL's table of algorithms with +OpenSSL_add_all_algorithms(3). 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 PKCS12 file or signature failure when +verifying certificates. + +* Why can't the OpenSSH configure script detect OpenSSL? + +Several reasons for problems with the automatic detection exist. +OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. +Sometimes the distribution has installed an older version in the system +locations that is detected instead of a new one installed. The OpenSSL +library might have been compiled for another CPU or another mode (32/64 bits). +Permissions might be wrong. + +The general answer is to check the config.log file generated when running +the OpenSSH configure script. It should contain the detailed information +on why the OpenSSL library was not detected or considered incompatible. + +* Can I use OpenSSL's SSL library with non-blocking I/O? + +Yes; make sure to read the SSL_get_error(3) manual page! + +A pitfall to avoid: Don't assume that SSL_read(3) will just read from +the underlying transport or that SSL_write(3) will just write to it -- +it is also possible that SSL_write(3) cannot do any useful work until +there is data to read, or that SSL_read(3) cannot do anything until it +is possible to send data. One reason for this is that the peer may +request a new TLS/SSL handshake at any time during the protocol, +requiring a bi-directional message exchange; both SSL_read(3) and +SSL_write(3) will try to continue any pending handshake. + +* Why doesn't my server application receive a client certificate? + +Due to the TLS protocol definition, a client will only send a certificate, +if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the +SSL_CTX_set_verify(3) function to enable the use of client certificates. + +* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? + +For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier +versions, uniqueIdentifier was incorrectly used for X.509 certificates. +The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. +Change your code to use the new name when compiling against OpenSSL 0.9.7. + +* I think I've detected a memory leak, is this a bug? + +In most cases the cause of an apparent memory leak is an OpenSSL internal table +that is allocated when an application starts up. Since such tables do not grow +in size over time they are harmless. + +These internal tables can be freed up when an application closes using various +functions. Currently these include following: + +Thread-local cleanup functions include ERR_remove_state(3). +Application-global cleanup functions that are aware of usage (and therefore +thread-safe) include ENGINE_cleanup(3) +and CONF_modules_unload(3). +"Brutal" (thread-unsafe) Application-global cleanup functions include: +ERR_free_strings(3), +EVP_cleanup(3) +and CRYPTO_cleanup_all_ex_data(3). + +* Why doesn't a memory BIO work when a file does? + +This can occur in several cases for example reading an S/MIME email message. +The reason is that a memory BIO can do one of two things when all the data +has been read from it. + +The default behaviour is to indicate that no more data is available and that +the call should be retried, this is to allow the application to fill up the BIO +again if necessary. + +Alternatively it can indicate that no more data is available and that EOF has +been reached. + +If a memory BIO is to behave in the same way as a file this second behaviour +is needed. This must be done by calling: + +<PRE> + BIO_set_mem_eof_return(bio, 0); +</PRE> + +See the manual pages for more details. + +* Where are the declarations and implementations of d2i_X509(3) etc? + +These are defined and implemented by macros of the form: + +<PRE> + DECLARE_ASN1_FUNCTIONS(X509) and + IMPLEMENT_ASN1_FUNCTIONS(X509) +</PRE> + +The implementation passes an ASN1 "template" defining the structure into an +ASN1 interpreter using generalised functions such as ASN1_item_d2i(3). + +* 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. diff --git a/docs/faq-4-build.txt b/docs/faq-4-build.txt new file mode 100644 index 0000000..bb39699 --- /dev/null +++ b/docs/faq-4-build.txt @@ -0,0 +1,224 @@ +Questions on Building and Testing OpenSSL + +* Why does Clang sanitizer give warnings? + +You need to build with -DPEDANTIC to run sanitized tests, otherwise +you will get optimized assembler versions of some functions. + +* Why does the linker complain about undefined symbols? + +Maybe the compilation was interrupted, and make doesn't notice that +something is missing. Run "make clean; make". + +If you used ./Configure instead of ./config, make sure that you +selected the right target. File formats may differ slightly between +OS versions (for example sparcv8/sparcv9, or a.out/elf). + +In case you get errors about the following symbols, use the config +option "no-asm", as described in INSTALL: + +<PRE> + BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, + CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, + RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, + bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, + bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, + des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, + des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order +</PRE> + +If none of these helps, you may want to try using the current snapshot. +If the problem persists, please submit a bug report. + +* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? + +On some Alpha installations running Tru64 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 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: + +<PRE> + make DIRS=crypto SDIRS=sha "`grep '^CFLAG=' Makefile.ssl | \ + sed -e 's/ -O[0-9] / -O0 /'`" + rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` + make +</PRE> + +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. + +3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It +should not be used and is not used in SSL/TLS nor any other recognized +protocol in either case. + +* 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): + +<PRE> + PATH=${PATH}:/usr/ccs/bin; export PATH +</PRE> + +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). + +* Why does the OpenSSL compilation fail on Win32 with VC++? + +Sometimes, you may get reports from VC++ command line (cl) that it +can't find standard include files like stdio.h and other weirdnesses. +One possible cause is that the environment isn't correctly set up. +To solve that problem for VC++ versions up to 6, one should run +VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ +installation directory (somewhere under 'Program Files'). For VC++ +version 7 (and up?), which is also called VS.NET, the file is called +VSVARS32.BAT instead. +This needs to be done prior to running NMAKE, and the changes are only +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. 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 +/usr/bin on your Red Hat machine. Several packages depend on this file, +including sendmail and ssh. /usr/local/bin is a good alternative choice. The +libraries that come with Red Hat 7.0 onwards have different names and so are +not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and +/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and +/lib/libcrypto.so.2 respectively). + +Please note that we have been advised by Red Hat attempting to recompile the +openssl rpm with all the cryptography enabled will not work. All other +packages depend on the original Red Hat supplied openssl package. It is also +worth noting that due to the way Red Hat supplies its packages, updates to +openssl on each distribution never change the package version, only the +build number. For example, on Red Hat 7.1, the latest openssl package has +version number 0.9.6 and build number 9 even though it contains all the +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. + +* Why does the OpenSSL compilation fail on MacOS X? + +If the failure happens when trying to build the "openssl" binary, with +a large number of undefined symbols, it's very probable that you have +OpenSSL 0.9.6b delivered with the operating system (you can find out by +running '/usr/bin/openssl version') and that you were trying to build +OpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in +MacOS X has a misfeature that's quite difficult to go around. +Look in the file PROBLEMS for a more detailed explanation and for possible +solutions. + +* Why does the OpenSSL test suite fail on MacOS X? + +If the failure happens when running 'make test' and the RC4 test fails, +it's very probable that you have OpenSSL 0.9.6b delivered with the +operating system (you can find out by running '/usr/bin/openssl version') +and that you were trying to build OpenSSL 0.9.6d. The problem is that +the loader ('ld') in MacOS X has a misfeature that's quite difficult to +go around and has linked the programs "openssl" and the test programs +with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the +libraries you just built. +Look in the file PROBLEMS for a more detailed explanation and for possible +solutions. + +* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? + +Failure in BN_sqr test is most likely caused by a failure to configure the +toolkit for current platform or lack of support for the platform in question. +Run './config -t' and './apps/openssl version -p'. Do these platform +identifiers match? If they don't, then you most likely failed to run +./config and you're hereby advised to do so before filing a bug report. +If ./config itself fails to run, then it's most likely problem with your +local environment and you should turn to your system administrator (or +similar). If identifiers match (and/or no alternative identifier is +suggested by ./config script), then the platform is unsupported. There might +or might not be a workaround. Most notably on SPARC64 platforms with GNU +C compiler you should be able to produce a working build by running +'./config -m32'. I understand that -m32 might not be what you want/need, +but the build should be operational. For further details turn to +@@@mailto:openssl-...@openssl.org@@@ + +* Why does the OpenSSL test suite fail in sha512t on x86 CPU? + +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 extensions. See accompanying INSTALL file and +OPENSSL_ia32cap(3) documentation page for further information. + +* Why does compiler fail to compile sha512.c? + +OpenSSL SHA-512 implementation depends on compiler support for 64-bit +integer type. Few elder compilers [ULTRIX cc, SCO compiler to mention a +couple] lack support for this and therefore are incapable of compiling +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. + +* Test suite still fails, what to do? + +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? + +If you are a new user then it is quite likely you haven't found a bug and +something is happening you aren't familiar with. Check this FAQ, the associated +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? + +Please see @@@https://www.openssl.org/community@@@. + +* I've found a security issue, how do I report it? + +If you think your bug has security implications then please send it to +openssl-secur...@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). If you wish to use PGP to send +in a report please use one or more of the keys of the OMC listed +at @@@https://www.openssl.org/community/omc.html@@@. + +Note that bugs only present in the openssl utility are not in general +considered to be security issues. diff --git a/docs/faq-5-misc.txt b/docs/faq-5-misc.txt new file mode 100644 index 0000000..c3151e1 --- /dev/null +++ b/docs/faq-5-misc.txt @@ -0,0 +1,224 @@ +Miscellaneous + +* Which is the current version of OpenSSL? +Miscellaneous + +* Which is the current version of OpenSSL? + +The current version is available from @@@https://www.openssl.org@@@. + +In addition to the current stable release, you can also access daily +snapshots of the OpenSSL development version at +@@@https://www.openssl.org/source/snapshot/@@@, +or get it by anonymous Git access. + +* Where is the documentation? + +OpenSSL is a library that provides cryptographic functionality to +applications such as secure web servers. Be sure to read the +documentation of the application you want to use. The INSTALL file +explains how to install this library. + +OpenSSL includes a command line utility that can be used to perform a +variety of cryptographic functions. It is described in the openssl(1) +manpage. Documentation for developers is currently being written. Many +manual pages are available; overviews of libcrypto and +libssl are given in the crypto(7) and +ssl(7) manpages. + +The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a +different directory if you specified one as described in INSTALL). +In addition, you can read the most current versions at +@@@https://www.openssl.org/docs/@@@. Note that the online documents refer +to the very latest development versions of OpenSSL and may include features +not present in released versions. If in doubt refer to the documentation +that came with the version of OpenSSL you are using. The pod format +documentation is included in each OpenSSL distribution under the docs +directory. + +* How can I contact the OpenSSL developers? + +The README file describes how to submit bug reports and patches to +OpenSSL. Information on the OpenSSL mailing lists is available from +@@@https://www.openssl.org/community/mailinglists.html@@@. + +* Where can I get a compiled version of OpenSSL? + +You can finder pointers to binary distributions in +@@@https://www.openssl.org/community/binaries.html@@@ . + +Some applications that use OpenSSL are distributed in binary form. +When using such an application, you don't need to install OpenSSL +yourself; the application will include the required parts (e.g. DLLs). + +If you want to build OpenSSL on a Windows system and you don't have +a C compiler, read the "Mingw32" section of INSTALL.W32 for information +on how to obtain and install the free GNU C compiler. + +A number of Linux and *BSD distributions include OpenSSL. + +* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? + +A number of these tools are great and wonderful, but are usually +centered around one or a few platforms. 'autoconf' and 'libtool' are +Unix centric. 'cmake' is a bit more widely spread, but not enough to +cover the platforms we support. + +For OpenSSL 1.1, we decided to base our build system on perl, +information files and build file (Makefile) templates, thereby +covering all the systems we support. Perl was the base language of +choice because we already use it in diverse scripts, and it's one of +the most widely spread scripting languages. + +* What is an 'engine' version? + +With version 0.9.6 OpenSSL was extended to interface to external crypto +hardware. This was realized in a special release '0.9.6-engine'. With +version 0.9.7 the changes were merged into the main development line, +so that the special release is no longer necessary. + +* How do I check the authenticity of the OpenSSL distribution? + +We provide PGP signatures and a variety of digests on each release. +For example, one of the following might work on your system: + +<PRE> + sha1sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha1 + sha256sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha256 +</PRE> + +You can check authenticity using pgp or gpg. You need the OpenSSL OMC +member public key used to sign it (download it from a key server or see a +list of keys at @@@https://www.openssl.org/community/omc.html@@@). Then +just do: + +<PRE> + pgp TARBALL.asc +</PRE> + +* How does the versioning scheme work? + +After the release of OpenSSL 1.0.0 the versioning scheme changed. Letter +releases (e.g. 1.0.1a) can only contain bug and security fixes and no +new features. Minor releases change the last number (e.g. 1.0.2) and +can contain new features that retain binary compatibility. Changes to +the middle number are considered major releases and neither source nor +binary compatibility is guaranteed. + +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. + +The current version is available from @@@https://www.openssl.org@@@. + +In addition to the current stable release, you can also access daily +snapshots of the OpenSSL development version at +@@@https://www.openssl.org/source/snapshot/@@@, or get +it by anonymous Git access. + +* Where is the documentation? + +OpenSSL is a library that provides cryptographic functionality to +applications such as secure web servers. Be sure to read the +documentation of the application you want to use. The INSTALL file +explains how to install this library. + +OpenSSL includes a command line utility that can be used to perform a +variety of cryptographic functions. It is described in the openssl(1) +manpage. Documentation for developers is currently being written. Many +manual pages are available; overviews over libcrypto and +libssl are given in the crypto(7) +and ssl(7) manpages. + +The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a +different directory if you specified one as described in INSTALL). +In addition, you can read the most current versions at +@@@https://www.openssl.org/docs/@@@. Note that the online documents refer +to the very latest development versions of OpenSSL and may include features +not present in released versions. If in doubt refer to the documentation +that came with the version of OpenSSL you are using. The pod format +documentation is included in each OpenSSL distribution under the docs +directory. + +* How can I contact the OpenSSL developers? + +The README file describes how to submit bug reports and patches to +OpenSSL. Information on the OpenSSL mailing lists is available from +@@@https://www.openssl.org/community/mailinglists.html@@@. + +* Where can I get a compiled version of OpenSSL? + +You can finder pointers to binary distributions in +@@@https://www.openssl.org/community/binaries.html@@@. + +Some applications that use OpenSSL are distributed in binary form. +When using such an application, you don't need to install OpenSSL +yourself; the application will include the required parts (e.g. DLLs). + +If you want to build OpenSSL on a Windows system and you don't have +a C compiler, read the "Mingw32" section of INSTALL.W32 for information +on how to obtain and install the free GNU C compiler. + +A number of Linux and *BSD distributions include OpenSSL. + +* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? + +A number of these tools are great and wonderful, but are usually +centered around one or a few platforms. 'autoconf' and 'libtool' are +Unix centric. 'cmake' is a bit more widely spread, but not enough to +cover the platforms we support. + +For OpenSSL 1.1, we decided to base our build system on perl, +information files and build file (Makefile) templates, thereby +covering all the systems we support. Perl was the base language of +choice because we already use it in diverse scripts, and it's one of +the most widely spread scripting languages. + +* What is an 'engine' version? + +With version 0.9.6 OpenSSL was extended to interface to external crypto +hardware. This was realized in a special release '0.9.6-engine'. With +version 0.9.7 the changes were merged into the main development line, +so that the special release is no longer necessary. + +* How do I check the authenticity of the OpenSSL distribution? + +We provide PGP signatures and a variety of digests on each release. +For example, one of the following might work on your system: + +<PRE> + sha1sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha1 + sha256sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha256 +</PRE> + +You can check authenticity using pgp or gpg. You need the OpenSSL OMC +member public key used to sign it (download it from a key server or see a +list of keys at @@@https://www.openssl.org/community/omc.html@@@). Then +just do: + +<PRE> + pgp TARBALL.asc +</PRE> + +* How does the versioning scheme work? + +After the release of OpenSSL 1.0.0 the versioning scheme changed. Letter +releases (e.g. 1.0.1a) can only contain bug and security fixes and no +new features. Minor releases change the last number (e.g. 1.0.2) and +can contain new features that retain binary compatibility. Changes to +the middle number are considered major releases and neither source nor +binary compatibility is guaranteed. + +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. diff --git a/docs/faq.txt b/docs/faq.txt deleted file mode 100644 index 172eb43..0000000 --- a/docs/faq.txt +++ /dev/null @@ -1,1074 +0,0 @@ -OpenSSL - Frequently Asked Questions --------------------------------------- - -[MISC] Miscellaneous questions - -* Which is the current version of OpenSSL? -* Where is the documentation? -* How can I contact the OpenSSL developers? -* Where can I get a compiled version of OpenSSL? -* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? -* What is an 'engine' version? -* How do I check the authenticity of the OpenSSL distribution? -* How does the versioning scheme work? - -[LEGAL] Legal questions - -* Do I need patent licenses to use OpenSSL? -* Can I use OpenSSL with GPL software? - -[USER] Questions on using the OpenSSL applications - -* Why do I get a "PRNG not seeded" error message? -* Why do I get an "unable to write 'random state'" error message? -* How do I create certificates or certificate requests? -* Why can't I create certificate requests? -* Why does <SSL program> fail with a certificate verify error? -* Why can I only use weak ciphers when I connect to a server using OpenSSL? -* How can I create DSA certificates? -* Why can't I make an SSL connection using a DSA certificate? -* How can I remove the passphrase on a private key? -* Why can't I use OpenSSL certificates with SSL client authentication? -* 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? -* 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 - -* Why does Clang sanitizer give warnings? -* Why does the linker complain about undefined symbols? -* 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 test fail with "bc: stack empty"? -* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? -* Why does the OpenSSL compilation fail with "ar: command not found"? -* Why does the OpenSSL compilation fail on Win32 with VC++? -* What is special about OpenSSL on Redhat? -* Why does the OpenSSL compilation fail on MacOS X? -* Why does the OpenSSL test suite fail on MacOS X? -* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? -* 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? -* I think I've found a bug, what should I do? -* I'm SURE I've found a bug, how do I report it? -* I've found a security issue, how do I report it? - -[PROG] Questions about programming with OpenSSL - -* Is OpenSSL thread-safe? -* 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? -* OpenSSL uses DER but I need BER format: does OpenSSL support BER? -* 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? -* Why can't the OpenSSH configure script detect OpenSSL? -* Can I use OpenSSL's SSL library with non-blocking I/O? -* 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? -* 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? - -=============================================================================== - -[MISC] ======================================================================== - -* Which is the current version of OpenSSL? - -The current version is available from <URL: https://www.openssl.org>. - -In addition to the current stable release, you can also access daily -snapshots of the OpenSSL development version at <URL: -https://www.openssl.org/source/snapshot/>, or get it by anonymous Git access. - - -* Where is the documentation? - -OpenSSL is a library that provides cryptographic functionality to -applications such as secure web servers. Be sure to read the -documentation of the application you want to use. The INSTALL file -explains how to install this library. - -OpenSSL includes a command line utility that can be used to perform a -variety of cryptographic functions. It is described in the openssl(1) -manpage. Documentation for developers is currently being written. Many -manual pages are available; overviews over libcrypto and -libssl are given in the crypto(3) and ssl(3) manpages. - -The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a -different directory if you specified one as described in INSTALL). -In addition, you can read the most current versions at -<URL: https://www.openssl.org/docs/>. Note that the online documents refer -to the very latest development versions of OpenSSL and may include features -not present in released versions. If in doubt refer to the documentation -that came with the version of OpenSSL you are using. The pod format -documentation is included in each OpenSSL distribution under the docs -directory. - - -* How can I contact the OpenSSL developers? - -The README file describes how to submit bug reports and patches to -OpenSSL. Information on the OpenSSL mailing lists is available from -<URL: https://www.openssl.org/community/mailinglists.html>. - - -* Where can I get a compiled version of OpenSSL? - -You can finder pointers to binary distributions in -<URL: https://www.openssl.org/community/binaries.html> . - -Some applications that use OpenSSL are distributed in binary form. -When using such an application, you don't need to install OpenSSL -yourself; the application will include the required parts (e.g. DLLs). - -If you want to build OpenSSL on a Windows system and you don't have -a C compiler, read the "Mingw32" section of INSTALL.W32 for information -on how to obtain and install the free GNU C compiler. - -A number of Linux and *BSD distributions include OpenSSL. - - -* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? - -A number of these tools are great and wonderful, but are usually -centered around one or a few platforms. 'autoconf' and 'libtool' are -Unix centric. 'cmake' is a bit more widely spread, but not enough to -cover the platforms we support. - -For OpenSSL 1.1, we decided to base our build system on perl, -information files and build file (Makefile) templates, thereby -covering all the systems we support. Perl was the base language of -choice because we already use it in diverse scripts, and it's one of -the most widely spread scripting languages. - - -* What is an 'engine' version? - -With version 0.9.6 OpenSSL was extended to interface to external crypto -hardware. This was realized in a special release '0.9.6-engine'. With -version 0.9.7 the changes were merged into the main development line, -so that the special release is no longer necessary. - -* How do I check the authenticity of the OpenSSL distribution? - -We provide PGP signatures and a variety of digests on each release. -For example, one of the following might work on your system: - - sha1sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha1 - sha256sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha256 - -You can check authenticity using pgp or gpg. You need the OpenSSL OMC -member public key used to sign it (download it from a key server or see a -list of keys at <URL: https://www.openssl.org/community/omc.html>). Then -just do: - - pgp TARBALL.asc - -* How does the versioning scheme work? - -After the release of OpenSSL 1.0.0 the versioning scheme changed. Letter -releases (e.g. 1.0.1a) can only contain bug and security fixes and no -new features. Minor releases change the last number (e.g. 1.0.2) and -can contain new features that retain binary compatibility. Changes to -the middle number are considered major releases and neither source nor -binary compatibility is guaranteed. - -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? - -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 - - -* Can I use OpenSSL with GPL software? - -On many systems including the major Linux and BSD distributions, yes (the -GPL does not place restrictions on using libraries that are part of the -normal operating system distribution). - -On other systems, the situation is less clear. Some GPL software copyright -holders claim that you infringe on their rights if you use OpenSSL with -their software on operating systems that don't normally include OpenSSL. - -If you develop open source software that uses OpenSSL, you may find it -useful to choose an other license than the GPL, or state explicitly that -"This program is released under the GPL with the additional exemption that -compiling, linking, and/or using OpenSSL is allowed." If you are using -GPL software developed by others, you may want to ask the copyright holder -for permission to use their software with OpenSSL. - - -[USER] ======================================================================== - -* Why do I get a "PRNG not seeded" error message? - -Cryptographic software needs a source of unpredictable data to work -correctly. Many open source operating systems provide a "randomness -device" (/dev/urandom or /dev/random) that serves this purpose. -All OpenSSL versions try to use /dev/urandom by default; starting with -version 0.9.7, OpenSSL also tries /dev/random if /dev/urandom is not -available. - -On other systems, applications have to call the RAND_add() or -RAND_seed() function with appropriate data before generating keys or -performing public key encryption. (These functions initialize the -pseudo-random number generator, PRNG.) Some broken applications do -not do this. As of version 0.9.5, the OpenSSL functions that need -randomness report an error if the random number generator has not been -seeded with at least 128 bits of randomness. If this error occurs and -is not discussed in the documentation of the application you are -using, please contact the author of that application; it is likely -that it never worked correctly. OpenSSL 0.9.5 and later make the -error visible by refusing to perform potentially insecure encryption. - -If you are using Solaris 8, you can add /dev/urandom and /dev/random -devices by installing patch 112438 (Sparc) or 112439 (x86), which are -available via the Patchfinder at <URL: http://sunsolve.sun.com> -(Solaris 9 includes these devices by default). For /dev/random support -for earlier Solaris versions, see Sun's statement at -<URL: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsrdb/27606&zone_32=SUNWski> -(the SUNWski package is available in patch 105710). - -On systems without /dev/urandom and /dev/random, it is a good idea to -use the Entropy Gathering Demon (EGD); see the RAND_egd() manpage for -details. Starting with version 0.9.7, OpenSSL will automatically look -for an EGD socket at /var/run/egd-pool, /dev/egd-pool, /etc/egd-pool and -/etc/entropy. - -Most components of the openssl command line utility automatically try -to seed the random number generator from a file. The name of the -default seeding file is determined as follows: If environment variable -RANDFILE is set, then it names the seeding file. Otherwise if -environment variable HOME is set, then the seeding file is $HOME/.rnd. -If neither RANDFILE nor HOME is set, versions up to OpenSSL 0.9.6 will -use file .rnd in the current directory while OpenSSL 0.9.6a uses no -default seeding file at all. OpenSSL 0.9.6b and later will behave -similarly to 0.9.6a, but will use a default of "C:\" for HOME on -Windows systems if the environment variable has not been set. - -If the default seeding file does not exist or is too short, the "PRNG -not seeded" error message may occur. - -The openssl command line utility will write back a new state to the -default seeding file (and create this file if necessary) unless -there was no sufficient seeding. - -Pointing $RANDFILE to an Entropy Gathering Daemon socket does not work. -Use the "-rand" option of the OpenSSL command line tools instead. -The $RANDFILE environment variable and $HOME/.rnd are only used by the -OpenSSL command line tools. Applications using the OpenSSL library -provide their own configuration options to specify the entropy source, -please check out the documentation coming the with application. - - -* Why do I get an "unable to write 'random state'" error message? - - -Sometimes the openssl command line utility does not abort with -a "PRNG not seeded" error message, but complains that it is -"unable to write 'random state'". This message refers to the -default seeding file (see previous answer). A possible reason -is that no default filename is known because neither RANDFILE -nor HOME is set. (Versions up to 0.9.6 used file ".rnd" in the -current directory in this case, but this has changed with 0.9.6a.) - - -* How do I create certificates or certificate requests? - -Check out the CA.pl(1) manual page. This provides a simple wrapper round -the 'req', 'verify', 'ca' and 'pkcs12' utilities. For finer control check -out the manual pages for the individual utilities and the certificate -extensions documentation (in ca(1), req(1), x509v3_config(5) ) - - -* Why can't I create certificate requests? - -You typically get the error: - - unable to find 'distinguished_name' in config - problems making Certificate Request - -This is because it can't find the configuration file. Check out the -DIAGNOSTICS section of req(1) for more information. - - -* Why does <SSL program> fail with a certificate verify error? - -This problem is usually indicated by log messages saying something like -"unable to get local issuer certificate" or "self signed certificate". -When a certificate is verified its root CA must be "trusted" by OpenSSL -this typically means that the CA certificate must be placed in a directory -or file and the relevant program configured to read it. The OpenSSL program -'verify' behaves in a similar way and issues similar error messages: check -the verify(1) program manual page for more information. - - -* Why can I only use weak ciphers when I connect to a server using OpenSSL? - -This is almost certainly because you are using an old "export grade" browser -which only supports weak encryption. Upgrade your browser to support 128 bit -ciphers. - - -* How can I create DSA certificates? - -Check the CA.pl(1) manual page for a DSA certificate example. - - -* Why can't I make an SSL connection to a server using a DSA certificate? - -Typically you'll see a message saying there are no shared ciphers when -the same setup works fine with an RSA certificate. There are two possible -causes. The client may not support connections to DSA servers most web -browsers (including Netscape and MSIE) only support connections to servers -supporting RSA cipher suites. The other cause is that a set of DH parameters -has not been supplied to the server. DH parameters can be created with the -dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh() for example: -check the source to s_server in apps/s_server.c for an example. - - -* How can I remove the passphrase on a private key? - -Firstly you should be really *really* sure you want to do this. Leaving -a private key unencrypted is a major security risk. If you decide that -you do have to do this check the EXAMPLES sections of the rsa(1) and -dsa(1) manual pages. - - -* Why can't I use OpenSSL certificates with SSL client authentication? - -What will typically happen is that when a server requests authentication -it will either not include your certificate or tell you that you have -no client certificates (Netscape) or present you with an empty list box -(MSIE). The reason for this is that when a server requests a client -certificate it includes a list of CAs names which it will accept. Browsers -will only let you select certificates from the list on the grounds that -there is little point presenting a certificate which the server will -reject. - -The solution is to add the relevant CA certificate to your servers "trusted -CA list". How you do this depends on the server software in uses. You can -print out the servers list of acceptable CAs using the OpenSSL s_client tool: - -openssl s_client -connect www.some.host:443 -prexit - -If your server only requests certificates on certain URLs then you may need -to manually issue an HTTP GET command to get the list when s_client connects: - -GET /some/page/needing/a/certificate.html - -If your CA does not appear in the list then this confirms the problem. - - -* Why does my browser give a warning about a mismatched hostname? - -Browsers expect the server's hostname to match the value in the commonName -(CN) field of the certificate. If it does not then you get a warning. - - -* How do I install a CA certificate into a browser? - -The usual way is to send the DER encoded certificate to the browser as -MIME type application/x-x509-ca-cert, for example by clicking on an appropriate -link. On MSIE certain extensions such as .der or .cacert may also work, or you -can import the certificate using the certificate import wizard. - -You can convert a certificate to DER form using the command: - -openssl x509 -in ca.pem -outform DER -out ca.der - -Occasionally someone suggests using a command such as: - -openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem - -DO NOT DO THIS! This command will give away your CAs private key and -reduces its security to zero: allowing anyone to forge certificates in -whatever name they choose. - -* Why is OpenSSL x509 DN output not conformant to RFC2253? - -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 introduced. See the manual -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? - -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 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 of the rules allowed the use of strong encryption but -only to an authorised server. - -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 -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. - - -* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? - -It doesn't: this extension is often the cause of confusion. - -Consider a certificate chain A->B->C so that A signs B and B signs C. Suppose -certificate C contains AKID. - -The purpose of this extension is to identify the authority certificate B. This -can be done either by including the subject key identifier of B or its issuer -name and serial number. - -In this latter case because it is identifying certificate B it must contain the -issuer name and serial number of B. - -It is often wrongly assumed that it should contain the subject name of B. If it -did this would be redundant information because it would duplicate the issuer -name of C. - - -* 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: -<URL: https://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: https://rt.openssl.org/Ticket/Display.html?user=guest&pass=guest&id=2771> - - -[BUILD] ======================================================================= - -* Why does Clang sanitizer give warnings? - -You need to build with -DPEDANTIC to run sanitized tests, otherwise -you will get optimized assembler versions of some functions. - -* Why does the linker complain about undefined symbols? - -Maybe the compilation was interrupted, and make doesn't notice that -something is missing. Run "make clean; make". - -If you used ./Configure instead of ./config, make sure that you -selected the right target. File formats may differ slightly between -OS versions (for example sparcv8/sparcv9, or a.out/elf). - -In case you get errors about the following symbols, use the config -option "no-asm", as described in INSTALL: - - BF_cbc_encrypt, BF_decrypt, BF_encrypt, CAST_cbc_encrypt, - CAST_decrypt, CAST_encrypt, RC4, RC5_32_cbc_encrypt, RC5_32_decrypt, - RC5_32_encrypt, bn_add_words, bn_div_words, bn_mul_add_words, - bn_mul_comba4, bn_mul_comba8, bn_mul_words, bn_sqr_comba4, - bn_sqr_comba8, bn_sqr_words, bn_sub_words, des_decrypt3, - des_ede3_cbc_encrypt, des_encrypt, des_encrypt2, des_encrypt3, - des_ncbc_encrypt, md5_block_asm_host_order, sha1_block_asm_data_order - -If none of these helps, you may want to try using the current snapshot. -If the problem persists, please submit a bug report. - - -* Why does the OpenSSL test fail with "bc: command not found"? - -You didn't install "bc", the Unix calculator. If you want to run the -tests, get GNU bc from ftp://ftp.gnu.org or from your OS distributor. - - -* Why does the OpenSSL test fail with "bc: 1 no implemented"? - -On some SCO installations or versions, bc has a bug that gets triggered -when you run the test suite (using "make test"). The message returned is -"bc: 1 not implemented". - -The best way to deal with this is to find another implementation of bc -and compile/install it. GNU bc (see <URL: https://www.gnu.org/software/software.html> -for download instructions) can be safely used, for example. - - -* Why does the OpenSSL test fail with "bc: stack empty"? - -On some DG/ux versions, bc seems to have a too small stack for calculations -that the OpenSSL bntest throws at it. This gets triggered when you run the -test suite (using "make test"). The message returned is "bc: stack empty". - -The best way to deal with this is to find another implementation of bc -and compile/install it. GNU bc (see <URL: https://www.gnu.org/software/software.html> -for download instructions) can be safely used, for example. - - -* Why does the OpenSSL compilation fail on Alpha Tru64 Unix? - -On some Alpha installations running Tru64 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 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 | \ - sed -e 's/ -O[0-9] / -O0 /'`" - rm `ls crypto/*.o crypto/sha/*.o | grep -v 'sha_dgst\.o'` - make ------ snip:end ----- - -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. - -3. Reconfigure the toolkit with no-sha0 option to leave out SHA0. It -should not be used and is not used in SSL/TLS nor any other recognized -protocol in either case. - - -* 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). - - -* Why does the OpenSSL compilation fail on Win32 with VC++? - -Sometimes, you may get reports from VC++ command line (cl) that it -can't find standard include files like stdio.h and other weirdnesses. -One possible cause is that the environment isn't correctly set up. -To solve that problem for VC++ versions up to 6, one should run -VCVARS32.BAT which is found in the 'bin' subdirectory of the VC++ -installation directory (somewhere under 'Program Files'). For VC++ -version 7 (and up?), which is also called VS.NET, the file is called -VSVARS32.BAT instead. -This needs to be done prior to running NMAKE, and the changes are only -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. 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 -/usr/bin on your Red Hat machine. Several packages depend on this file, -including sendmail and ssh. /usr/local/bin is a good alternative choice. The -libraries that come with Red Hat 7.0 onwards have different names and so are -not affected. (eg For Red Hat 7.2 they are /lib/libssl.so.0.9.6b and -/lib/libcrypto.so.0.9.6b with symlinks /lib/libssl.so.2 and -/lib/libcrypto.so.2 respectively). - -Please note that we have been advised by Red Hat attempting to recompile the -openssl rpm with all the cryptography enabled will not work. All other -packages depend on the original Red Hat supplied openssl package. It is also -worth noting that due to the way Red Hat supplies its packages, updates to -openssl on each distribution never change the package version, only the -build number. For example, on Red Hat 7.1, the latest openssl package has -version number 0.9.6 and build number 9 even though it contains all the -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. - - -* Why does the OpenSSL compilation fail on MacOS X? - -If the failure happens when trying to build the "openssl" binary, with -a large number of undefined symbols, it's very probable that you have -OpenSSL 0.9.6b delivered with the operating system (you can find out by -running '/usr/bin/openssl version') and that you were trying to build -OpenSSL 0.9.7 or newer. The problem is that the loader ('ld') in -MacOS X has a misfeature that's quite difficult to go around. -Look in the file PROBLEMS for a more detailed explanation and for possible -solutions. - - -* Why does the OpenSSL test suite fail on MacOS X? - -If the failure happens when running 'make test' and the RC4 test fails, -it's very probable that you have OpenSSL 0.9.6b delivered with the -operating system (you can find out by running '/usr/bin/openssl version') -and that you were trying to build OpenSSL 0.9.6d. The problem is that -the loader ('ld') in MacOS X has a misfeature that's quite difficult to -go around and has linked the programs "openssl" and the test programs -with /usr/lib/libcrypto.dylib and /usr/lib/libssl.dylib instead of the -libraries you just built. -Look in the file PROBLEMS for a more detailed explanation and for possible -solutions. - -* Why does the OpenSSL test suite fail in BN_sqr test [on a 64-bit platform]? - -Failure in BN_sqr test is most likely caused by a failure to configure the -toolkit for current platform or lack of support for the platform in question. -Run './config -t' and './apps/openssl version -p'. Do these platform -identifiers match? If they don't, then you most likely failed to run -./config and you're hereby advised to do so before filing a bug report. -If ./config itself fails to run, then it's most likely problem with your -local environment and you should turn to your system administrator (or -similar). If identifiers match (and/or no alternative identifier is -suggested by ./config script), then the platform is unsupported. There might -or might not be a workaround. Most notably on SPARC64 platforms with GNU -C compiler you should be able to produce a working build by running -'./config -m32'. I understand that -m32 might not be what you want/need, -but the build should be operational. For further details turn to -<openssl-...@openssl.org>. - -* Why does OpenBSD-i386 build fail on des-586.s with "Unimplemented segment type"? - -As of 0.9.7 assembler routines were overhauled for position independence -of the machine code, which is essential for shared library support. For -some reason OpenBSD is equipped with an out-of-date GNU assembler which -finds the new code offensive. To work around the problem, configure with -no-asm (and sacrifice a great deal of performance) or patch your assembler -according to <URL: https://www.openssl.org/~appro/gas-1.92.3.OpenBSD.patch>. -For your convenience a pre-compiled replacement binary is provided at -<URL: https://www.openssl.org/~appro/gas-1.92.3.static.aout.bin>. -Reportedly elder *BSD a.out platforms also suffer from this problem and -remedy should be same. Provided binary is statically linked and should be -working across wider range of *BSD branches, not just OpenBSD. - -* Why does the OpenSSL test suite fail in sha512t on x86 CPU? - -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 extensions. See accompanying INSTALL file and -OPENSSL_ia32cap(3) documentation page for further information. - -* Why does compiler fail to compile sha512.c? - -OpenSSL SHA-512 implementation depends on compiler support for 64-bit -integer type. Few elder compilers [ULTRIX cc, SCO compiler to mention a -couple] lack support for this and therefore are incapable of compiling -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. - -* Test suite still fails, what to do? - -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? - -If you are a new user then it is quite likely you haven't found a bug and -something is happening you aren't familiar with. Check this FAQ, the associated -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? - -Please see <URL: https://www.openssl.org/community> - -* I've found a security issue, how do I report it? - -If you think your bug has security implications then please send it to -openssl-secur...@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). If you wish to use PGP to send -in a report please use one or more of the keys of the OMC listed -at <URL: https://www.openssl.org/community/omc.html> - -Note that bugs only present in the openssl utility are not in general -considered to be security issues. - -[PROG] ======================================================================== - -* Is OpenSSL thread-safe? - -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. - -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? - -This is usually because you've missed the comment in INSTALL.W32. -Your application must link against the same version of the Win32 -C-Runtime against which your openssl libraries were linked. The -default version for OpenSSL is /MD - "Multithreaded DLL". - -If you are using Microsoft Visual C++'s IDE (Visual Studio), in -many cases, your new project most likely defaulted to "Debug -Singlethreaded" - /ML. This is NOT interchangeable with /MD and your -program will crash, typically on the first BIO related read or write -operation. - -For each of the six possible link stage configurations within Win32, -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: - - 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) - - Single Threaded /ML - MS VC++ often defaults to - this for the release - version of a new project. - Debug Single Threaded /MLd - MS VC++ often defaults to - this for the debug version - of a new project. - Multithreaded /MT - Debug Multithreaded /MTd - Multithreaded DLL /MD - OpenSSL defaults to this. - Debug Multithreaded DLL /MDd - -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 -.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 -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? - -You have two options. You can either use a memory BIO in conjunction -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: - ------ snip:start ----- - unsigned char *buf, *p; - int len = i2d_PKCS7(p7, NULL); - - buf = OPENSSL_malloc(len); /* error checking omitted */ - 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: - ------ snip:start ----- - unsigned char *p = buf; - - 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 -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. - -Memory allocation and encoding can also be combined in a single -operation by the ASN1 routines: - ------ 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); ------ snip:end ----- - -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? - -The short answer is yes, because DER is a special case of BER and OpenSSL -ASN1 decoders can process BER. - -The longer answer is that ASN1 structures can be encoded in a number of -different ways. One set of ways is the Basic Encoding Rules (BER) with various -permissible encodings. A restriction of BER is the Distinguished Encoding -Rules (DER): these uniquely specify how a given structure is encoded. - -Therefore, because DER is a special case of BER, DER is an acceptable encoding -for BER. - - -* 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 -should try to determine the cause. In particular, you should call -ERR_print_errors() or ERR_print_errors_fp() after the failed call -and see if the message helps. Note that the problem may occur earlier -than you think -- you should check for errors after every call where -it is possible, otherwise the actual problem may be hidden because -some OpenSSL functions clear the error state. - - -* I just get a load of numbers for the error output, what do they mean? - -The actual format is described in the ERR_print_errors() manual page. -You should call the function ERR_load_crypto_strings() before hand and -the message will be output in text form. If you can't do this (for example -it is a pre-compiled binary) you can use the errstr utility on the error -code itself (the hex digits after the second colon). - - -* Why do I get errors about unknown algorithms? - -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? - -Several reasons for problems with the automatic detection exist. -OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. -Sometimes the distribution has installed an older version in the system -locations that is detected instead of a new one installed. The OpenSSL -library might have been compiled for another CPU or another mode (32/64 bits). -Permissions might be wrong. - -The general answer is to check the config.log file generated when running -the OpenSSH configure script. It should contain the detailed information -on why the OpenSSL library was not detected or considered incompatible. - - -* Can I use OpenSSL's SSL library with non-blocking I/O? - -Yes; make sure to read the SSL_get_error(3) manual page! - -A pitfall to avoid: Don't assume that SSL_read() will just read from -the underlying transport or that SSL_write() will just write to it -- -it is also possible that SSL_write() cannot do any useful work until -there is data to read, or that SSL_read() cannot do anything until it -is possible to send data. One reason for this is that the peer may -request a new TLS/SSL handshake at any time during the protocol, -requiring a bi-directional message exchange; both SSL_read() and -SSL_write() will try to continue any pending handshake. - - -* Why doesn't my server application receive a client certificate? - -Due to the TLS protocol definition, a client will only send a certificate, -if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the -SSL_CTX_set_verify() function to enable the use of client certificates. - - -* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? - -For OpenSSL 0.9.7 the OID table was extended and corrected. In earlier -versions, uniqueIdentifier was incorrectly used for X.509 certificates. -The correct name according to RFC2256 (LDAP) is x500UniqueIdentifier. -Change your code to use the new name when compiling against OpenSSL 0.9.7. - - -* I think I've detected a memory leak, is this a bug? - -In most cases the cause of an apparent memory leak is an OpenSSL internal table -that is allocated when an application starts up. Since such tables do not grow -in size over time they are harmless. - -These internal tables can be freed up when an application closes using various -functions. Currently these include following: - -Thread-local cleanup functions: - - ERR_remove_state() - -Application-global cleanup functions that are aware of usage (and therefore -thread-safe): - - ENGINE_cleanup() and CONF_modules_unload() - -"Brutal" (thread-unsafe) Application-global cleanup functions: - - 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. - - -* Why doesn't a memory BIO work when a file does? - -This can occur in several cases for example reading an S/MIME email message. -The reason is that a memory BIO can do one of two things when all the data -has been read from it. - -The default behaviour is to indicate that no more data is available and that -the call should be retried, this is to allow the application to fill up the BIO -again if necessary. - -Alternatively it can indicate that no more data is available and that EOF has -been reached. - -If a memory BIO is to behave in the same way as a file this second behaviour -is needed. This must be done by calling: - - BIO_set_mem_eof_return(bio, 0); - -See the manual pages for more details. - - -* Where are the declarations and implementations of d2i_X509() etc? - -These are defined and implemented by macros of the form: - - - DECLARE_ASN1_FUNCTIONS(X509) and IMPLEMENT_ASN1_FUNCTIONS(X509) - -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. - -=============================================================================== _____ openssl-commits mailing list To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-commits