diff --git a/src/docs/markdown/caddyfile/directives/acme_server.md b/src/docs/markdown/caddyfile/directives/acme_server.md index d30bbc8..a074ab8 100644 --- a/src/docs/markdown/caddyfile/directives/acme_server.md +++ b/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 [] { - ca - lifetime - resolvers + ca + lifetime + resolvers + challenges + allow_wildcard_names + allow { + domains + ip_ranges + } + deny { + domains + ip_ranges + } } ``` @@ -30,6 +40,15 @@ acme_server [] { - **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 diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 59e463a..6434e3e 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -45,6 +45,8 @@ file_server [] [browse] { - **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** 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** 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. diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 380d250..1fdc564 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -511,7 +511,7 @@ transport http { tls_insecure_skip_verify tls_curves tls_timeout - tls_trusted_ca_certs + tls_trust_pool tls_server_name tls_renegotiation tls_except_ports @@ -557,7 +557,7 @@ transport http { - **tls_timeout** is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout. -- **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** 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** sets the server name used when verifying the certificate received in the TLS handshake. By default, this will use the upstream address' host part. diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 615e6fa..ec0970d 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -41,8 +41,7 @@ tls [internal|] | [ ] { reuse_private_keys client_auth { mode [request|require|verify_if_given|require_and_verify] - trusted_ca_cert - trusted_ca_cert_file + trust_pool trusted_leaf_cert trusted_leaf_cert_file verifier @@ -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** is a base64 DER-encoded CA certificate against which to validate client certificates. - - - **trusted_ca_cert_file** is a path to a PEM CA certificate file against which to validate client certificates. + - **trust_pool** configures the source of certificate authorities (CA) providing certificates 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** 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** 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 +} +``` + +- **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** 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 [...] { + authority ... +} +``` + +- **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 [...] { + authority ... +} +``` + +- **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** 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** 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 + tls +} +``` + +- **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** 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 + insecure_skip_verify + handshake_timeout + server_name + renegotiation +} +``` + +- **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** 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** is the maximum [duration](/docs/conventions#durations) to wait for the TLS handshake to complete. Default: No timeout.. + +- **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** 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 + eager_validation +} +``` + +- **backend** configures the deferred [trust pool provider](#trust-pool-providers). The configuration follows the same behavior of [`trust_pool`](#trust_pool). + +- **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