[openssl-commits] [web] master update
Richard Levitte
levitte at openssl.org
Tue Jan 29 10:17:43 UTC 2019
The branch master has been updated
via 8557dd2bb3cebee18ec35347250271322b09d5da (commit)
from 0ef1cccd789aa8434f9ef8e3783df637d506b53f (commit)
- Log -----------------------------------------------------------------
commit 8557dd2bb3cebee18ec35347250271322b09d5da
Author: Richard Levitte <levitte at 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 <matt at 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 at 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 at 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-dev at 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-security at 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-dev at 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-security at 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-security at 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-security at 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;
+}
+
More information about the openssl-commits
mailing list