From 6161a07af230c876165fd4adf6c952a7785d0a46 Mon Sep 17 00:00:00 2001 From: Daniel Santos Date: Thu, 11 Jun 2020 11:47:34 -0600 Subject: [PATCH] docs: tls: Add client_auth subdirective docs (#55) * doc(tls): Add the tls.client_auth Caddyfile directive doc * doc(client_auth): Additional explanation for the client_auth example * doc(client_auth): Add multiple trusted_ca directive notes - Update the example as well * Fine-tune tls docs formatting Co-authored-by: Matthew Holt --- src/docs/markdown/caddyfile/directives/tls.md | 39 ++++++++++++++++++- src/resources/css/docs.css | 6 +++ 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 48af9e4..a855190 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -24,6 +24,13 @@ tls [internal|] | [ ] { ca_root dns [] on_demand + client_auth { + mode [request|require|verify_if_given|require_and_verify] + trusted_ca_cert + trusted_ca_cert_file + trusted_leaf_cert + trusted_leaf_cert_file + } } ``` @@ -62,6 +69,24 @@ tls [internal|] | [ ] { - **ca_root** specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store. - **dns** enables the [DNS challenge](/docs/automatic-https#dns-challenge) using the specified provider plugin, which must be plugged in from one of the [caddy-dns](https://github.com/caddy-dns) repositories. Each provider plugin may have their own syntax following their name; refer to their docs for details. Maintaining support for each DNS provider is a community effort. [Learn how to enable the DNS challenge for your provider at our wiki.](https://caddy.community/t/how-to-use-dns-provider-modules-in-caddy-2/8148) - **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es). +- **client_auth** enables and configures TLS client authentication: + - **mode** is the mode for authenticating the client. Allowed values are: + + | Mode | Description | + |--------------------|------------------------------------------------------------------------------------------| + | request | Ask clients for a certificate, but allow even if there isn't one; do not verify it | + | require | Require clients to present a certificate, but do not verify it | + | verify_if_given | Ask clients for a certificate; allow even if there isn't one, but verify it if there is | + | require_and_verify | Require clients to present a valid certificate that is verified | + + 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. Client certificates which are not signed by any of these CAs will be rejected. + - **trusted_ca_cert_file** is a base64 DER-encoded CA certificate file against which to validate client certificates. Client certificates which are not signed by any of these CAs will be rejected. + - **trusted_leaf_cert** is a base64 DER-encoded client leaf certificate to accept. Client certificates which are not signed by any of these CAs will be rejected. + - **trusted_leaf_cert_file** is a base64 DER-encoded CA certificate file against which to validate client certificates. Client certificates which are not signed by any of these CAs will be rejected. + + Multiple `trusted_*` directives may be specified as a way to chain multiple CA or leaf certificates. @@ -99,4 +124,16 @@ Enable the DNS challenge for a domain managed on Cloudflare with account credent tls { dns cloudflare {env.CLOUDFLARE_API_TOKEN} } -``` \ No newline at end of file +``` + +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 +tls { + client_auth { + mode require_and_verify + trusted_ca_cert_file ../caddy.ca.cer + trusted_ca_cert_file ../root.ca.cer + } +} +``` diff --git a/src/resources/css/docs.css b/src/resources/css/docs.css index 3519cb3..332af85 100644 --- a/src/resources/css/docs.css +++ b/src/resources/css/docs.css @@ -275,6 +275,12 @@ article li { line-height: 1.5em; } +article li p, +article li ul, +article li ol { + margin-bottom: .5em; +} + h1, h2, h3,