add to v2.8.0 docs (#390)

* tls: add `trust_pool*` docs

* add a short note about the embedded filesystem.

---------

Co-authored-by: Francis Lavoie <lavofr@gmail.com>

src/docs/markdown/caddyfile/directives/acme_server.md

@@ -18,9 +18,19 @@ Using ACME server defaults, ACME clients should simply be configured to use `htt
 
 ```caddy-d
 acme_server [<matcher>] {
-	ca        <id>
+	ca         <id>
-	lifetime  <duration>
+	lifetime   <duration>
-	resolvers <resolvers...>
+	resolvers  <resolvers...>
+	challenges <challenges...>
+	allow_wildcard_names
+	allow {
+		domains <domains...>
+		ip_ranges <addresses...>
+	}
+	deny {
+		domains <domains...>
+		ip_ranges <addresses...>
+	}
 }
 ```
 
@@ -30,6 +40,15 @@ acme_server [<matcher>] {
 
 - **resolvers** are the addresses of DNS resolvers to use when looking up the TXT records for solving ACME DNS challenges. Accepts [network addresses](/docs/conventions#network-addresses) defaulting to UDP and port 53 unless specified. If the host is an IP address, it will be dialed directly to resolve the upstream server. If the hot is not an IP address, the addresses are resolved using the [name resolution convention](https://golang.org/pkg/net/#hdr-Name_Resolution) of the Go standard library. If multiple resolvers are specified, then one is chosen at random.
 
+- **challenges** sets the enabled challenge types. If not set or the directive is used without values, then all challenge types are enabled. Accepted values are: http-01, tls-alpn-01, dns-01.
+
+- **allow_wildcard_names** enables issuing of certificates with wildcard SAN (Subject Alternative Name)
+
+- **allow**, **deny** configure the operational policy of the `acme_server`. The policy evaluation follows the criteria described by Step-CA [here](https://smallstep.com/docs/step-ca/policies/#policy-evaluation).
+
+	- **domains** sets the subject domain names to be allowed or denied per the policy evaluation criteria.
+
+	- **ip_ranges** sets the subject IP ranges to be allowed or denied per the policy evaluation criteria.
 
 ## Examples
 

src/docs/markdown/caddyfile/directives/file_server.md

@@ -45,6 +45,8 @@ file_server [<matcher>] [browse] {
 
 - **fs** <span id="fs"/> specifies an alternate (perhaps virtual) file system to use. Any Caddy module in the `caddy.fs` namespace can be used here. Any root path/prefix will still apply to alternate file system modules. By default, the local disk is used.
 
+	[`xcaddy`](/docs/build#xcaddy) v0.4.0 introduces the [`--embed` flag](https://github.com/caddyserver/xcaddy#custom-builds) to embed a filesystem tree into the custom Caddy build, and registers an `fs` module named `embedded` which allows your static site to be distributed as a Caddy executable.
+
 - **root** <span id="root"/> sets the path to the site root. It's similar to the [`root`](root) directive except it applies to this file server instance only and overrides any other site root that may have been defined. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this handler. For other directives (like [`try_files`](try_files) or [`templates`](templates)) to know the same site root, use the [`root`](root) directive instead.
 
 - **hide** <span id="hide"/> is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default.

src/docs/markdown/caddyfile/directives/reverse_proxy.md

@@ -511,7 +511,7 @@ transport http {
 	tls_insecure_skip_verify
 	tls_curves <curves...>
 	tls_timeout <duration>
-	tls_trusted_ca_certs <pem_files...>
+	tls_trust_pool <module>
 	tls_server_name <server_name>
 	tls_renegotiation <level>
 	tls_except_ports <ports...>
@@ -557,7 +557,7 @@ transport http {
 
 - **tls_timeout** <span id="tls_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout.
 
-- **tls_trusted_ca_certs** <span id="tls_trusted_ca_certs"/> is a list of PEM files that specify CA public keys to trust when connecting to the backend.
+- **tls_trust_pool** <span id="tls_trust_pool"/> configures the source of trusted certificate authorities similar to the [`trust_pool` sub-directive](/docs/caddyfile/directives/tls#trust_pool) described on the `tls` directive documentation. The list of trust pool sources available in standard Caddy installation is available [here](/docs/caddyfile/directives/tls#trust-pool-providers).
 
 - **tls_server_name** <span id="tls_server_name"/> sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part.
 

src/docs/markdown/caddyfile/directives/tls.md

@@ -41,8 +41,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	reuse_private_keys
 	client_auth {
 		mode                   [request|require|verify_if_given|require_and_verify]
-		trusted_ca_cert        <base64_der>
+		trust_pool             <module>
-		trusted_ca_cert_file   <filename>
 		trusted_leaf_cert      <base64_der>
 		trusted_leaf_cert_file <filename>
 		verifier 			   <module>
@@ -143,9 +142,9 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari
 
     Default: `require_and_verify` if any `trusted_ca_cert` or `trusted_leaf_cert` are provided; otherwise, `require`.
 	
-  - **trusted_ca_cert** <span id="trusted_ca_cert"/> is a base64 DER-encoded CA certificate against which to validate client certificates.
+  - **trust_pool** <span id="trust_pool"/> configures the source of certificate authorities (CA) providing certificates against which to validate client certificates.
 	
-  - **trusted_ca_cert_file** <span id="trusted_ca_cert_file"/> is a path to a PEM CA certificate file against which to validate client certificates.
+	The certificate authority used providing the pool of trusted certificates and the configuration within the segment depends on the configured source of trust pool module. The standard modules available in Caddy are [listed below](#trust-pool-providers). The full list of modules, including 3rd-party, is listed in the [`trust_pool` JSON documentation](/docs/json/apps/http/servers/tls_connection_policies/client_authentication/#trust_pool).
 
   - **trusted_leaf_cert** <span id="trusted_leaf_cert"/> is a base64 DER-encoded client leaf certificate to accept.
 
@@ -165,6 +164,127 @@ Keep in mind that Let's Encrypt may send you emails about your certificate neari
 
 - **insecure_secrets_log** <span id="insecure_secrets_log"/> enables logging of TLS secrets to a file. This is also known as `SSLKEYLOGFILE`. Uses NSS key log format, which can then be parsed by Wireshark or other tools. ⚠️ **Security Warning:** This is insecure as it allows other programs or tools to decrypt TLS connections, and therefore completely compromises security. However, this capability can be useful for debugging and troubleshooting.
 
+### Trust Pool Providers
+
+These are the standard trust pool providers that can be used in the `trust_pool` subdirective:
+
+#### inline
+
+The `inline` module parses the trusted root certificates as listed in the Caddyfile directly in base64 DER-encoded format. The `trust_der` directive may be repeated multiple times.
+
+```caddy-d
+trust_pool inline {
+	trust_der      <base64_der>
+}
+```
+
+- **trust_der** <span id="trust_der"/> is a base64 DER-encoded CA certificate against which to validate client certificates.
+
+#### file
+
+The `file` module reads the trusted root certificates from PEM files from disk. The `pem_file` directive can accept multiple file paths on the same line and may be repeated multiple times.
+
+```caddy-d
+... file [<pem_file>...] {
+	pem_file <pem_file>...
+}
+```
+
+- **pem_file** <span id="pem_file"/> is a path to a PEM CA certificate file against which to validate client certificates.
+
+#### pki_root
+
+The `pki_root` module obtains the _root_ and trusts certificates from the certificate authority defined in the [PKI app](/docs/caddyfile/options#pki-options). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times.
+
+```caddy-d
+... pki_root [<ca_name>...] {
+	authority <ca_name>...
+}
+```
+
+- **authority** <span id="authority"/> is the name of the certificate authority configured in the PKI app.
+
+#### pki_intermediate
+
+The `pki_intermediate` module obtains the _intermediate_ and trusts certificates from the certificate authority defined in the [PKI app](/docs/caddyfile/options#pki-options). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times.
+
+```caddy-d
+... pki_intermediate [<ca_name>...] {
+	authority <ca_name>...
+}
+```
+
+- **authority** <span id="authority"/> is the name of the certificate authority configured in the PKI app.
+
+#### storage
+
+The `storage` module extracts the trusted certificates root from Caddy [storage](/docs/caddyfile/options#storage). The `authority` directive can accept multiple authorities at the same time and may be repeated multiple times.
+
+```caddy-d
+... storage [<storage_keys>...] {
+	storage <storage_module>
+	keys    <storage_keys>...
+}
+```
+
+- **storage** <span id="storage"/> is an optional storage module to use. If not specified, the default storage module will be used. If specified, it may be specified only once.
+
+- **keys** <span id="keys"/> is the list of storage keys at which the PEM files of the certificates are stored. The directive accepts multiple values on the same line and may be specified multiple times.
+
+#### http
+
+The `http` module obtains the trusted certificates from HTTP endpoints. The `endpoints` directive can accept multiple endpoints at the same time and may be repeated multiple times.
+
+```caddy-d
+... http [<endpoints...>] {
+	endpoints   <endpoints...>
+	tls         <tls_config>
+}
+```
+
+- **endpoints** <span id="endpoints"/> is the list of HTTP endpoints from which to obtain certificates. The directive accepts multiple values on the same line and may be specified multiple times.
+
+- **tls** <span id="tls"/> is an optional TLS configuration to use when connecting to the HTTP endpoint. The segment parsing is defined in the [following section](#tls-1).
+
+##### TLS
+
+```caddy-d
+... {
+	ca                    <ca_module>
+	insecure_skip_verify
+	handshake_timeout     <duration>
+	server_name           <name>
+	renegotiation         <never|once|freely>
+}
+```
+
+- **ca** <span id="ca"/> is an optional directive to define the provider of trust pool. The configuration follows the same behavior of [`trust_pool`](#trust_pool). If specified, it may be specified only once.
+
+- **insecure_skip_verify** <span id="insecure_skip_verify"/> turns off TLS handshake verification, making the connection insecure and vulnerable to man-in-the-middle attacks. _Do not use in production._ The verification is done against either the certificate authorities trusted by the system or as determined by the [`ca`](#ca) directive.
+
+- **handshake_timeout** <span id="handshake_timeout"/> is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout..
+
+- **server_name** <span id="server_name"/> sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part.
+
+- **renegotiation** <span id="renegotiation"/> sets the TLS renegotiation level. TLS renegotiation is the act of performing subsequent handshakes after the first. The level may be one of:
+  - `never` (the default) disables renegotiation.
+  - `once` allows a remote server to request renegotiation once per connection.
+  - `freely` allows a remote server to repeatedly request renegotiation.
+
+#### lazy
+
+The `lazy` module defers the generation of the certificate pool from the guest module to demand-time rather than at provisionig time. The gain of the lazy load adds a risk of failure to load the certificates at demand time because the validation that's typically done at provisioning is deferred. Eager validation is a configuration option.
+
+```caddy-d
+... lazy {
+	backend           <ca_module>
+	eager_validation
+}
+```
+
+- **backend** <span id="backend"/> configures the deferred [trust pool provider](#trust-pool-providers). The configuration follows the same behavior of [`trust_pool`](#trust_pool).
+
+- **eager_validation** <span id="eager_validation"/> turns on eager validation of the trust pool provider by trying to obtain the trust certifiate during the validation phase at configuration load-time. The eager loading is used only for error-checking. The result is discarded and will be loaded again on-demand at runtime.
 
 ### Issuers