From dcdc5f416d45fa099c9f5c0a1d535f2813de7221 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Aug 2016 14:47:20 +0200 Subject: docs-make: have markdown files use .md --- docs/Makefile.am | 2 +- docs/SECURITY | 110 --------------------------------------------------- docs/SECURITY.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/SSL-PROBLEMS | 87 ---------------------------------------- docs/SSL-PROBLEMS.md | 87 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 198 insertions(+), 198 deletions(-) delete mode 100644 docs/SECURITY create mode 100644 docs/SECURITY.md delete mode 100644 docs/SSL-PROBLEMS create mode 100644 docs/SSL-PROBLEMS.md diff --git a/docs/Makefile.am b/docs/Makefile.am index e11c42196..445d3fa2e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -37,7 +37,7 @@ EXTRA_DIST = MANUAL BUGS CONTRIBUTE.md FAQ FEATURES INTERNALS.md SSLCERTS.md \ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS \ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY.md INSTALL \ $(PDFPAGES) LICENSE-MIXING README.netware INSTALL.devcpp \ - MAIL-ETIQUETTE HTTP-COOKIES.md SECURITY RELEASE-PROCEDURE SSL-PROBLEMS \ + MAIL-ETIQUETTE HTTP-COOKIES.md SECURITY.md RELEASE-PROCEDURE SSL-PROBLEMS.md \ HTTP2.md ROADMAP.md CODE_OF_CONDUCT.md CODE_STYLE.md CHECKSRC.md MAN2HTML= roffit $< >$@ diff --git a/docs/SECURITY b/docs/SECURITY deleted file mode 100644 index 3c07e0bbe..000000000 --- a/docs/SECURITY +++ /dev/null @@ -1,110 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - -curl security for developers -============================ - -This document is intended to provide guidance to curl developers on how -security vulnerabilities should be handled. - -Publishing Information ----------------------- - -All known and public curl or libcurl related vulnerabilities are listed on -[the curl web site security page](https://curl.haxx.se/docs/security.html). - -Security vulnerabilities should not be entered in the project's public bug -tracker unless the necessary configuration is in place to limit access to the -issue to only the reporter and the project's security team. - -Vulnerability Handling ----------------------- - -The typical process for handling a new security vulnerability is as follows. - -No information should be made public about a vulnerability until it is -formally announced at the end of this process. That means, for example that a -bug tracker entry must NOT be created to track the issue since that will make -the issue public and it should not be discussed on any of the project's public -mailing lists. Also messages associated with any commits should not make -any reference to the security nature of the commit if done prior to the public -announcement. - -- The person discovering the issue, the reporter, reports the vulnerability - privately to `curl-security@haxx.se`. That's an email alias that reaches a - handful of selected and trusted people. - -- Messages that do not relate to the reporting or managing of an undisclosed - security vulnerability in curl or libcurl are ignored and no further action - is required. - -- A person in the security team sends an e-mail to the original reporter to - acknowledge the report. - -- The security team investigates the report and either rejects it or accepts - it. - -- If the report is rejected, the team writes to the reporter to explain why. - -- If the report is accepted, the team writes to the reporter to let him/her - know it is accepted and that they are working on a fix. - -- The security team discusses the problem, works out a fix, considers the - impact of the problem and suggests a release schedule. This discussion - should involve the reporter as much as possible. - -- The release of the information should be "as soon as possible" and is most - often synced with an upcoming release that contains the fix. If the - reporter, or anyone else, thinks the next planned release is too far away - then a separate earlier release for security reasons should be considered. - -- Write a security advisory draft about the problem that explains what the - problem is, its impact, which versions it affects, solutions or - workarounds, when the release is out and make sure to credit all - contributors properly. - -- Request a CVE number from - [distros@openwall](http://oss-security.openwall.org/wiki/mailing-lists/distros) - when also informing and preparing them for the upcoming public security - vulnerability announcement - attach the advisory draft for information. Note - that 'distros' won't accept an embargo longer than 19 days and they do not - care for Windows-specific flaws. For windows-specific flaws, request CVE - directly from MITRE. - -- Update the "security advisory" with the CVE number. - -- The security team commits the fix in a private branch. The commit message - should ideally contain the CVE number. This fix is usually also distributed - to the 'distros' mailing list to allow them to use the fix prior to the - public announcement. - -- At the day of the next release, the private branch is merged into the master - branch and pushed. Once pushed, the information is accessible to the public - and the actual release should follow suit immediately afterwards. - -- The project team creates a release that includes the fix. - -- The project team announces the release and the vulnerability to the world in - the same manner we always announce releases. It gets sent to the - curl-announce, curl-library and curl-users mailing lists. - -- The security web page on the web site should get the new vulnerability - mentioned. - - - -CURL-SECURITY (at haxx dot se) ------------------------------- - -Who is on this list? There are a couple of criteria you must meet, and then we -might ask you to join the list or you can ask to join it. It really isn't very -formal. We basically only require that you have a long-term presence in the -curl project and you have shown an understanding for the project and its way -of working. You must've been around for a good while and you should have no -plans in vanishing in the near future. - -We do not make the list of partipants public mostly because it tends to vary -somewhat over time and a list somewhere will only risk getting outdated. diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 000000000..3c07e0bbe --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,110 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + +curl security for developers +============================ + +This document is intended to provide guidance to curl developers on how +security vulnerabilities should be handled. + +Publishing Information +---------------------- + +All known and public curl or libcurl related vulnerabilities are listed on +[the curl web site security page](https://curl.haxx.se/docs/security.html). + +Security vulnerabilities should not be entered in the project's public bug +tracker unless the necessary configuration is in place to limit access to the +issue to only the reporter and the project's security team. + +Vulnerability Handling +---------------------- + +The typical process for handling a new security vulnerability is as follows. + +No information should be made public about a vulnerability until it is +formally announced at the end of this process. That means, for example that a +bug tracker entry must NOT be created to track the issue since that will make +the issue public and it should not be discussed on any of the project's public +mailing lists. Also messages associated with any commits should not make +any reference to the security nature of the commit if done prior to the public +announcement. + +- The person discovering the issue, the reporter, reports the vulnerability + privately to `curl-security@haxx.se`. That's an email alias that reaches a + handful of selected and trusted people. + +- Messages that do not relate to the reporting or managing of an undisclosed + security vulnerability in curl or libcurl are ignored and no further action + is required. + +- A person in the security team sends an e-mail to the original reporter to + acknowledge the report. + +- The security team investigates the report and either rejects it or accepts + it. + +- If the report is rejected, the team writes to the reporter to explain why. + +- If the report is accepted, the team writes to the reporter to let him/her + know it is accepted and that they are working on a fix. + +- The security team discusses the problem, works out a fix, considers the + impact of the problem and suggests a release schedule. This discussion + should involve the reporter as much as possible. + +- The release of the information should be "as soon as possible" and is most + often synced with an upcoming release that contains the fix. If the + reporter, or anyone else, thinks the next planned release is too far away + then a separate earlier release for security reasons should be considered. + +- Write a security advisory draft about the problem that explains what the + problem is, its impact, which versions it affects, solutions or + workarounds, when the release is out and make sure to credit all + contributors properly. + +- Request a CVE number from + [distros@openwall](http://oss-security.openwall.org/wiki/mailing-lists/distros) + when also informing and preparing them for the upcoming public security + vulnerability announcement - attach the advisory draft for information. Note + that 'distros' won't accept an embargo longer than 19 days and they do not + care for Windows-specific flaws. For windows-specific flaws, request CVE + directly from MITRE. + +- Update the "security advisory" with the CVE number. + +- The security team commits the fix in a private branch. The commit message + should ideally contain the CVE number. This fix is usually also distributed + to the 'distros' mailing list to allow them to use the fix prior to the + public announcement. + +- At the day of the next release, the private branch is merged into the master + branch and pushed. Once pushed, the information is accessible to the public + and the actual release should follow suit immediately afterwards. + +- The project team creates a release that includes the fix. + +- The project team announces the release and the vulnerability to the world in + the same manner we always announce releases. It gets sent to the + curl-announce, curl-library and curl-users mailing lists. + +- The security web page on the web site should get the new vulnerability + mentioned. + + + +CURL-SECURITY (at haxx dot se) +------------------------------ + +Who is on this list? There are a couple of criteria you must meet, and then we +might ask you to join the list or you can ask to join it. It really isn't very +formal. We basically only require that you have a long-term presence in the +curl project and you have shown an understanding for the project and its way +of working. You must've been around for a good while and you should have no +plans in vanishing in the near future. + +We do not make the list of partipants public mostly because it tends to vary +somewhat over time and a list somewhere will only risk getting outdated. diff --git a/docs/SSL-PROBLEMS b/docs/SSL-PROBLEMS deleted file mode 100644 index e63987101..000000000 --- a/docs/SSL-PROBLEMS +++ /dev/null @@ -1,87 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - -SSL problems - - First, let's establish that we often refer to TLS and SSL interchangeably as - SSL here. The current protocol is called TLS, it was called SSL a long time - ago. - - There are several known reasons why a connection that involves SSL might - fail. This is a document that attempts to details the most common ones and - how to mitigate them. - -CA certs - - CA certs are used to digitally verify the server's certificate. You need a - "ca bundle" for this. See lots of more details on this in the SSLCERTS - document. - -CA bundle missing intermediate certificates - - When using said CA bundle to verify a server cert, you will experience - problems if your CA cert does not have the certificates for the - intermediates in the whole trust chain. - -Protocol version - - Some broken servers fail to support the protocol negotiation properly that - SSL servers are supposed to handle. This may cause the connection to fail - completely. Sometimes you may need to explicitly select a SSL version to use - when connecting to make the connection succeed. - - An additional complication can be that modern SSL libraries sometimes are - built with support for older SSL and TLS versions disabled! - - All versions of SSL are considered insecure and should be avoided. Use TLS. - -Ciphers - - Clients give servers a list of ciphers to select from. If the list doesn't - include any ciphers the server wants/can use, the connection handshake - fails. - - curl has recently disabled the user of a whole bunch of seriously insecure - ciphers from its default set (slightly depending on SSL backend in use). - - You may have to explicitly provide an alternative list of ciphers for curl - to use to allow the server to use a WEAK cipher for you. - - Note that these weak ciphers are identified as flawed. For example, this - includes symmetric ciphers with less than 128 bit keys and RC4. - - WinSSL in Windows XP is not able to connect to servers that no longer - support the legacy handshakes and algorithms used by those versions, so we - advice against building curl to use WinSSL on really old Windows versions. - - References: - - https://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01 - -Allow BEAST - - BEAST is the name of a TLS 1.0 attack that surfaced 2011. When adding means - to mitigate this attack, it turned out that some broken servers out there in - the wild didn't work properly with the BEAST mitigation in place. - - To make such broken servers work, the --ssl-allow-beast option was - introduced. Exactly as it sounds, it re-introduces the BEAST vulnerability - but on the other hand it allows curl to connect to that kind of strange - servers. - -Disabling certificate revocation checks - - Some SSL backends may do certificate revocation checks (CRL, OCSP, etc) - depending on the OS or build configuration. The --ssl-no-revoke option was - introduced in 7.44.0 to disable revocation checking but currently is only - supported for WinSSL (the native Windows SSL library), with an exception in - the case of Windows' Untrusted Publishers blacklist which it seems can't be - bypassed. This option may have broader support to accommodate other SSL - backends in the future. - - References: - - https://curl.haxx.se/docs/ssl-compared.html diff --git a/docs/SSL-PROBLEMS.md b/docs/SSL-PROBLEMS.md new file mode 100644 index 000000000..91803e22d --- /dev/null +++ b/docs/SSL-PROBLEMS.md @@ -0,0 +1,87 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + +# SSL problems + + First, let's establish that we often refer to TLS and SSL interchangeably as + SSL here. The current protocol is called TLS, it was called SSL a long time + ago. + + There are several known reasons why a connection that involves SSL might + fail. This is a document that attempts to details the most common ones and + how to mitigate them. + +## CA certs + + CA certs are used to digitally verify the server's certificate. You need a + "ca bundle" for this. See lots of more details on this in the SSLCERTS + document. + +## CA bundle missing intermediate certificates + + When using said CA bundle to verify a server cert, you will experience + problems if your CA cert does not have the certificates for the + intermediates in the whole trust chain. + +## Protocol version + + Some broken servers fail to support the protocol negotiation properly that + SSL servers are supposed to handle. This may cause the connection to fail + completely. Sometimes you may need to explicitly select a SSL version to use + when connecting to make the connection succeed. + + An additional complication can be that modern SSL libraries sometimes are + built with support for older SSL and TLS versions disabled! + + All versions of SSL are considered insecure and should be avoided. Use TLS. + +## Ciphers + + Clients give servers a list of ciphers to select from. If the list doesn't + include any ciphers the server wants/can use, the connection handshake + fails. + + curl has recently disabled the user of a whole bunch of seriously insecure + ciphers from its default set (slightly depending on SSL backend in use). + + You may have to explicitly provide an alternative list of ciphers for curl + to use to allow the server to use a WEAK cipher for you. + + Note that these weak ciphers are identified as flawed. For example, this + includes symmetric ciphers with less than 128 bit keys and RC4. + + WinSSL in Windows XP is not able to connect to servers that no longer + support the legacy handshakes and algorithms used by those versions, so we + advice against building curl to use WinSSL on really old Windows versions. + + References: + + https://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01 + +## Allow BEAST + + BEAST is the name of a TLS 1.0 attack that surfaced 2011. When adding means + to mitigate this attack, it turned out that some broken servers out there in + the wild didn't work properly with the BEAST mitigation in place. + + To make such broken servers work, the --ssl-allow-beast option was + introduced. Exactly as it sounds, it re-introduces the BEAST vulnerability + but on the other hand it allows curl to connect to that kind of strange + servers. + +## Disabling certificate revocation checks + + Some SSL backends may do certificate revocation checks (CRL, OCSP, etc) + depending on the OS or build configuration. The --ssl-no-revoke option was + introduced in 7.44.0 to disable revocation checking but currently is only + supported for WinSSL (the native Windows SSL library), with an exception in + the case of Windows' Untrusted Publishers blacklist which it seems can't be + bypassed. This option may have broader support to accommodate other SSL + backends in the future. + + References: + + https://curl.haxx.se/docs/ssl-compared.html -- cgit v1.2.3