curl-curl/docs
Wyatt O'Day 1dc6ddde06
mbedTLS: cleanup insecure/deprecated code
1. With `MBEDTLS_SSL_PROTO_TLS1_2` not enabled, the mbedTLS code was not
able to connect to any server due to broken logic in curl's
`mbed_set_ssl_version_min_max()`. Now it correctly sets the minimum
supported TLS version based on what is compiled in the library.

2. If debugging is enabled, move the debugging enabling earlier in the
`mbed_connect_step1()` so that verbose errors are actually displayed if
failures happen (see the previous point -- it would've made debugging
that issue easier).

3. Remove the constant `mbedtls_x509_crt_profile_fr` and instead use
mbedTLS-included profile `mbedtls_x509_crt_profile_next` with
`mbedtls_ssl_conf_cert_profile()`. This will follow the latest standards
as new mbedTLS versions are released (rather than being stuck-in-time
until someone comes along to fix what was hard-coded here). This has the
immediate benefit of no longer supporting SHA1 certs and insecure RSA
key-lengths (1024). This fix immediately prevents previously possible
MITM attacks (SHA1 hashes and RSA-1024 keys can be forged relatively
easily by nation-state actors and criminal organizations with
deep-pockets).

4. Added [predictive
resistance](https://mbed-tls.readthedocs.io/en/latest/kb/how-to/add-a-random-generator/#enabling-prediction-resistance)
to the random number generator (adding more entropy to the RNG).

5. Split the random number generator into initialization, the actual
random generation, and the "freeing" of the resources. This
significantly reduces the overhead of using the RNG.

6. Removed the separate RNG function in the TLS connect stage (instead
use the "main" one) and remove the ad-hoc threading support. Instead
properly document how to enable threading in mbedTLS. As it was, other
internals of mbedTLS could have race conditions (in the RSA module in
particular) if `MBEDTLS_THREADING_C` was *not* enabled. And if it is
enabled, then these race-conditions cannot happen. And also, if
MBEDTLS_THREADING_C is enabled then the RNG functions [are fully
thread-safe](https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading/).

   So, the previous ad-hoc threading support was both partial and broken.

7. Enable support for disabling `MBEDTLS_PEM_PARSE_C`.

8. Add support for `CURLOPT_SSLCERTTYPE` so user can specify `PEM` or
`DER` and get faster execution.

Closes #19983
2025-12-20 17:33:57 +01:00
..
cmdline-opts compressed.md: might generate a huge amount of bytes 2025-12-19 10:11:27 +01:00
examples openssl: drop includes unused or duplicate 2025-12-20 13:51:05 +01:00
internals curlx: add curlx_rename(), fix to support long filenames on Windows 2025-12-20 16:03:11 +01:00
libcurl mbedTLS: cleanup insecure/deprecated code 2025-12-20 17:33:57 +01:00
tests GHA/checkdocs: re-enable proselint, update setup, fix issues found 2025-12-11 11:42:28 +01:00
.gitignore docs: add RELEASE-TOOLS.md.dist to .gitignore 2024-07-01 22:49:55 +02:00
ALTSVC.md docs: fold long lines 2025-12-11 11:42:28 +01:00
BINDINGS.md tidy-up: URLs (cont.) and mdlinkcheck 2025-12-10 01:21:07 +01:00
BUG-BOUNTY.md tidy-up: URLs 2025-09-23 00:34:46 +02:00
BUGS.md docs: fix two typos 2025-07-01 22:53:04 +02:00
CIPHERS-TLS12.md docs: update CIPHERS.md 2024-08-12 23:35:56 +02:00
CIPHERS.md tidy-up: update MS links, allow long URLs via checksrc 2025-09-20 11:49:23 +02:00
CMakeLists.txt tests: move test docs into /docs 2025-05-28 15:00:03 +02:00
CODE_OF_CONDUCT.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
CODE_REVIEW.md docs: fix broken link in CODE_REVIEW.md 2025-06-21 10:32:06 +02:00
CONTRIBUTE.md tidy-up: URLs 2025-12-09 00:19:10 +01:00
curl-config.md docs: minor edits to please the new spellchecker regime 2025-02-27 13:15:21 +01:00
CURL-DISABLE.md build: add build-level CURL_DISABLE_TYPECHECK options 2025-11-21 13:48:35 +01:00
CURLDOWN.md misc: fix typos 2025-07-12 08:59:44 +02:00
DEPRECATE.md DEPRECATE: add CMake <3.18 deprecation for April 2026 2025-12-09 19:34:13 +01:00
DISTROS.md tidy-up: URLs 2025-12-09 00:19:10 +01:00
EARLY-RELEASE.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
ECH.md tidy-up: URLs 2025-12-09 00:19:10 +01:00
EXPERIMENTAL.md docs/EXPERIMENTAL.md: add a mention of HTTPSRR as experimental 2025-01-16 19:41:42 +01:00
FAQ.md tidy-up: miscellaneous 2025-12-12 04:18:48 +01:00
FEATURES.md FEATURES.md: fix typo 2024-08-23 08:46:09 +02:00
GOVERNANCE.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
HELP-US.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
HISTORY.md HISTORY: add current website stats 2025-12-16 23:33:54 +01:00
HSTS.md docs: bring back ALTSVC.md and HSTS.md 2024-12-09 09:32:19 +01:00
HTTP3.md GHA/checkdocs: re-enable proselint, update setup, fix issues found 2025-12-11 11:42:28 +01:00
HTTP-COOKIES.md tidy-up: URLs 2025-09-23 00:34:46 +02:00
HTTPSRR.md tidy-up: URLs 2025-09-23 00:34:46 +02:00
INFRASTRUCTURE.md GHA/checkdocs: re-enable proselint, update setup, fix issues found 2025-12-11 11:42:28 +01:00
INSTALL INSTALL: converted to markdown => INSTALL.md 2016-10-21 15:57:29 +02:00
INSTALL-CMAKE.md tidy-up: miscellaneous 2025-12-18 21:27:58 +01:00
INSTALL.md tidy-up: URLs 2025-12-09 00:19:10 +01:00
INTERNALS.md INTERNALS.md: add more dependency versions and dates 2025-11-25 11:11:06 +01:00
IPFS.md IPFS.md: wrap long lines 2025-12-08 17:28:43 +01:00
KNOWN_BUGS.md tidy-up: URLs (cont.) and mdlinkcheck 2025-12-10 01:21:07 +01:00
KNOWN_RISKS.md CURLOPT_ACCEPT_ENCODING.md: warn about the expansion 2025-12-19 10:44:43 +01:00
MAIL-ETIQUETTE.md docs: remove dead URLs 2025-12-05 23:41:41 +01:00
Makefile.am lib: keep timestamp in easy handle 2025-12-16 08:48:44 +01:00
MANUAL.md tidy-up: miscellaneous 2025-12-12 04:18:48 +01:00
mk-ca-bundle.md mk-ca-bundle.md: the file format docs URL is permaredirected 2025-12-08 22:07:32 +01:00
options-in-versions tool_getparam: add --knownhosts 2025-10-06 13:41:22 +02:00
README.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
RELEASE-PROCEDURE.md RELEASE-PROCEDURE.md: drop the _newslog edit mention 2025-09-08 11:12:47 +02:00
ROADMAP.md CI: add whitespace checker 2024-06-27 13:33:30 +02:00
runtests.md runtests: improve XML prolog check, enable -w permanently, fix two tests 2025-12-14 12:26:38 +01:00
RUSTLS.md tidy-up: URLs 2025-09-23 00:34:46 +02:00
SECURITY-ADVISORY.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
SPONSORS.md SPONSORS.md: clarify that we don't promise goods or services 2025-02-05 23:40:24 +01:00
SSL-PROBLEMS.md spelling: 'a' vs 'an' 2025-05-30 11:38:35 +02:00
SSLCERTS.md tidy-up: miscellaneous 2025-12-12 04:18:48 +01:00
testcurl.md tidy-up: URLs 2025-12-09 00:19:10 +01:00
THANKS tidy-up: miscellaneous 2025-11-17 13:32:43 +01:00
THANKS-filter RELEASE-NOTES: synced 2025-11-05 14:12:23 +01:00
TheArtOfHttpScripting.md tidy-up: miscellaneous 2025-12-12 04:18:48 +01:00
TODO.md TODO: consider a multi-threaded curl tool 2025-12-15 11:47:20 +01:00
URL-SYNTAX.md docs: switch more URLs to https:// 2025-12-08 12:57:51 +01:00
VERSIONS.md VERSIONS: 8.18.0 is now pending 2025-11-05 08:00:05 +01:00
VULN-DISCLOSURE-POLICY.md VULN-DISCLOSURE-POLICY: make it pass test 1275 2025-09-07 12:39:44 +02:00
wcurl.md badwords: make some words match case-insensitively 2025-11-27 15:10:34 +01:00

curl logo

Documentation

You find a mix of various documentation in this directory and subdirectories, using several different formats. Some of them are not ideal for reading directly in your browser.

If you would rather see the rendered version of the documentation, check out the curl website's documentation section for general curl stuff or the libcurl section for libcurl related documentation.