The branch master has been updated via 8557dd2bb3cebee18ec35347250271322b09d5da (commit) from 0ef1cccd789aa8434f9ef8e3783df637d506b53f (commit)
- Log ----------------------------------------------------------------- commit 8557dd2bb3cebee18ec35347250271322b09d5da Author: Richard Levitte <levi...@openssl.org> Date: Tue Dec 25 15:53:29 2018 +0100 Reformat FAQ files Make them correct Markdown, and then use pandoc to create the FAQ HTML. We then use CSS and a bit of Javascript to make it an accordion style FAQ. Reviewed-by: Matt Caswell <m...@openssl.org> (Merged from https://github.com/openssl/web/pull/103) ----------------------------------------------------------------------- Summary of changes: bin/mk-faq | 110 +++------ docs/faq-1-legal.txt | 42 ++-- docs/faq-2-user.txt | 373 +++++++++++++++---------------- docs/faq-3-prog.txt | 614 +++++++++++++++++++++++++-------------------------- docs/faq-4-build.txt | 397 ++++++++++++++++----------------- docs/faq-5-misc.txt | 177 ++++++++------- docs/faq-6-old.txt | 18 +- docs/faq.html | 9 +- inc/screen.css | 121 ++++++++++ 9 files changed, 951 insertions(+), 910 deletions(-) diff --git a/bin/mk-faq b/bin/mk-faq index 531a6c6..0f92d2e 100755 --- a/bin/mk-faq +++ b/bin/mk-faq @@ -1,88 +1,30 @@ -#! /usr/bin/perl -use strict; -use warnings; +#! /bin/sh -# Filename->anchor name -my %anchors; -foreach my $f ( @ARGV ) { - next unless $f =~ /faq-[0-9]-(.*).txt/; - $anchors{$f} = uc($1); -} +cat <<EOF +<h3><a name='toc'>Table of Contents</a></h3> +<ol> +EOF +for faqfile in "$@"; do + anchor=`basename $faqfile .txt | cut -f3 -d- | tr '[:lower:]' '[:upper:]'` + title=`head -1 $faqfile | sed -e 's|^##* *||'` -my $top = ' <a href="#toc"><img src="/img/up.gif"/></a>'; -print "<h3><a name='toc'>Table of Contents</a></h3>\n"; + cat <<EOF + <h4><a href='#$anchor'>$title</a></h4> +EOF +done +cat <<EOF +</ol> +EOF -# 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); -} +for faqfile in "$@"; do + anchor=`basename $faqfile .txt | cut -f3 -d- | tr '[:lower:]' '[:upper:]'` -# 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); + cat <<EOF +<hr /> +EOF + cat $faqfile \ + | perl -pe 'BEGIN { $count = 0 } s/^(#### )/$1|'${anchor}'|/; s/^(\* *)(?{ $count++ })/$1|'${anchor}'${count}|/' \ + | pandoc -t html --no-highlight \ + | sed -E -e 's/ id="[-a-z]*">/>/' \ + | sed -E -e 's/<([^<>]*)>\|([A-Z]*[0-9]*)\|/<\1 id="\2">/' +done diff --git a/docs/faq-1-legal.txt b/docs/faq-1-legal.txt index dc69809..1dfc067 100644 --- a/docs/faq-1-legal.txt +++ b/docs/faq-1-legal.txt @@ -1,28 +1,28 @@ -Legal Questions +#### Legal Questions -* Do I need patent licenses to use OpenSSL? +* 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. + 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> + You can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using -* Can I use OpenSSL with GPL software? + ./config no-idea no-mdc2 no-rc5 -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). +* Can I use OpenSSL with GPL software? -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. + 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. -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 index 682ec7f..74126ab 100644 --- a/docs/faq-2-user.txt +++ b/docs/faq-2-user.txt @@ -1,220 +1,215 @@ -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.) - -* Why do I get errors when trying to decrypt 1.0.2 data with 1.1.0? - -A message digest is used to create the encrypt/decrypt key from -a human-entered passphrase. In OpenSSL 1.1.0 we changed from MD5 to -SHA-256. We did this as part of an overall change to move away from -the now-insecure and broken MD5 algorithm. If you have old files, -use the "-md md5" flag to decrypt them. - -* 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. - -* 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. +#### 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 can I remove the passphrase on a private key? +* Why do I get errors when trying to decrypt 1.0.2 data with 1.1.0? -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. + A message digest is used to create the encrypt/decrypt key from + a human-entered passphrase. In OpenSSL 1.1.0 we changed from MD5 to + SHA-256. We did this as part of an overall change to move away from + the now-insecure and broken MD5 algorithm. If you have old files, + use the "-md md5" flag to decrypt them. -* Why can't I use OpenSSL certificates with SSL client authentication? +* How do I create certificates or certificate requests? -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. + 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) ). -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: +* Why can't I create certificate requests? -<PRE> - openssl s_client -connect www.some.host:443 -prexit -</PRE> + You typically get the error: -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: + unable to find 'distinguished_name' in config + problems making Certificate Request -<PRE> - GET /some/page/needing/a/certificate.html -</PRE> + This is because it can't find the configuration file. Check out the + DIAGNOSTICS section of req(1) for more information. -If your CA does not appear in the list then this confirms the problem. +* Why does <SSL program> fail with a certificate verify error? -* Why does my browser give a warning about a mismatched hostname? + 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. -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 can I create DSA certificates? -* How do I install a CA certificate into a browser? + Check the CA.pl(1) manual page for a DSA certificate example. -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. +* Why can't I make an SSL connection to a server using a DSA certificate? -You can convert a certificate to DER form using the command: + 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. -openssl x509 -in ca.pem -outform DER -out ca.der +* How can I remove the passphrase on a private key? -Occasionally someone suggests using a command such as: + 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. -openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem +* Why can't I use OpenSSL certificates with SSL client authentication? -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. + 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. -* Why is OpenSSL x509 DN output not conformant to RFC2253? + 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: -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. + openssl s_client -connect www.some.host:443 -prexit -* Why does OpenSSL set the authority key identifier (AKID) extension incorrectly? + 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: -It doesn't: this extension is often the cause of confusion. + GET /some/page/needing/a/certificate.html -Consider a certificate chain A->B->C so that A signs B and B signs C. Suppose -certificate C contains AKID. + If your CA does not appear in the list then this confirms the problem. -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. +* Why does my browser give a warning about a mismatched hostname? -In this latter case because it is identifying certificate B it must contain the -issuer name and serial number of B. + 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. -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 do I install a CA certificate into a browser? -* How can I set up a bundle of commercial root CA certificates? + 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. -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. + You can convert a certificate to DER form using the command: -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@@@ + openssl x509 -in ca.pem -outform DER -out ca.der -* Some secure servers 'hang' with OpenSSL 1.0.1, is this a bug? + 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. + +* 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. -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 index bb6790a..f93569a 100644 --- a/docs/faq-3-prog.txt +++ b/docs/faq-3-prog.txt @@ -1,317 +1,303 @@ -Programming with OpenSSL - -* Is OpenSSL thread-safe? - -Yes but with some limitations; for example, an SSL connection -cannot be used concurrently by multiple threads. This is true for -most OpenSSL objects. - -For version 1.1.0 and later, there is nothing further you need do. - -For earlier versions than 1.1.0, it is necessary for your -application to set up the thread callback functions. 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. - -* My code gets "undefined structure" or "unknown size" when building with 1.1.0 or later. - -In 1.1.0 we made most of the structures opaque. This means that you can -no longer access the fields directly, but must use settor and accessor -functions. You can also no longer have direct instances of the objects, -but can only use pointers to them. -For example, the first line below is wrong; the second is correct: -<PRE> - RSA r; /* wrong */ - RSA *r; /* right */ -</PRE> - -* 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. - -* The encoding for GeneralName is wrong; why is the SEQUENCE tag missing? - -In RFC 5280 GeneralName is defined in the module in Appendix A.2, and that -module specifies the use of IMPLICIT tagging. This means that there is not an -explicit SEQUENCE (30) tag following the A0 tag (you just know from the ASN.1 -that what follows the A1 tag is a SEQUENCE). This is in contrast to the value -field within OtherName (test@kerberose-domain.internal), where the tag for -UTF8String (0C) follows the A0 tag, since EXPLICIT tagging is specified for -that particular field. - -You will notice the same thing if you look at other choices within -GeneralName. If you look at the DNS names encoded in the subjectAltName -extension, the 82 tag (corresponding to [2]) is not followed by a tag for -IA5String (22). It is not needed since the ASN.1 indicates that what follows -the 82 tag is an IA5String. However, if the module specified EXPLICIT -encoding, then there would be a 16 tag after the 82 tag. - -(Thanks to David Cooper for this text.) - -* I tried to set a cipher list with a valid cipher, but the call fails, why? - -OpenSSL 1.1.0 introduced the concept of a “security level”, allowing -for a configuration to be made more secure by excluding algorithms -and key sizes that are known to be flawed or susceptible to brute force at -a given level of work. SSL_CTX_set_security_level(3) can be used to -programmatically set a security level, or the keyword "@SECLEVEL=N" can -be used in a TLS cipher string, for values of N from 0 to 5 (inclusive). -The default is level 1, which excludes MD5 as the MAC and algorithms -with less than 80 bits of security. A value of 0 can be used, with appropriate -caution, to produce behavior compatible with previous versions of OpenSSL -(to the extent possible), but this is not recommended for general usage. - -* 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. +#### Programming with OpenSSL + +* Is OpenSSL thread-safe? + + Yes but with some limitations; for example, an SSL connection + cannot be used concurrently by multiple threads. This is true for + most OpenSSL objects. + + For version 1.1.0 and later, there is nothing further you need do. + + For earlier versions than 1.1.0, it is necessary for your + application to set up the thread callback functions. 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. + +* My code gets "undefined structure" or "unknown size" when building + with 1.1.0 or later. + + In 1.1.0 we made most of the structures opaque. This means that you can + no longer access the fields directly, but must use settor and accessor + functions. You can also no longer have direct instances of the objects, + but can only use pointers to them. + For example, the first line below is wrong; the second is correct: + + RSA r; /* wrong */ + RSA *r; /* right */ + +* 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: + + unsigned char *buf, *p; + int len = i2d_PKCS7(p7, NULL); + + buf = OPENSSL_malloc(len); /* error checking omitted */ + p = buf; + i2d_PKCS7(p7, &p); + + At this point buf contains the len bytes of the DER encoding of p7. + + The opposite assumes we already have len bytes in buf: + + unsigned char *p = buf; + + p7 = d2i_PKCS7(NULL, &p, len); + + 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: + + 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); + + 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. + +* The encoding for GeneralName is wrong; why is the SEQUENCE tag missing? + + In RFC 5280 GeneralName is defined in the module in Appendix A.2, and that + module specifies the use of IMPLICIT tagging. This means that there is not an + explicit SEQUENCE (30) tag following the A0 tag (you just know from the ASN.1 + that what follows the A1 tag is a SEQUENCE). This is in contrast to the value + field within OtherName (test@kerberose-domain.internal), where the tag for + UTF8String (0C) follows the A0 tag, since EXPLICIT tagging is specified for + that particular field. + + You will notice the same thing if you look at other choices within + GeneralName. If you look at the DNS names encoded in the subjectAltName + extension, the 82 tag (corresponding to [2]) is not followed by a tag for + IA5String (22). It is not needed since the ASN.1 indicates that what follows + the 82 tag is an IA5String. However, if the module specified EXPLICIT + encoding, then there would be a 16 tag after the 82 tag. + + (Thanks to David Cooper for this text.) + +* I tried to set a cipher list with a valid cipher, but the call fails, why? + + OpenSSL 1.1.0 introduced the concept of a “security level”, allowing + for a configuration to be made more secure by excluding algorithms + and key sizes that are known to be flawed or susceptible to brute force at + a given level of work. SSL_CTX_set_security_level(3) can be used to + programmatically set a security level, or the keyword "@SECLEVEL=N" can + be used in a TLS cipher string, for values of N from 0 to 5 (inclusive). + The default is level 1, which excludes MD5 as the MAC and algorithms + with less than 80 bits of security. A value of 0 can be used, with appropriate + caution, to produce behavior compatible with previous versions of OpenSSL + (to the extent possible), but this is not recommended for general usage. -* I just get a load of numbers for the error output, what do they mean? +* I've called <some function> and it fails, why? -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. - -* 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. - -Starting with OpenSSL 1.1.0, everything should be cleaned up on exit (or -when the shared library unloads). If not, please find out what resource is -leaked and report an issue. In previous releases, 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> + 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. + +* 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. + + Starting with OpenSSL 1.1.0, everything should be cleaned up on exit (or + when the shared library unloads). If not, please find out what resource is + leaked and report an issue. In previous releases, 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: + + BIO_set_mem_eof_return(bio, 0); + + 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: + + 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(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. -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 index 7c16f52..72202b4 100644 --- a/docs/faq-4-build.txt +++ b/docs/faq-4-build.txt @@ -1,202 +1,195 @@ -Questions on Building and Testing OpenSSL - -* Does OpenSSL use AES-NI or other speedups? - -The short answer is yes, unless you configure with "no-asm." - -What OpenSSL does is not obvious. The INSTALL document talks about the -no-asm configuration option. Details about what the assembler code does -in terms of optimization are only available by reading the source code -comments in the various Perl files that generate the assembler, mostly. - -On x86, the assembly code uses the CPUID instruction (see the -OPENSSL_ia32cap.pod manpage) to determine if various instructions (AES, -SSE, MMX, etc) are available and will use them if so. For other processors, -similar tests are performed if at all possible. - -* 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 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 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. 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. - -* How do I enable weak ciphers? - -Warning: known-insecure ciphers are disabled in newer releases of OpenSSL. -There is good reason why these have been disabled by default. Consider upgrading -to more robust options as these ciphers may only provide a facade of security. -This option is not recommended for anyone other than maintainers of legacy -applications. There are two parts to doing this. First, you must configure -with "enable-weak-ssl-ciphers." This compiles the ciphers, but does not -enable them at run-time; to do this you must set the "security level" flag. -This can be done at build time to change the default, or it can be done at -runtime to change it for particular SSL_CTX; see -@@@https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html@@@ -for details. - -In other words, you should do one of the following: - -<PRE> - ./config enable-weak-ssl-ciphers -DOPENSSL_TLS_SECURITY_LEVEL=0 -</PRE> - -or - -<PRE> - # To configure and build - ./config enable-weak-ssl-ciphers - - /* In your code */ - SSL_CTX_set_security_level(ctx, 0); -</PRE> +#### Questions on Building and Testing OpenSSL + +* Does OpenSSL use AES-NI or other speedups? + + The short answer is yes, unless you configure with "no-asm." + + What OpenSSL does is not obvious. The INSTALL document talks about the + no-asm configuration option. Details about what the assembler code does + in terms of optimization are only available by reading the source code + comments in the various Perl files that generate the assembler, mostly. + + On x86, the assembly code uses the CPUID instruction (see the + OPENSSL_ia32cap.pod manpage) to determine if various instructions (AES, + SSE, MMX, etc) are available and will use them if so. For other processors, + similar tests are performed if at all possible. + +* 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 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): + + PATH=${PATH}:/usr/ccs/bin; export PATH + + 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 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. 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. + +* How do I enable weak ciphers? + + Warning: known-insecure ciphers are disabled in newer releases of OpenSSL. + There is good reason why these have been disabled by default. Consider upgrading + to more robust options as these ciphers may only provide a facade of security. + This option is not recommended for anyone other than maintainers of legacy + applications. There are two parts to doing this. First, you must configure + with "enable-weak-ssl-ciphers." This compiles the ciphers, but does not + enable them at run-time; to do this you must set the "security level" flag. + This can be done at build time to change the default, or it can be done at + runtime to change it for particular SSL_CTX; see + https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html + for details. + + In other words, you should do one of the following: + + ./config enable-weak-ssl-ciphers -DOPENSSL_TLS_SECURITY_LEVEL=0 + + or + + # To configure and build + ./config enable-weak-ssl-ciphers + + /* In your code */ + SSL_CTX_set_security_level(ctx, 0); + diff --git a/docs/faq-5-misc.txt b/docs/faq-5-misc.txt index 006b323..f06fd34 100644 --- a/docs/faq-5-misc.txt +++ b/docs/faq-5-misc.txt @@ -1,122 +1,119 @@ -Miscellaneous +#### Miscellaneous -* Which is the current version of OpenSSL? +* Which is the current version of OpenSSL? -The current version is available from @@@https://www.openssl.org@@@. + 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. + 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? +* 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 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. + 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. + 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. -* I need a FIPS validated offering +* I need a FIPS validated offering -Please see -@@@https://www.openssl.org/docs/fips.html@@@; the OpenSSL project is no longer -involved in private label validations nor adding platforms to the existing -certificates. + Please see + https://www.openssl.org/docs/fips.html; the OpenSSL project is no longer + involved in private label validations nor adding platforms to the existing + certificates. -* How can I contact the OpenSSL developers? +* 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@@@. + 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? +* Where can I get a compiled version of OpenSSL? -You can finder pointers to binary distributions in -@@@https://www.openssl.org/community/binaries.html@@@ . + 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). + 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. + 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. + A number of Linux and *BSD distributions include OpenSSL. -* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? +* 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. + 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. + 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. -* How do I check the authenticity of the OpenSSL distribution? +* 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: + 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> + 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 @@@https://www.openssl.org/community/omc.html@@@). Then -just do: + 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> + pgp TARBALL.asc -* How does the versioning scheme work? +* 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. + 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. + 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? +* 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. + 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. -* Do you have a bug bounty program? +* Do you have a bug bounty program? -The project does not. Google runs a program -@@@https://www.google.com/about/appsecurity/patch-rewards/@@@; so does -HackerOne, @@@https://hackerone.com/ibb-openssl@@@. In general, if you -have found a security issue, send email to openssl-secur...@openssl.org. -Please note that we do not consider DNS configurations or Website -configuration to be security issues. + The project does not. Google runs a program + https://www.google.com/about/appsecurity/patch-rewards/; so does + HackerOne, https://hackerone.com/ibb-openssl. In general, if you + have found a security issue, send email to openssl-secur...@openssl.org. + Please note that we do not consider DNS configurations or Website + configuration to be security issues. + diff --git a/docs/faq-6-old.txt b/docs/faq-6-old.txt index 708771a..6b0e3bd 100644 --- a/docs/faq-6-old.txt +++ b/docs/faq-6-old.txt @@ -1,14 +1,14 @@ -Older Versions and Platforms +#### Older Versions and Platforms -* What does "old" mean here? +* What does "old" mean here? -Any OpenSSL release before 1.0.2, and any platform that is not in wide use, -and doesn't get full support. Or something like that. + Any OpenSSL release before 1.0.2, and any platform that is not in wide use, + and doesn't get full support. Or something like that. -* Why does compilation fail due to an undefined symbol NID_uniqueIdentifier? +* 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. + 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. diff --git a/docs/faq.html b/docs/faq.html index a988032..080ff7d 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -10,7 +10,7 @@ <div class="blog-index"> <article> <header><h2>Frequently Asked Questions</h2></header> - <div class="entry-content"> + <div class="faq"> <!--#include virtual="faq.inc" --> </div> <footer> @@ -28,4 +28,11 @@ <!--#include virtual="/inc/footer.shtml" --> </body> +<script> +$(document).ready(function(){ + $(".faq ul > li").click(function(){ + $(this).toggleClass("open"); + }); +}); +</script> </html> diff --git a/inc/screen.css b/inc/screen.css index e3d672c..9938bcc 100644 --- a/inc/screen.css +++ b/inc/screen.css @@ -1573,3 +1573,124 @@ tr:first-child { font-weight: bold; border-bottom: 1px solid black; } tr:nth-child(even) { background-color: #D9f0ff; } td.d { float: left; width: 20%; } td.t { float: right; width: 80%; } + +/* FAQ accordion */ +/* + * This also needs a bit of javascript that toggles the 'open' class on a + * 'faq ul li' element. + * Quite of lot of the effort is really to get nice rounded boxes around + * each entry, and the squared plus / minus sign off to the left. + * + * The FAQ itself is expected to looks like this: + * + * <div class="faq"> + * ... + * <ul> + * <li> + * <p>FAQ entry title</p> + * <p>FAQ entry text</p> + * <p>more text</p> + * <p>more text</p> + * <p>more text</p> + * </li> + * ... + * </ul> + * ... + * </div> + * + * One could have argued for using <dt> and <dd>, but support for it looks + * damn ugly in Markdown, so we use this form instead, which results in the + * above: + * + * * FAQ entry title + * + * FAQ entry text + * + * more text + * + * more text + * + * more text + */ + +/* Styling for closed items */ +.faq ul { + position: relative; + margin-left: 0; + padding-left: 0; + list-style: none; +} + +.faq ul > li { + margin: 5px 0 0 0; + padding: 0; + border: 1px solid #cccccc; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + border-radius: 5px; +} + +.faq ul > li > p { + margin: 0; + padding: 5px 20px; +} + +.faq ul > li > p:nth-child(1)::before { + position: absolute; + margin-left: -1em; + content: "\229E"; +} + +.faq ul > li > p:nth-child(1) { + background-color: #ebebeb; + cursor: pointer; + color: #666666; +} + +.faq ul > li > p:nth-child(1):hover { + background-color: #f5f5f5; +} + +.faq ul > li > p:nth-child(n+2) { + display: none; + transition: display .5s ease 0s; +} + +.faq ul > li > pre { + display: none; + transition: display .5s ease 0s; + margin: 5px 20px; +} + +/* The changes for an opened entry */ +.faq ul > li.open > p:nth-child(1)::before { + position: absolute; + margin-left: -1em; + content: "\229F"; +} + +.faq ul > li.open > p:nth-child(1) { + -moz-border-radius: 5px 5px 0 0; + -webkit-border-radius: 5px 5px 0 0; + border-radius: 5px 5px 0 0; + background-color: #cef98d; +} + +.faq ul > li.open > p:nth-child(1):hover { + background-color: #c6f089; +} + +.faq ul > li.open > p:nth-child(n+2) { + display: block; +} + +.faq ul > li.open > pre { + display: block; +} + +/* Hacks because we have CSS code elsewhere giving a bad result here */ +.faq code { + /* counteract 'li code' */ + color: #00FF00; +} + _____ openssl-commits mailing list To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-commits