From 08beae1df95bc7433a909259a2ea668976cc2368 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Fri, 11 Mar 2022 00:37:47 -0500 Subject: [PATCH] `caddy trust`, API endpoints --- src/docs/markdown/api.md | 94 ++++++++++++++++++++++--------- src/docs/markdown/command-line.md | 40 +++++++++---- 2 files changed, 96 insertions(+), 38 deletions(-) diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md index a86f33f..b56bdfe 100644 --- a/src/docs/markdown/api.md +++ b/src/docs/markdown/api.md @@ -42,6 +42,12 @@ To get started with the API, try our [API tutorial](/docs/api-tutorial) or, if y - **[Using `@id` in JSON](#using-id-in-json)** Easily traverse into the config structure +- **[GET /pki/ca/<id>](#get-pkicaid)** + Returns information about a particular [PKI app](/docs/json/apps/pki/) CA + +- **[GET /pki/ca/<id>/certificates](#get-pkicaidcertificates)** + Returns the certificate chain of a particular [PKI app](/docs/json/apps/pki/) CA + - **[GET /reverse_proxy/upstreams](#get-reverse-proxyupstreams)** Returns the current status of the configured proxy upstreams @@ -90,33 +96,33 @@ Export entire config and pretty-print it: 
curl "http://localhost:2019/config/" | jq
 {
-	"apps": {
-		"http": {
-			"servers": {
-				"myserver": {
-					"listen": [
-						":443"
-					],
-					"routes": [
-						{
-							"match": [
-								{
-									"host": [
-										"example.com"
-									]
-								}
-							],
-							"handle": [
-								{
-									"handler": "file_server"
-								}
-							]
-						}
-					]
-				}
-			}
-		}
-	}
+  "apps": {
+    "http": {
+      "servers": {
+        "myserver": {
+          "listen": [
+            ":443"
+          ],
+          "routes": [
+            {
+              "match": [
+                {
+                  "host": [
+                    "example.com"
+                  ]
+                }
+              ],
+              "handle": [
+                {
+                  "handler": "file_server"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  }
 }
Export just the listener addresses: @@ -232,6 +238,40 @@ but with an ID, the path becomes which is much easier to remember and write by hand. +## GET /pki/ca/<id> + +Returns information about a particular [PKI app](/docs/json/apps/pki/) CA by its ID. If the requested CA ID is the default (`local`), then the CA will be provisioned if it has not already been. Other CA IDs will return an error if they have not been previously provisioned. + +
curl "http://localhost:2019/pki/ca/local" | jq
+{
+  "id": "local",
+  "name": "Caddy Local Authority",
+  "root_common_name": "Caddy Local Authority - 2022 ECC Root",
+  "intermediate_common_name": "Caddy Local Authority - ECC Intermediate",
+  "root_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... gRw==\n-----END CERTIFICATE-----\n",
+  "intermediate_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... FzQ==\n-----END CERTIFICATE-----\n"
+}
+ + +## GET /pki/ca/<id>/certificates + +Returns the certificate chain of a particular [PKI app](/docs/json/apps/pki/) CA by its ID. If the requested CA ID is the default (`local`), then the CA will be provisioned if it has not already been. Other CA IDs will return an error if they have not been previously provisioned. + +This endpoint is used internally by the [`caddy trust`](/docs/command-line#caddy-trust) command to allow installing the CA's root certificate to your system's trust store. + +
curl "http://localhost:2019/pki/ca/local/certificates"
+-----BEGIN CERTIFICATE-----
+MIIByDCCAW2gAwIBAgIQViS12trTXBS/nyxy7Zg9JDAKBggqhkjOPQQDAjAwMS4w
+...
+By75JkP6C14OfU733oElfDUMa5ctbMY53rWFzQ==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIBpDCCAUmgAwIBAgIQTS5a+3LUKNxC6qN3ZDR8bDAKBggqhkjOPQQDAjAwMS4w
+...
+9M9t0FwCIQCAlUr4ZlFzHE/3K6dARYKusR1ck4A3MtucSSyar6lgRw==
+-----END CERTIFICATE-----
+ + ## GET /reverse_proxy/upstreams Returns the current status of the configured reverse proxy upstreams (backends) as a JSON document. diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 05a5b33..fb720ec 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -321,46 +321,64 @@ Note: the flag `--config` doesn't support `-` to read the config from stdin. Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious. Consider running Caddy [as a service](/docs/running) instead. -Once started, you can use [`caddy stop`](#caddy-stop) or [the /stop API endpoint](/docs/api#post-stop) to exit the background process. +Once started, you can use [`caddy stop`](#caddy-stop) or the [`POST /stop`](/docs/api#post-stop) API endpoint to exit the background process. ### `caddy stop` -
caddy stop [--address <interface>]
+
caddy stop
+	[--address <interface>]
+	[--config <path> [--adapter <name>]]
-Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the [/stop endpoint](/docs/api#post-stop) of the admin API to perform a graceful shutdown. +Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the [`POST /stop`](/docs/api#post-stop) endpoint of the admin API to perform a graceful shutdown. -`--address` can be used if the running instance's admin API is not on the default port; an alternate address can be specified here. +The address of this request can be customized using the `--address` flag, or from the given `--config`, if the running instance's admin API is not using the default listen address. If you want to stop the current configuration but do not want to exit the process, use [`caddy reload`](#caddy-reload) with a blank config, or the [`DELETE /config/`](/docs/api#delete-configpath) endpoint. ### `caddy trust` -
caddy trust
+
caddy trust
+	[--ca <id>]
+	[--address <interface>]
+	[--config <path> [--adapter <name>]]
-Installs the root certificate for Caddy's default internal CA (named "local") into the local trust store(s); intended for development environments only. May prompt for a password if there are not already sufficient privileges. +Installs a root certificate for a CA managed by Caddy's [PKI app](/docs/json/apps/pki/) into local trust stores. -**This command is often unnecessary.** Because Caddy will install its root certificate into local trust stores automatically when first needed, this command is only useful if you need to pre-install the certificates while you have elevated privileges, like during system provisioning in automated environments. +Caddy will attempt to install its root certificates into the local trust stores automatically when they are first generated, but it might fail if Caddy doesn't have the appropriate permissions to write to the trust store. This command is necessary to pre-install the certificates before using them, if the server process runs as an unprivileged user (such as via systemd). You may need to run this command with `sudo` to unix systems. + +By default, this command installs the root certificate for Caddy's default CA (i.e. "local"). You may specify the ID of another CA with the `--ca` flag. + +This command will attempt to connect to Caddy's [admin API](/docs/api) to fetch the root certificate, using the [`GET /pki/ca//certificates`](/docs/api#get-pkicaidcertificates) endpoint. You may explicitly specify the `--address`, or use the `--config` flag to load the admin address from your config, if the running instance's admin API is not using the default listen address. + +You may also use the `caddy` binary with this command to install certificates on other machines in your network, if the admin API is made accessible to other machines -- be careful if doing this, to not expose the admin API to untrusted clients. ### `caddy untrust` 
caddy untrust
+	[--cert <path>]
 	[--ca <id>]
-	[--cert <path>]
+ [--address <interface>] + [--config <path> [--adapter <name>]] -Untrusts a root certificate from the local trust store(s). Intended for development environments only. Specify either the `--ca` or `--cert` flags, but not both. If neither are specified, Caddy's default CA (`local`). +Untrusts a root certificate from the local trust store(s). -`--ca` specifies the ID of the Caddy CA to untrust. The default CA's ID is `local`. +This command uninstalls trust; it does not necessarily delete the root certificate from trust stores entirely. Thus, repeatedly trusting and untrusting new certificates can fill up trust databases. -`--cert` specifies the path to the PEM-encoded certificate file to uninstall. +This command does not delete or modify certificate files from Caddy's configured storage. +This command can be used in one of two ways: +- By specifying a direct path to the root certificate to untrust with the `--cert` flag. +- By fetching the root certificate from the [admin API](/docs/api) using the [`GET /pki/ca//certificates`](/docs/api#get-pkicaidcertificates) endpoint. This is the default behaviour if no flags are given. + +If the admin API is used, then the CA ID defaults to "local". You may specify the ID of another CA with the `--ca` flag. You may explicitly specify the `--address`, or use the `--config` flag to load the admin address from your config, if the running instance's admin API is not using the default listen address. ### `caddy upgrade`