From a295a88d39f45588c7c83fde960331996b0c693c Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 17 Oct 2023 11:13:55 +0200 Subject: [PATCH] Kill the FAQ It's unused and hasn't seen an update for eons. Reviewed-by: Anton Arapov Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/web/pull/431) --- .gitignore | 1 - .htaccess | 1 - Makefile | 5 - bin/mk-faq | 35 ---- dirdata.yaml | 2 +- docs/dirdata.yaml | 1 - docs/faq-1-legal.txt | 28 --- docs/faq-2-user.txt | 230 ------------------------- docs/faq-3-prog.txt | 303 --------------------------------- docs/faq-4-build.txt | 195 --------------------- docs/faq-5-misc.txt | 103 ----------- docs/faq-6-old.txt | 14 -- docs/faq.md.tt | 14 -- docs/index.md | 2 - inc/pandoc-body-prologue.html5 | 2 +- inc/screen.css | 121 ------------- source/index.md.tt | 7 +- 17 files changed, 5 insertions(+), 1059 deletions(-) delete mode 100755 bin/mk-faq delete mode 100644 docs/faq-1-legal.txt delete mode 100644 docs/faq-2-user.txt delete mode 100644 docs/faq-3-prog.txt delete mode 100644 docs/faq-4-build.txt delete mode 100644 docs/faq-5-misc.txt delete mode 100644 docs/faq-6-old.txt delete mode 100644 docs/faq.md.tt diff --git a/.gitignore b/.gitignore index 6a77588c..a49bf67e 100644 --- a/.gitignore +++ b/.gitignore @@ -16,7 +16,6 @@ community/omc.md community/*.html docs/OpenSSL300Design.html docs/OpenSSLStrategicArchitecture.html -docs/faq.inc docs/fips.inc docs/man*/ docs/manpages.md diff --git a/.htaccess b/.htaccess index dc11eabe..ad8cf0af 100644 --- a/.htaccess +++ b/.htaccess @@ -6,7 +6,6 @@ Options +ExecCGI +FollowSymLinks Redirect permanent /about/releasestrat.html /policies/releasestrat.html Redirect permanent /licenses/openssl_ccla.pdf /policies/openssl_ccla.pdf Redirect permanent /licenses/openssl_icla.pdf /policies/openssl_icla.pdf -Redirect permanent /support/faq.html /docs/faq.html Redirect permanent /licenses /policies/cla.html Redirect permanent /licenses/ /policies/cla.html Redirect permanent /.well-known/acme-challenge/MX5CvUJNvymcKf22SNORcfjGk4oGQyIWJiBc_johfYo http://dcv.akamai.com/.well-known/acme-challenge/MX5CvUJNvymcKf22SNORcfjGk4oGQyIWJiBc_johfYo diff --git a/Makefile b/Makefile index 0af7b627..bb9afa29 100644 --- a/Makefile +++ b/Makefile @@ -334,11 +334,6 @@ docs/mansidebar.html: docs/mansidebar.html.tt Makefile bin/from-tt @rm -f $@ ./bin/from-tt releases='master $(MANSERIES)' $< -docs/faq.inc: $(wildcard docs/faq-[0-9]-*.txt) Makefile bin/mk-faq - @rm -f $@ - ./bin/mk-faq docs/faq-[0-9]-*txt >$@ -docs/faq.md: docs/faq.inc - ###################################################################### ## ## Policy page building section diff --git a/bin/mk-faq b/bin/mk-faq deleted file mode 100755 index 85a956cf..00000000 --- a/bin/mk-faq +++ /dev/null @@ -1,35 +0,0 @@ -#! /bin/sh - -cat < -

Table of Contents

-
    -EOF -for faqfile in "$@"; do - anchor=`basename $faqfile .txt | cut -f3 -d- | tr '[:lower:]' '[:upper:]'` - title=`head -1 $faqfile | sed -e 's|^##* *||'` - - cat <$title -EOF -done -cat < -EOF - -for faqfile in "$@"; do - anchor=`basename $faqfile .txt | cut -f3 -d- | tr '[:lower:]' '[:upper:]'` - - cat < -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 - -cat < -EOF diff --git a/dirdata.yaml b/dirdata.yaml index 2ba653aa..8dacdea0 100644 --- a/dirdata.yaml +++ b/dirdata.yaml @@ -6,7 +6,7 @@ sidebar: | - [Our Mission and Values](/community/mission.html) - [Downloads: Source code](/source) - - [Docs: FAQ, FIPS, manpages, ...](/docs) + - [Docs: FIPS, manpages, ...](/docs) - [News: Latest information](/news) - [Roadmap: What's planned](/roadmap.html) - [Policies: How we operate](/policies) diff --git a/docs/dirdata.yaml b/docs/dirdata.yaml index 8100fec9..aa44fdc2 100644 --- a/docs/dirdata.yaml +++ b/docs/dirdata.yaml @@ -4,7 +4,6 @@ breadcrumbs: >- sidebar: | # Documentation - - [FAQ](faq.html) - [Manpages](manpages.html) - [FIPS-140 Validation](fips.html) --- diff --git a/docs/faq-1-legal.txt b/docs/faq-1-legal.txt deleted file mode 100644 index 1dfc0670..00000000 --- a/docs/faq-1-legal.txt +++ /dev/null @@ -1,28 +0,0 @@ -#### Legal Questions - -* Do I need patent licenses to use OpenSSL? - - For information on intellectual property rights, please consult a lawyer. - The OpenSSL team does not offer legal advice. - - You can configure OpenSSL so as not to use IDEA, MDC2 and RC5 by using - - ./config no-idea no-mdc2 no-rc5 - -* Can I use OpenSSL with GPL software? - - On many systems including the major Linux and BSD distributions, yes (the - GPL does not place restrictions on using libraries that are part of the - normal operating system distribution). - - On other systems, the situation is less clear. Some GPL software copyright - holders claim that you infringe on their rights if you use OpenSSL with - their software on operating systems that don't normally include OpenSSL. - - If you develop open source software that uses OpenSSL, you may find it - useful to choose an other license than the GPL, or state explicitly that - "This program is released under the GPL with the additional exemption that - compiling, linking, and/or using OpenSSL is allowed." If you are using - GPL software developed by others, you may want to ask the copyright holder - for permission to use their software with OpenSSL. - diff --git a/docs/faq-2-user.txt b/docs/faq-2-user.txt deleted file mode 100644 index 3bc8ff7e..00000000 --- a/docs/faq-2-user.txt +++ /dev/null @@ -1,230 +0,0 @@ -#### 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: - - unable to find 'distinguished_name' in config - problems making Certificate Request - - This is because it can't find the configuration file. Check out the - DIAGNOSTICS section of req(1) for more information. - -* Why does <SSL program> fail with a certificate verify error? - - This problem is usually indicated by log messages saying something like - "unable to get local issuer certificate" or "self signed certificate". - When a certificate is verified its root CA must be "trusted" by OpenSSL - this typically means that the CA certificate must be placed in a directory - or file and the relevant program configured to read it. The OpenSSL program - 'verify' behaves in a similar way and issues similar error messages: check - the verify(1) program manual page for more information. - -* How can I create DSA certificates? - - Check the CA.pl(1) manual page for a DSA certificate example. - -* Why can't I make an SSL connection to a server using a DSA certificate? - - Typically you'll see a message saying there are no shared ciphers when - the same setup works fine with an RSA certificate. There are two possible - causes. The client may not support connections to DSA servers most web - browsers (including Netscape and MSIE) only support connections to servers - supporting RSA cipher suites. The other cause is that a set of DH parameters - has not been supplied to the server. DH parameters can be created with the - dhparam(1) command and loaded using the SSL_CTX_set_tmp_dh(3) for example: - check the source to s_server in apps/s_server.c for an example. - -* How can I remove the passphrase on a private key? - - Firstly you should be really *really* sure you want to do this. Leaving - a private key unencrypted is a major security risk. If you decide that - you do have to do this check the EXAMPLES sections of the rsa(1) and - dsa(1) manual pages. - -* Why can't I use OpenSSL certificates with SSL client authentication? - - What will typically happen is that when a server requests authentication - it will either not include your certificate or tell you that you have - no client certificates (Netscape) or present you with an empty list box - (MSIE). The reason for this is that when a server requests a client - certificate it includes a list of CAs names which it will accept. Browsers - will only let you select certificates from the list on the grounds that - there is little point presenting a certificate which the server will - reject. - - The solution is to add the relevant CA certificate to your servers "trusted - CA list". How you do this depends on the server software in uses. You can - print out the servers list of acceptable CAs using the OpenSSL s_client tool: - - openssl s_client -connect www.some.host:443 -prexit - - If your server only requests certificates on certain URLs then you may need - to manually issue an HTTP GET command to get the list when s_client connects: - - GET /some/page/needing/a/certificate.html - - If your CA does not appear in the list then this confirms the problem. - -* Why does my browser give a warning about a mismatched hostname? - - Browsers expect the server's hostname to match the value in the commonName - (CN) field of the certificate. If it does not then you get a warning. - -* How do I install a CA certificate into a browser? - - The usual way is to send the DER encoded certificate to the browser as - MIME type application/x-x509-ca-cert, for example by clicking on an - appropriate link. On MSIE certain extensions such as .der or .cacert - may also work, or you can import the certificate using the - certificate import wizard. - - You can convert a certificate to DER form using the command: - - openssl x509 -in ca.pem -outform DER -out ca.der - - Occasionally someone suggests using a command such as: - - openssl pkcs12 -export -out cacert.p12 -in cacert.pem -inkey cakey.pem - - DO NOT DO THIS! This command will give away your CAs private key and - reduces its security to zero: allowing anyone to forge certificates in - whatever name they choose. - -* Why is OpenSSL x509 DN output not conformant to RFC2253? - - The ways to print out the oneline format of the DN (Distinguished Name) have - been extended in version 0.9.7 of OpenSSL. Using the new X509_NAME_print_ex(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. - -* Some secure servers emit an infinite loop of HTTP headers with an OpenSSL - 1.1.0 client, is this a bug? - - OpenSSL 1.1.0 introduced support for several new TLS extensions, including - encrypt-then-mac and extended-master-secret, both of which provide - significant security improvements. Unfortunately, some deployed TLS - servers are severely broken and do not implement extensibility in a - standards-compliant manner; these servers may exhibit strange behavior - such as repeating the HTTP headers in a loop after receiving a ClientHello - that includes such TLS extensions unknown to them. While these new TLS - extensions provide significant security benefits to clients and are - accordingly enabled by default in modern TLS clients, if bringing the - server into compliance is not possible, the extension(s) in question can - be disabled on a per-connection basis when talking to the buggy server, by - using SSL_set_options(3). diff --git a/docs/faq-3-prog.txt b/docs/faq-3-prog.txt deleted file mode 100644 index f93569ad..00000000 --- a/docs/faq-3-prog.txt +++ /dev/null @@ -1,303 +0,0 @@ -#### 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've called <some function> and it fails, why? - - Before submitting a report or asking in one of the mailing lists, you - should try to determine the cause. In particular, you should call - ERR_print_errors(3) or ERR_print_errors_fp(3) after the failed call - and see if the message helps. Note that the problem may occur earlier - than you think -- you should check for errors after every call where - it is possible, otherwise the actual problem may be hidden because - some OpenSSL functions clear the error state. - -* I just get a load of numbers for the error output, what do they mean? - - The actual format is described in the ERR_print_errors(3) manual page. - You should call the function ERR_load_crypto_strings(3) before hand and - the message will be output in text form. If you can't do this (for example - it is a pre-compiled binary) you can use the errstr(1) utility on the error - code itself (the hex digits after the second colon). - -* Why do I get errors about unknown algorithms? - - The cause is forgetting to load OpenSSL's table of algorithms with - OpenSSL_add_all_algorithms(3). See the manual page for more information. This - can cause several problems such as being unable to read in an encrypted - PEM file, unable to decrypt a PKCS12 file or signature failure when - verifying certificates. - -* Why can't the OpenSSH configure script detect OpenSSL? - - Several reasons for problems with the automatic detection exist. - OpenSSH requires at least version 0.9.5a of the OpenSSL libraries. - Sometimes the distribution has installed an older version in the system - locations that is detected instead of a new one installed. The OpenSSL - library might have been compiled for another CPU or another mode (32/64 bits). - Permissions might be wrong. - - The general answer is to check the config.log file generated when running - the OpenSSH configure script. It should contain the detailed information - on why the OpenSSL library was not detected or considered incompatible. - -* Can I use OpenSSL's SSL library with non-blocking I/O? - - Yes; make sure to read the SSL_get_error(3) manual page! - - A pitfall to avoid: Don't assume that SSL_read(3) will just read from - the underlying transport or that SSL_write(3) will just write to it -- - it is also possible that SSL_write(3) cannot do any useful work until - there is data to read, or that SSL_read(3) cannot do anything until it - is possible to send data. One reason for this is that the peer may - request a new TLS/SSL handshake at any time during the protocol, - requiring a bi-directional message exchange; both SSL_read(3) and - SSL_write(3) will try to continue any pending handshake. - -* Why doesn't my server application receive a client certificate? - - Due to the TLS protocol definition, a client will only send a certificate, - if explicitly asked by the server. Use the SSL_VERIFY_PEER flag of the - SSL_CTX_set_verify(3) function to enable the use of client certificates. - -* 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. - diff --git a/docs/faq-4-build.txt b/docs/faq-4-build.txt deleted file mode 100644 index 72202b4a..00000000 --- a/docs/faq-4-build.txt +++ /dev/null @@ -1,195 +0,0 @@ -#### 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@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@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 deleted file mode 100644 index 4c4265a2..00000000 --- a/docs/faq-5-misc.txt +++ /dev/null @@ -1,103 +0,0 @@ -#### Miscellaneous - -* Which is the current version of OpenSSL? - - The current version is available from https://www.openssl.org. - - In addition to the current stable release, you can also access daily - snapshots of the OpenSSL development version at - https://www.openssl.org/source/snapshot/, - or get it by anonymous Git access. - -* Where is the documentation? - - OpenSSL is a library that provides cryptographic functionality to - applications such as secure web servers. Be sure to read the - documentation of the application you want to use. The INSTALL file - explains how to install this library. - - OpenSSL includes a command line utility that can be used to perform a - variety of cryptographic functions. It is described in the openssl(1) - manpage. Documentation for developers is currently being written. Many - manual pages are available; overviews of libcrypto and - libssl are given in the crypto(7) and - ssl(7) manpages. - - The OpenSSL manpages are installed in /usr/local/ssl/man/ (or a - different directory if you specified one as described in INSTALL). - In addition, you can read the most current versions at - https://www.openssl.org/docs/. Note that the online documents refer - to the very latest development versions of OpenSSL and may include features - not present in released versions. If in doubt refer to the documentation - that came with the version of OpenSSL you are using. The pod format - documentation is included in each OpenSSL distribution under the docs - directory. - -* I need a FIPS validated offering - - Please see https://www.openssl.org/docs/fips.html. - -* How can I contact the OpenSSL developers? - - The README file describes how to submit bug reports and patches to - OpenSSL. Information on the OpenSSL mailing lists is available from - https://www.openssl.org/community/mailinglists.html. - -* Where can I get a compiled version of OpenSSL? - - You can find pointers to binary distributions in - https://www.openssl.org/community/binaries.html. - - Some applications that use OpenSSL are distributed in binary form. - When using such an application, you don't need to install OpenSSL - yourself; the application will include the required parts (e.g. DLLs). - - If you want to build OpenSSL on a Windows system and you don't have - a C compiler, read the "Mingw32" section of INSTALL.W32 for information - on how to obtain and install the free GNU C compiler. - - A number of Linux and *BSD distributions include OpenSSL. - -* Why aren't tools like 'autoconf' and 'libtool' or 'cmake' used? - - A number of these tools are great and wonderful, but are usually - centered around one or a few platforms. 'autoconf' and 'libtool' are - Unix centric. 'cmake' is a bit more widely spread, but not enough to - cover the platforms we support. - - For OpenSSL 1.1, we decided to base our build system on perl, - information files and build file (Makefile) templates, thereby - covering all the systems we support. Perl was the base language of - choice because we already use it in diverse scripts, and it's one of - the most widely spread scripting languages. - -* How do I check the authenticity of the OpenSSL distribution? - - We provide PGP signatures and a variety of digests on each release. - For example, one of the following might work on your system: - - sha1sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha1 - sha256sum TARBALL | awk '{print $1;}' | cmp - TARBALL.sha256 - - You can check authenticity using pgp or gpg. You need the OpenSSL OMC - member public key used to sign it (download it from a key server or see a - list of keys at https://www.openssl.org/community/omc.html). Then - just do: - - pgp TARBALL.asc - -* How does the versioning scheme work? - - Please see - https://www.openssl.org/policies/general/versioning-policy.html. - -* 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@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 deleted file mode 100644 index 6b0e3bd2..00000000 --- a/docs/faq-6-old.txt +++ /dev/null @@ -1,14 +0,0 @@ -#### Older Versions and Platforms - -* 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. - -* 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. - diff --git a/docs/faq.md.tt b/docs/faq.md.tt deleted file mode 100644 index be755b70..00000000 --- a/docs/faq.md.tt +++ /dev/null @@ -1,14 +0,0 @@ ---- -breadcrumb: Frequently Asked Questions -header-includes: | - ---- -# Frequently Asked Questions - -[% INCLUDE "faq.inc" %] diff --git a/docs/index.md b/docs/index.md index 655a06ef..b994f066 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,8 +3,6 @@ breadcrumb: Documentation --- # Documentation -The [frequently-asked questions (FAQ)](faq.html) page is available. - A good starting point for understanding some of the key concepts in OpenSSL 3.0 is the libcrypto [manual page](https://www.openssl.org/docs/man3.0/man7/crypto.html). diff --git a/inc/pandoc-body-prologue.html5 b/inc/pandoc-body-prologue.html5 index e53483b5..0e498872 100644 --- a/inc/pandoc-body-prologue.html5 +++ b/inc/pandoc-body-prologue.html5 @@ -21,7 +21,7 @@
  1. Home
  2. Blog
  3. Downloads
    4. -
  4. Docs
    5. +
  5. Docs
  6. News
  7. Policies
  8. Community
    9. diff --git a/inc/screen.css b/inc/screen.css index ff2b4657..eb448614 100644 --- a/inc/screen.css +++ b/inc/screen.css @@ -1577,124 +1577,3 @@ table > tr:nth-child(even), table > thead + tbody > tr:nth-child(odd), table > : } 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: - * - *
    - * ... - *
      - *
    • - *

      FAQ entry title

      - *

      FAQ entry text

      - *

      more text

      - *

      more text

      - *

      more text

      - *
      • - * ... - *
    - * ... - *
    - * - * One could have argued for using
    and
    , 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; -} - diff --git a/source/index.md.tt b/source/index.md.tt index a39f8e48..95a6f24b 100644 --- a/source/index.md.tt +++ b/source/index.md.tt @@ -73,10 +73,9 @@ Guide](https://www.openssl.org/docs/man3.1/man7/migration_guide.html) When building a release for the first time, please make sure to look at the INSTALL file in the distribution along with any NOTES file -applicable to your platform. If you have problems, look at the FAQ, -which can be found [online](/docs/faq.html). If you still need more -help, then join the [openssl-users](/community/mailinglists.html) email -list and post a question there. +applicable to your platform. If you have problems, then join the +[openssl-users](/community/mailinglists.html) email list and post a +question there. PGP keys for the signatures are available from the [OTC page](https://www.openssl.org/community/otc.html). Current members that