From 5d005df8c6598a294a99d3c395d4ff4e30315abb Mon Sep 17 00:00:00 2001 From: Kyle Havlovitz Date: Wed, 6 Jun 2018 10:50:13 -0700 Subject: [PATCH] docs: add Connect CA overview --- website/source/docs/connect/ca.html.md | 191 ++++++++++++++++++++++++- 1 file changed, 189 insertions(+), 2 deletions(-) diff --git a/website/source/docs/connect/ca.html.md b/website/source/docs/connect/ca.html.md index 424f83486b..b38eda585b 100644 --- a/website/source/docs/connect/ca.html.md +++ b/website/source/docs/connect/ca.html.md @@ -3,9 +3,196 @@ layout: "docs" page_title: "Connect - Certificate Management" sidebar_current: "docs-connect-ca" description: |- - TODO + An overview of the Connect Certificate Authority mechanisms. --- # Connect Certificate Management -TODO +The certificate management in Connect is done centrally through the Consul +servers using the configured CA (Certificate Authority) provider. A CA provider +controls the active root certificate and performs leaf certificate signing for +proxies to use for mutual TLS. Currently, the only supported provider is the +built-in Consul CA, which generates and stores the root certificate and key on +the Consul servers and can be configured with a custom key/certificate if needed. + +The CA provider is initialized either on cluster bootstrapping, or (if Connect is +disabled initially) when a leader server is elected that has Connect enabled. +During the cluster's initial bootstrapping, the CA provider can be configured +through the [Agent configuration](docs/agent/options.html#connect_ca_config) +and afterward can only be updated through the [Update CA Configuration endpoint] +(/api/connect/ca.html#update-ca-configuration). + +### Consul CA (Certificate Authority) Provider + +By default, if no provider is configured when Connect is enabled, the Consul +provider will be used and a private key/root certificate will be generated +and used as the active root certificate for the cluster. To see this in action, +start Consul in [dev mode](/docs/agent/options.html#_dev) and query the +[list CA Roots endpoint](/api/connect/ca.html#list-ca-root-certificates): + +```bash +$ curl localhost:8500/v1/connect/ca/roots +{ + "ActiveRootID": "31:6c:06:fb:49:94:42:d5:e4:55:cc:2e:27:b3:b2:2e:96:67:3e:7e", + "TrustDomain": "36cb52cd-4058-f811-0432-6798a240c5d3.consul", + "Roots": [ + { + "ID": "31:6c:06:fb:49:94:42:d5:e4:55:cc:2e:27:b3:b2:2e:96:67:3e:7e", + "Name": "Consul CA Root Cert", + "SerialNumber": 7, + "SigningKeyID": "31:39:3a:34:35:3a:38:62:3a:33:30:3a:61:31:3a:34:35:3a:38:34:3a:61:65:3a:32:33:3a:35:32:3a:64:62:3a:38:64:3a:31:62:3a:66:66:3a:61:39:3a:30:39:3a:64:62:3a:66:63:3a:32:61:3a:37:32:3a:33:39:3a:61:65:3a:64:61:3a:31:31:3a:35:33:3a:66:34:3a:33:37:3a:35:63:3a:64:65:3a:64:31:3a:36:38:3a:64:38", + "NotBefore": "2018-06-06T17:35:25Z", + "NotAfter": "2028-06-03T17:35:25Z", + "RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA2MDYxNzM1MjVaFw0yODA2MDMxNzM1MjVaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgo09lpx63bHw\ncSXeeoSpHpHgyzX1Q8ewJ3RUg6Ie8Howbs/QBz1y/kGxsF35HXij3YrqhgQyPPx4\nbQ8FH2YR4aOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8xOTo0NTo4YjozMDphMTo0NTo4NDphZToyMzo1MjpkYjo4ZDox\nYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpkYToxMTo1MzpmNDozNzo1Yzpk\nZTpkMTo2ODpkODBqBgNVHSMEYzBhgF8xOTo0NTo4YjozMDphMTo0NTo4NDphZToy\nMzo1MjpkYjo4ZDoxYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpkYToxMTo1\nMzpmNDozNzo1YzpkZTpkMTo2ODpkODA/BgNVHREEODA2hjRzcGlmZmU6Ly8zNmNi\nNTJjZC00MDU4LWY4MTEtMDQzMi02Nzk4YTI0MGM1ZDMuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgiszNmNiNTJjZC00MDU4LWY4MTEtMDQzMi02Nzk4YTI0MGM1ZDMu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIHl6UDdouw8Fzn/oDHputAxt3UFbVg/U\nvC6jWPuqqMwmAiEAkvMadtwjtNU7m/AQRJrj1LeG3eXw7dWO8SlI2fEs0yY=\n-----END CERTIFICATE-----\n", + "IntermediateCerts": null, + "Active": true, + "CreateIndex": 8, + "ModifyIndex": 8 + } + ] +} +``` + +#### Specifying a Private Key and Root Certificate + +The above root certificate has been automatically generated during the cluster's +bootstrap, but it is possible to configure the Consul CA provider to use a specific +private key and root certificate. + +To view the current CA configuration, use the [Get CA Configuration endpoint] +(/api/connect/ca.html#get-ca-configuration): + +```bash +$ curl localhost:8500/v1/connect/ca/configuration +{ + "Provider": "consul", + "Config": { + "PrivateKey": null, + "RootCert": null, + "RotationPeriod": "2160h" + }, + "CreateIndex": 5, + "ModifyIndex": 5 +} +``` + +This is the default Connect CA configuration if nothing is explicitly set when +Connect is enabled - the PrivateKey and RootCert fields are both empty, and have been +generated (as seen above). + +There are two ways to have the Consul CA use a custom private key and root certificate: +either through the `ca_config` section of the [Agent configuration] +(docs/agent/options.html#connect_ca_config) (which can only be used during the cluster's +initial bootstrap) or through the [Update CA Configuration endpoint] +(/api/connect/ca.html#update-ca-configuration). + +Currently consul requires that root certificates are valid [SPIFFE SVID Signing certificates] +(https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded +in the SAN is the cluster identifier created at bootstrap with the ".consul" TLD. In this +example, we will set the URI SAN to `spiffe://36cb52cd-4058-f811-0432-6798a240c5d3.consul`. + +In order to use the Update CA Configuration HTTP endpoint, the private key and certificate +must be passed via JSON: + +```bash +$ jq -n --arg key "$(cat root.key)" --arg cert "$(cat root.crt)" ' +{ + "Provider": "consul", + "Config": { + "PrivateKey": $key, + "RootCert": $cert, + "RotationPeriod": "2160h" + } +}' > ca_config.json +``` + +The resulting `ca_config.json` file can then be used to update the active root certificate: + +```bash +$ cat ca_config.json +{ + "Provider": "consul", + "Config": { + "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEArqiy1c3pbT3cSkjdEM1APALUareU...", + "RootCert": "-----BEGIN CERTIFICATE-----\nMIIDijCCAnKgAwIBAgIJAOFZ66em1qC7MA0GCSqGSIb3...", + "RotationPeriod": "2160h" + } +} + +$ curl --request PUT --data @ca_config.json localhost:8500/v1/connect/ca/configuration + +... + +[INFO] connect: CA rotated to new root under provider "consul" +``` + +The cluster is now using the new private key and root certificate. Updating the CA config +this way also triggered a certificate rotation, which will be covered in the next section. + +#### Root Certificate Rotation + +Whenever the CA's configuration is updated in a way that causes the root key to +change, a special rotation process will be triggered in order to smoothly transition to +the new certificate. + +First, an intermediate CA certificate is requested from the new root, which is then +cross-signed by the old root. This cross-signed certificate is then distributed +alongside any newly-generated leaf certificates used by the proxies once the new root +becomes active, and provides a chain of trust back to the old root certificate in the +event that a certificate signed by the new root is presented to a proxy that has not yet +updated its bundle of trusted root CA certificates to include the new root. + +After the cross-signed certificate has been successfully generated and the new root +certificate or CA provider has been set up, the new root becomes the active one +and is immediately used for signing any new incoming certificate requests. + +If we check the [list CA roots endpoint](/api/connect/ca.html#list-ca-root-certificates) +after the config update in the previous section, we can see both the old and new root +certificates are present, and the currently active root has an intermediate certificate +which has been generated and cross-signed automatically by the old root during the +rotation process: + +```bash +$ curl localhost:8500/v1/connect/ca/roots +{ + "ActiveRootID": "d2:2c:41:94:1e:50:04:ea:86:fc:08:d6:b0:45:a4:af:8a:eb:76:a0", + "TrustDomain": "36cb52cd-4058-f811-0432-6798a240c5d3.consul", + "Roots": [ + { + "ID": "31:6c:06:fb:49:94:42:d5:e4:55:cc:2e:27:b3:b2:2e:96:67:3e:7e", + "Name": "Consul CA Root Cert", + "SerialNumber": 7, + "SigningKeyID": "31:39:3a:34:35:3a:38:62:3a:33:30:3a:61:31:3a:34:35:3a:38:34:3a:61:65:3a:32:33:3a:35:32:3a:64:62:3a:38:64:3a:31:62:3a:66:66:3a:61:39:3a:30:39:3a:64:62:3a:66:63:3a:32:61:3a:37:32:3a:33:39:3a:61:65:3a:64:61:3a:31:31:3a:35:33:3a:66:34:3a:33:37:3a:35:63:3a:64:65:3a:64:31:3a:36:38:3a:64:38", + "NotBefore": "2018-06-06T17:35:25Z", + "NotAfter": "2028-06-03T17:35:25Z", + "RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA2MDYxNzM1MjVaFw0yODA2MDMxNzM1MjVaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgo09lpx63bHw\ncSXeeoSpHpHgyzX1Q8ewJ3RUg6Ie8Howbs/QBz1y/kGxsF35HXij3YrqhgQyPPx4\nbQ8FH2YR4aOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8xOTo0NTo4YjozMDphMTo0NTo4NDphZToyMzo1MjpkYjo4ZDox\nYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpkYToxMTo1MzpmNDozNzo1Yzpk\nZTpkMTo2ODpkODBqBgNVHSMEYzBhgF8xOTo0NTo4YjozMDphMTo0NTo4NDphZToy\nMzo1MjpkYjo4ZDoxYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpkYToxMTo1\nMzpmNDozNzo1YzpkZTpkMTo2ODpkODA/BgNVHREEODA2hjRzcGlmZmU6Ly8zNmNi\nNTJjZC00MDU4LWY4MTEtMDQzMi02Nzk4YTI0MGM1ZDMuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgiszNmNiNTJjZC00MDU4LWY4MTEtMDQzMi02Nzk4YTI0MGM1ZDMu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIHl6UDdouw8Fzn/oDHputAxt3UFbVg/U\nvC6jWPuqqMwmAiEAkvMadtwjtNU7m/AQRJrj1LeG3eXw7dWO8SlI2fEs0yY=\n-----END CERTIFICATE-----\n", + "IntermediateCerts": null, + "Active": false, + "CreateIndex": 8, + "ModifyIndex": 24 + }, + { + "ID": "d2:2c:41:94:1e:50:04:ea:86:fc:08:d6:b0:45:a4:af:8a:eb:76:a0", + "Name": "Consul CA Root Cert", + "SerialNumber": 16238269036752183483, + "SigningKeyID": "", + "NotBefore": "2018-06-06T17:37:03Z", + "NotAfter": "2028-06-03T17:37:03Z", + "RootCert": "-----BEGIN CERTIFICATE-----\nMIIDijCCAnKgAwIBAgIJAOFZ66em1qC7MA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNp\nc2NvMRIwEAYDVQQKDAlIYXNoaUNvcnAxEjAQBgNVBAMMCWxvY2FsaG9zdDAeFw0x\nODA2MDYxNzM3MDNaFw0yODA2MDMxNzM3MDNaMGIxCzAJBgNVBAYTAlVTMRMwEQYD\nVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMRIwEAYDVQQK\nDAlIYXNoaUNvcnAxEjAQBgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEB\nBQADggEPADCCAQoCggEBAK6ostXN6W093EpI3RDNQDwC1Gq3lPNoodL5XRaVVIBU\n3X5iC+Ttk02p67cHUguh4ZrWr3o3Dzxm+gKK0lfZLW0nNYNPAIGZWQD9zVSx1Lqt\n8X0pd+fhMV5coQrh3YIG/vy17IBTSBuRUX0mXOKjOeJJlrw1HQZ8pfm7WX6LFul2\nXszvgn5K1XR+9nhPy6K2bv99qsY0sm7AqCS2BjYBW8QmNngJOdLPdhyFh7invyXe\nPqgujc/KoA3P6e3/G7bJZ9+qoQMK8uwD7PxtA2hdQ9t0JGPsyWgzhwfBxWdBWRzV\nRvVi6Yu2tvw3QrjdeKQ5Ouw9FUb46VnTU7jTO974HjkCAwEAAaNDMEEwPwYDVR0R\nBDgwNoY0c3BpZmZlOi8vMzZjYjUyY2QtNDA1OC1mODExLTA0MzItNjc5OGEyNDBj\nNWQzLmNvbnN1bDANBgkqhkiG9w0BAQsFAAOCAQEATHgCro9VXj7JbH/tlB6f/KWf\n7r98+rlUE684ZRW9XcA9uUA6y265VPnemsC/EykPsririoh8My1jVPuEfgMksR39\n9eMDJKfutvSpLD1uQqZE8hu/hcYyrmQTFKjW71CfGIl/FKiAg7wXEw2ljLN9bxNv\nGG118wrJyMZrRvFjC2QKY025QQSJ6joNLFMpftsZrJlELtRV+nx3gMabpiDRXhIw\nJM6ti26P1PyVgGRPCOG10v+OuUtwe0IZoOqWpPJN8jzSuqZWf99uolkG0xuqLNz6\nd8qvTp1YF9tTmysgvdeGALez/02HTF035RVTsQfH9tM/+4yG1UnmjLpz3p4Fow==\n-----END CERTIFICATE-----", + "IntermediateCerts": [ + "-----BEGIN CERTIFICATE-----\nMIIDTzCCAvWgAwIBAgIBFzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA2MDYxNzM3MDNaFw0yODA2MDMxNzM3MDNaMGIxCzAJBgNVBAYT\nAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2Nv\nMRIwEAYDVQQKDAlIYXNoaUNvcnAxEjAQBgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJ\nKoZIhvcNAQEBBQADggEPADCCAQoCggEBAK6ostXN6W093EpI3RDNQDwC1Gq3lPNo\nodL5XRaVVIBU3X5iC+Ttk02p67cHUguh4ZrWr3o3Dzxm+gKK0lfZLW0nNYNPAIGZ\nWQD9zVSx1Lqt8X0pd+fhMV5coQrh3YIG/vy17IBTSBuRUX0mXOKjOeJJlrw1HQZ8\npfm7WX6LFul2Xszvgn5K1XR+9nhPy6K2bv99qsY0sm7AqCS2BjYBW8QmNngJOdLP\ndhyFh7invyXePqgujc/KoA3P6e3/G7bJZ9+qoQMK8uwD7PxtA2hdQ9t0JGPsyWgz\nhwfBxWdBWRzVRvVi6Yu2tvw3QrjdeKQ5Ouw9FUb46VnTU7jTO974HjkCAwEAAaOC\nARswggEXMGgGA1UdDgRhBF8xOTo0NTo4YjozMDphMTo0NTo4NDphZToyMzo1Mjpk\nYjo4ZDoxYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpkYToxMTo1MzpmNDoz\nNzo1YzpkZTpkMTo2ODpkODBqBgNVHSMEYzBhgF8xOTo0NTo4YjozMDphMTo0NTo4\nNDphZToyMzo1MjpkYjo4ZDoxYjpmZjphOTowOTpkYjpmYzoyYTo3MjozOTphZTpk\nYToxMTo1MzpmNDozNzo1YzpkZTpkMTo2ODpkODA/BgNVHREEODA2hjRzcGlmZmU6\nLy8zNmNiNTJjZC00MDU4LWY4MTEtMDQzMi02Nzk4YTI0MGM1ZDMuY29uc3VsMAoG\nCCqGSM49BAMCA0gAMEUCIBp46tRDot7GFyDXu7egq7lXBvn+UUHD5MmlFvdWmtnm\nAiEAwKBzEMcLd5kCBgFHNGyksRAMh/AGdEW859aL6z0u4gM=\n-----END CERTIFICATE-----\n" + ], + "Active": true, + "CreateIndex": 24, + "ModifyIndex": 24 + } + ] +} +``` + +The old root certificate will be automatically removed once enough time has elapsed +for any leaf certificates signed by it to expire. + +### External CA (Certificate Authority) Providers (Vault) + +TODO \ No newline at end of file