ssl: support Apple SecTrust configurations

- configure/cmake support for enabling the option
- supported in OpenSSL and GnuTLS backends
- when configured, Apple SecTrust is the default trust store
  for peer verification. When one of the CURLOPT_* for adding
  certificates is used, that default does not apply.
- add documentation of build options and SSL use

Closes #18703

docs/INSTALL-CMAKE.md

@@ -368,6 +368,7 @@ Details via CMake
 - `CURL_ZSTD`:                              Use zstd (`ON`, `OFF` or `AUTO`). Default: `AUTO`
 - `ENABLE_ARES`:                            Enable c-ares support. Default: `OFF`
 - `USE_APPLE_IDN`:                          Use Apple built-in IDN support. Default: `OFF`
+- `USE_APPLE_SECTRUST`:                     Use Apple OS-native certificate verification. Default: `OFF`
 - `USE_LIBIDN2`:                            Use libidn2 for IDN support. Default: `ON`
 - `USE_LIBRTMP`:                            Enable librtmp from rtmpdump. Default: `OFF`
 - `USE_NGHTTP2`:                            Use nghttp2 library. Default: `ON`

docs/INSTALL.md

@@ -153,6 +153,25 @@ conflicting identical symbol names.
 When you build with multiple TLS backends, you can select the active one at
 runtime when curl starts up.
 
+### Selecting TLS Trust Anchors Defaults
+
+Verifying a server certificate established a chain of trust that needs to
+start somewhere. Those "root" certificates make the set of Trust Anchors.
+
+While the build system tries to find good defaults on the platform you
+use, you may specify these explicitly. The following options are provided:
+
+ - `--with-ca-bundle=FILE`: the file that libcurl loads default root
+ certificates from.
+ - `--with-ca-path=DIRECTORY`: a directory in which root certificates files
+ are found.
+ - `--with-ca-embed=FILE`: a file read *at build time* and added to `libcurl`.
+ - `--with-ca-fallback`: an OpenSSL specific option for delegating default
+ trust anchor selection to what OpenSSL thinks is best, *if* there are
+no other certificates configured by the application.
+ - `--with-apple-sectrust`: use the system "SecTrust" service on Apple
+ operating systems for verification. (Added in 8.17.0)
+
 ## MultiSSL and HTTP/3
 
 HTTP/3 needs QUIC and QUIC needs TLS. Building libcurl with HTTP/3 and QUIC

docs/SSLCERTS.md

@@ -8,8 +8,10 @@ SPDX-License-Identifier: curl
 
 ## Native vs file based
 
-If curl was built with Schannel support, then curl uses the system native CA
-store for verification. All other TLS libraries use a file based CA store by
+If curl was built with Schannel support, then curl uses the Windows native CA
+store for verification. On Apple operating systems, it is possible to use Apple's
+"SecTrust" services for certain TLS backends, details below.
+All other TLS libraries use a file based CA store by
 default.
 
 ## Verification
@@ -71,8 +73,10 @@ another option to restrict search to the application's directory.
 
 ### Use the native store
 
-In several environments, in particular on Windows, you can ask curl to use the
-system's native CA store when verifying the certificate.
+In several environments, in particular on Microsoft and Apple operating
+systems, you can ask curl to use the system's native CA store when verifying
+the certificate. Depending on how curl was built, this may already be the
+default.
 
 With the curl command line tool: `--ca-native`.
 
@@ -102,14 +106,46 @@ latest Firefox bundle.
 
 ## Native CA store
 
-If curl was built with Schannel or was instructed to use the native CA Store,
-then curl uses the certificates that are built into the OS. These are the same
-certificates that appear in the Internet Options control panel (under Windows)
-or Keychain Access application (under macOS). Any custom security rules for
-certificates are honored.
+### Windows + Schannel
+
+If curl was built with Schannel, then curl uses the certificates that are
+built into the OS. These are the same certificates that appear in the
+Internet Options control panel (under Windows).
+Any custom security rules for certificates are honored.
 
 Schannel runs CRL checks on certificates unless peer verification is disabled.
 
+### Apple + OpenSSL/GnuTLS
+
+When curl is built with Apple SecTrust enabled and uses an OpenSSL compatible
+TLS backend or GnuTLS, the default verification is handled by that Apple
+service. As in:
+
+    curl https://example.com
+
+You may still provide your own certificates on the command line, such as:
+
+    curl --cacert mycerts.pem https://example.com
+
+In this situation, Apple SecTrust is **not** used and verification is done
+**only** with the trust anchors found in `mycerts.pem`. If you want **both**
+Apple SecTrust and your own file to be considered, use:
+
+    curl --ca-native --cacert mycerts.pem https://example.com
+
+
+#### Other Combinations
+
+How well the use of native CA stores work in all other combinations depends
+on the TLS backend and the OS. Many TLS backends offer functionality to access
+the native CA on a range of operating systems. Some provide this only on specific
+configurations.
+
+Specific support in curl exists for Windows and OpenSSL compatible TLS backends.
+It tries to load the certificates from the Windows "CA" and "ROOT" stores for
+transfers requesting the native CA. Due to Window's delayed population of those
+stores, this might not always find all certificates.
+
 ## HTTPS proxy
 
 curl can do HTTPS to the proxy separately from the connection to the server.

docs/cmdline-opts/ca-native.md

@@ -25,12 +25,14 @@ This option is independent of other CA certificate locations set at run time or
 build time. Those locations are searched in addition to the native CA store.
 
 This option works with OpenSSL and its forks (LibreSSL, BoringSSL, etc) on
-Windows. (Added in 7.71.0)
+Windows (Added in 7.71.0) and on Apple OS when libcurl is built with
+Apple SecTrust enabled. (Added in 8.17.0)
 
 This option works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo,
 Fedora, RHEL), macOS, Android and iOS. (Added in 8.3.0)
 
-This option works with GnuTLS. (Added in 8.5.0)
+This option works with GnuTLS (Added in 8.5.0) and also uses Apple
+SecTrust when libcurl is built with it. (Added in 8.17.0)
 
 This option works with rustls on Windows, macOS, Android and iOS. On Linux it
 is equivalent to using the Mozilla CA certificate bundle. When used with rustls