diff --git a/src/docs/markdown/automatic-https.md b/src/docs/markdown/automatic-https.md index 21c62de..5514941 100644 --- a/src/docs/markdown/automatic-https.md +++ b/src/docs/markdown/automatic-https.md @@ -79,6 +79,10 @@ Any of the following will prevent automatic HTTPS from being activated, either i - Listening exclusively on the HTTP port - Manually loading certificates (unless [this config property](/docs/json/apps/http/servers/automatic_https/ignore_loaded_certificates/) is true) +**Special cases:** + +- Domains ending in `.ts.net` will not be managed by Caddy. Instead, Caddy will automatically attempt to get these certificates at handshake-time from the locally-running [Tailscale](https://tailscale.com) instance. This requires that [HTTPS is enabled in your Tailscale account](https://tailscale.com/kb/1153/enabling-https/) and the Caddy process must either be running as root, or you must configure `tailscaled` to give your Caddy user [permission to fetch certificates](https://github.com/caddyserver/caddy/pull/4541#issuecomment-1021568348). + ## Effects diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 3399e89..680f94d 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -42,7 +42,8 @@ tls [internal|] | [ ] { trusted_leaf_cert trusted_leaf_cert_file } - issuer [] + issuer [] + get_certificate [] } ``` @@ -105,6 +106,7 @@ tls [internal|] | [ ] { Multiple `trusted_*` directives may be used to specify multiple CA or leaf certificates. Client certificates which are not listed as one of the leaf certificates or signed by any of the specified CAs will be rejected according to the **mode**. - **issuer** configures a custom certificate issuer, or a source from which to obtain certificates. Which issuer is used and the options that follow in this segment depend on the issuer modules that are available (see below for the standard issuers; plugins may add others). Some of the other subdirectives such as `ca` and `dns` are actually shortcuts for configuring the `acme` issuer (and this subdirective was added later), so specifying this directive and some of the others is confusing and thus prohibited. This subdirective can be specified multiple times to configure multiple, redundant issuers; if one fails to issue a cert, the next one will be tried. +- **get_certificate** enables getting certificates from a _manager module_ at handshake-time. [See below for standard certificate manager modules.](#certificate-managers) ### Issuers @@ -190,6 +192,36 @@ Obtains certificates from an internal certificate authority. - **sign_with_root** forces the root to be the issuer instead of the intermediate. This is NOT recommended and should only be used when devices/clients do not properly validate certificate chains (very uncommon). + +### Certificate Managers + +Certificate manager modules are distinct from issuer modules in that use of manager modules implies that an external tool or service is keeping the certificate renewed, whereas an issuer module implies that Caddy itself is managing the certificate. (Issuer modules take a Certificate Signing Request (CSR) as input, but certificate manager modules take a TLS ClientHello as input.) + +These manager modules come standard with the `tls` directive: + +#### tailscale + +Get certificates from a locally-running [Tailscale](https://tailscale.com) instance. [HTTPS must be enabled in your Tailscale account](https://tailscale.com/kb/1153/enabling-https/) (or your open source [Headscale server](https://github.com/juanfont/headscale)); and the Caddy process must either be running as root, or you must configure `tailscaled` to give your Caddy user [permission to fetch certificates](https://github.com/caddyserver/caddy/pull/4541#issuecomment-1021568348). + +_**NOTE: This is usually unnecessary!** Caddy automatically uses Tailscale for all `*.ts.net` domains without any extra configuration._ + +```caddy-d +get_certificate tailscale # often unnecessary! +``` + + +#### http + +Get certificates by making an HTTP(S) request. The response must have a 200 status code and the body must contain a PEM chain including the full certificate (with intermediates) as well as the private key. + +```caddy-d +get_certificate http +``` + +- **url** is the fully-qualified URL to which to make the request. It is strongly advised that this be a local endpoint for performance reasons. The URL will be augmented with the following query string parameters: `server_name` = SNI value, `signature_schemes` = comma-separated list of hex IDs of signature algorithms, and `cipher_suites` = comma-separated list of hex IDS of cipher suites. + + + ## Examples Use a custom certificate and key: @@ -236,6 +268,14 @@ tls { } ``` +Get the certificate chain via HTTP, instead of having Caddy manage it: + +```caddy-d +tls { + get_certificate http http://localhost:9007/certs +} +``` + Enable TLS Client Authentication and require clients to present a valid certificate that is verified against all the provided CA's via `trusted_ca_cert_file` ```caddy-d