* Update AWS SDK to use PCA features. * Add AWS PCA provider * Add plumbing for config, config validation tests, add test for inheriting existing CA resources created by user * Unparallel the tests so we don't exhaust PCA limits * Merge updates * More aggressive polling; rate limit pass through on sign; Timeout on Sign and CA create * Add AWS PCA docs * Fix Vault doc typo too * Doc typo * Apply suggestions from code review Co-Authored-By: R.B. Boyer <rb@hashicorp.com> Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Doc fixes; tests for erroring if State is modified via API * More review cleanup * Uncomment tests! * Minor suggested clean ups
5.3 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
docs | Connect - Certificate Management | docs-connect-ca-consul | Consul ships with a built-in CA system so that Connect can be easily enabled out of the box. The built-in CA generates and stores the root certificate and private key on Consul servers. It can also be configured with a custom certificate and private key if needed. |
Built-In CA
Consul ships with a built-in CA system so that Connect can be easily enabled out of the box. The built-in CA generates and stores the root certificate and private key on Consul servers. It can also be configured with a custom certificate and private key if needed.
If Connect is enabled and no CA provider is specified, the built-in CA is the default provider used. The provider can be updated and rotated at any point to migrate to a new provider.
-> This page documents the specifics of the built-in CA provider. Please read the certificate management overview page first to understand how Consul manages certificates with configurable CA providers.
Configuration
The built-in CA provider has no required configuration. Enabling Connect alone will configure the built-in CA provider and will automatically generate a root certificate and private key:
connect {
enabled = true
}
The configuration options are listed below. Note, the
first key is the value used in API calls and the second key (after the /
)
is used if you're adding configuring to the agent's configuration file.
-
PrivateKey
/private_key
(string: ""
) - A PEM-encoded private key for signing operations. This must match the private key used for the root certificate if it is manually specified. If this is blank, a private key is automatically generated. -
RootCert
/root_cert
(string: ""
) - A PEM-encoded root certificate to use. If this is blank, a root certificate is automatically generated using the private key specified. If this is specified, the certificate must be a valid SPIFFE SVID signing certificate and the URI in the SAN must match the cluster identifier created at bootstrap with the ".consul" TLD. The cluster identifier can be found using the CA List Roots endpoint.
There are also common CA configuration options that are supported by all CA providers.
Specifying a Custom Private Key and Root Certificate
By default, a root certificate and private key will be automatically generated during the cluster's bootstrap. It is possible to configure the Consul CA provider to use a specific private key and root certificate. This is particularly useful if you have an external PKI system that doesn't currently integrate with Consul directly.
To view the current CA configuration, use the [Get CA Configuration endpoint] (/api/connect/ca.html#get-ca-configuration):
$ curl localhost:8500/v1/connect/ca/configuration
{
"Provider": "consul",
"Config": {
"LeafCertTTL": "72h",
"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 have not been set, so those have been generated (as seen above in the roots list).
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:
$ jq -n --arg key "$(cat root.key)" --arg cert "$(cat root.crt)" '
{
"Provider": "consul",
"Config": {
"LeafCertTTL": "72h",
"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:
$ cat ca_config.json
{
"Provider": "consul",
"Config": {
"LeafCertTTL": "72h",
"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.