From 10496e59a4706d471c833d3459359ff273d3b2ee Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Wed, 9 Mar 2022 03:14:25 -0500 Subject: [PATCH] docs: `pki` app --- .../caddyfile/directives/acme_server.md | 2 +- src/docs/markdown/caddyfile/directives/tls.md | 4 +- src/docs/markdown/caddyfile/options.md | 50 +++++++++++++++++++ 3 files changed, 53 insertions(+), 3 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/acme_server.md b/src/docs/markdown/caddyfile/directives/acme_server.md index d8802d3..402f879 100644 --- a/src/docs/markdown/caddyfile/directives/acme_server.md +++ b/src/docs/markdown/caddyfile/directives/acme_server.md @@ -22,5 +22,5 @@ acme_server [] { } ``` -- **ca** specifies the ID of the certificate authority with which to sign certificates. The default is `local`, which is Caddy's default CA, intended for locally-used, self-signed certificates, which is most common in dev environments. For broader use, it is recommended to specify a different CA to avoid confusion. If the CA with the given ID does not already exist, it will be created. +- **ca** specifies the ID of the certificate authority with which to sign certificates. The default is `local`, which is Caddy's default CA, intended for locally-used, self-signed certificates, which is most common in dev environments. For broader use, it is recommended to specify a different CA to avoid confusion. If the CA with the given ID does not already exist, it will be created. See the [PKI app global options](/docs/caddyfile/options#pki-options) to configure alternate CAs. diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 7d190db..e0d59cd 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -173,7 +173,7 @@ Note that ZeroSSL is a default issuer, so configuring it explicitly is usually u #### internal -Obtains certificates from an internal certificate authority. +Obtains certificates from an internal certificate authority. ```caddy ... internal { @@ -181,7 +181,7 @@ Obtains certificates from an internal certificate authority. } ``` -- **ca** is the name of the internal CA to use. Default: `local` +- **ca** is the name of the internal CA to use. Default: `local`. See the [PKI app global options](/docs/caddyfile/options#pki-options) to configure alternate CAs. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index c2a1b42..a7de224 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -105,6 +105,25 @@ Possible options are: strict_sni_host } } + + # PKI Options + pki { + ca [] { + name + root_cn + intermediate_cn + root { + format + cert + key + } + intermediate { + format + cert + key + } + } + } } ``` @@ -333,3 +352,34 @@ If you wish to _not_ have these headers redacted, you may enable the `log_creden - **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._ - **strict_sni_host** require that a request's `Host` header matches the value of the ServerName sent by the client's TLS ClientHello; often a necessary safeguard when using TLS client authentication. + + + +## PKI Options + +The PKI (Public Key Infrastructure) app is the foundation for Caddy's [Local HTTPS](/docs/automatic-https#local-https) and [ACME server](/docs/caddyfile/directives/acme_server) features. The app defines certificate authorities (CAs) which are capable of signing certificates. + +The default CA ID is `local`. If the ID is omitted when configuring the `ca`, then `local` is assumed. + +##### `name` +The user-facing name of the certificate authority. Default: `Caddy Local Authority` + +##### `root_cn` +The name to put in the CommonName field of the root certificate. Default: `{pki.ca.name} - {time.now.year} ECC Root` + +##### `intermediate_cn` +The name to put in the CommonName field of the intermediate certificates. Default: `{pki.ca.name} - ECC Intermediate` + +##### `root` +A key pair (certificate and private key) to use as the root for the CA. If not specified, one will be generated and managed automatically. + +- **format** is the format in which the certificate and private key are provided. Currently, only `pem_file` is supported, which is the default, so this field is optional. +- **cert** is the certificate. This should be the path to a PEM file, when using `pem_file` format. +- **key** is the private key. This should be the path to a PEM file, when using `pem_file` format. + +##### `intermediate` +A key pair (certificate and private key) to use as the intermediate for the CA. If not specified, one will be generated and managed automatically. + +- **format** is the format in which the certificate and private key are provided. Currently, only `pem_file` is supported, which is the default, so this field is optional. +- **cert** is the certificate. This should be the path to a PEM file, when using `pem_file` format. +- **key** is the private key. This should be the path to a PEM file, when using `pem_file` format.