luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/connect/ca.mdx

208 lines
7.9 KiB
Plaintext
Raw Normal View History

initial
2020-04-06 20:27:35 +00:00
---
layout: api
page_title: Certificate Authority - Connect - HTTP API
description: |-
The /connect/ca endpoints provide tools for interacting with Connect's
Certificate Authority mechanism via Consul's HTTP API.
---
# Certificate Authority (CA) - Connect HTTP API
The `/connect/ca` endpoints provide tools for interacting with Connect's
Certificate Authority mechanism.
## List CA Root Certificates
This endpoint returns the current list of trusted CA root certificates in
the cluster.
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `GET` | `/connect/ca/roots` | `application/json` |
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
initial
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `none` |
Add capability for the v1/connect/ca/roots endpoint to return a PEM encoded certificate chain (#8774) Co-authored-by: R.B. Boyer <rb@hashicorp.com>
2020-10-09 14:43:33 +00:00
### Parameters
- `pem` `(boolean: false)` - Specifies that the return body should be a PEM encoded
certificate chain suitable for use by applications needing to trust Connect CA
signed certificates. The Content-Type will be set to `application/pem-certificate-chain`
to indicate the format of the response.
initial
2020-04-06 20:27:35 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
initial
2020-04-06 20:27:35 +00:00
$ curl \
http://127.0.0.1:8500/v1/connect/ca/roots
```
### Sample Response
```json
{
"ActiveRootID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
"TrustDomain": "7f42f496-fbc7-8692-05ed-334aa5340c1e.consul",
"Roots": [
{
"ID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
"Name": "Consul CA Root Cert",
"SerialNumber": 7,
"SigningKeyID": "2d:09:5d:84:b9:89:4b:dd:e3:88:bb:9c:e2:b2:69:81:1f:4b:a6:fd:4d:df:ee:74:63:f3:74:55:ca:b0:b5:65",
"ExternalTrustDomain": "a1499528-fbf6-df7b-05e5-ae81e1873fc4",
"NotBefore": "2018-05-25T21:39:23Z",
"NotAfter": "2028-05-22T21:39:23Z",
"RootCert": "-----BEGIN CERTIFICATE-----\nMIICmDCCAj6gAwIBAgIBBzAKBggqhkjOPQQDAjAWMRQwEgYDVQQDEwtDb25zdWwg\nQ0EgNzAeFw0xODA1MjUyMTM5MjNaFw0yODA1MjIyMTM5MjNaMBYxFDASBgNVBAMT\nC0NvbnN1bCBDQSA3MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEq4S32Pu0/VL4\nG75gvdyQuAhqMZFsfBRwD3pgvblgZMeJc9KDosxnPR+W34NXtMD/860NNVJIILln\n9lLhIjWPQqOCAXswggF3MA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/\nMGgGA1UdDgRhBF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDplMzo4ODpiYjo5Yzpl\nMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2MzpmMzo3NDo1NTpj\nYTpiMDpiNTo2NTBqBgNVHSMEYzBhgF8yZDowOTo1ZDo4NDpiOTo4OTo0YjpkZDpl\nMzo4ODpiYjo5YzplMjpiMjo2OTo4MToxZjo0YjphNjpmZDo0ZDpkZjplZTo3NDo2\nMzpmMzo3NDo1NTpjYTpiMDpiNTo2NTA/BgNVHREEODA2hjRzcGlmZmU6Ly83ZjQy\nZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUuY29uc3VsMD0GA1UdHgEB\n/wQzMDGgLzAtgis3ZjQyZjQ5Ni1mYmM3LTg2OTItMDVlZC0zMzRhYTUzNDBjMWUu\nY29uc3VsMAoGCCqGSM49BAMCA0gAMEUCIBBBDOWXWApx4S6bHJ49AW87Nw8uQ/gJ\nJ6lvm3HzEQw2AiEA4PVqWt+z8fsQht0cACM42kghL97SgDSf8rgCqfLYMng=\n-----END CERTIFICATE-----\n",
"IntermediateCerts": null,
"Active": true,
"PrivateKeyType": "ec",
"PrivateKeyBits": 256,
"CreateIndex": 8,
"ModifyIndex": 8
}
]
}
```
Add capability for the v1/connect/ca/roots endpoint to return a PEM encoded certificate chain (#8774) Co-authored-by: R.B. Boyer <rb@hashicorp.com>
2020-10-09 14:43:33 +00:00
### Sample PEM Encoded Response
```
-----BEGIN CERTIFICATE-----
MIICDzCCAbWgAwIBAgIBCDAKBggqhkjOPQQDAjAxMS8wLQYDVQQDEyZwcmktMWNq
OHphbW0uY29uc3VsLmNhLjA3OTMzYTEzLmNvbnN1bDAeFw0yMDEwMDgxOTQ4MzZa
Fw0zMDEwMDgxOTQ4MzZaMDExLzAtBgNVBAMTJnByaS0xY2o4emFtbS5jb25zdWwu
Y2EuMDc5MzNhMTMuY29uc3VsMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDCkT
IIxSDhA3XCKIuDcj4s9IVjf0NQT6QHPAzFBb964/4fTtX/J8x2n6A1lOXowFIWtx
GvAD/IJF74zn5ZA/wqOBvTCBujAOBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUw
AwEB/zApBgNVHQ4EIgQguPlAkrIkOnLr9+8DZ4afZWrYZUd2LB6nMJP72jDVxmcw
KwYDVR0jBCQwIoAguPlAkrIkOnLr9+8DZ4afZWrYZUd2LB6nMJP72jDVxmcwPwYD
VR0RBDgwNoY0c3BpZmZlOi8vMDc5MzNhMTMtYTYyYi1iZTkwLTQ0ZjEtZGVkOWE2
NjczNzZlLmNvbnN1bDAKBggqhkjOPQQDAgNIADBFAiEA0ExkvLESG1I1TMFVronr
2fjoORukgzBgRMbWAEC2DJ0CIACsxeFS6tprHiRv4cEa2Md75h1iIisb2V2U7dvY
Z7Rr
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICEzCCAbigAwIBAgIBCTAKBggqhkjOPQQDAjAxMS8wLQYDVQQDEyZwcmktMWNq
OHphbW0uY29uc3VsLmNhLjA3OTMzYTEzLmNvbnN1bDAeFw0yMDEwMDgxOTQ3Mzda
Fw0yMTEwMDgxOTQ3MzdaMDExLzAtBgNVBAMTJnNlYy0xbmIxMHZ0by5jb25zdWwu
Y2EuMDc5MzNhMTMuY29uc3VsMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9zWs
UxEYvLZUySoflz6e+HqLcaXM8heNRRkAiLiGkmn6nan6olnnrVBLyHAfHaHWJQ9W
wI8HwSZf0g4Ms16LWKOBwDCBvTAOBgNVHQ8BAf8EBAMCAYYwEgYDVR0TAQH/BAgw
BgEB/wIBADApBgNVHQ4EIgQg+csK9Sg6odIfLLk3aiRY2OB4O0DiOa1XRTVdOVDE
t6QwKwYDVR0jBCQwIoAguPlAkrIkOnLr9+8DZ4afZWrYZUd2LB6nMJP72jDVxmcw
PwYDVR0RBDgwNoY0c3BpZmZlOi8vMDc5MzNhMTMtYTYyYi1iZTkwLTQ0ZjEtZGVk
OWE2NjczNzZlLmNvbnN1bDAKBggqhkjOPQQDAgNJADBGAiEAqJ60KJepAP4Xe4Ak
5UYB1huu/B8Lyz5yEYUpUplgdD4CIQCrrkoXoD4SGJ4HaIjy6a5eNf3YkhLpmbXO
6DL6FXVa1Q==
-----END CERTIFICATE-----
```
initial
2020-04-06 20:27:35 +00:00
## Get CA Configuration
This endpoint returns the current CA configuration.
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `GET` | `/connect/ca/configuration` | `application/json` |
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
initial
2020-04-06 20:27:35 +00:00
maintenance complete, pending markdown-page component addition
2020-12-08 23:24:36 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ----------------------------- |
Require operator:write to get Connect CA config (#9240) A vulnerability was identified in Consul and Consul Enterprise (“Consul”) such that operators with `operator:read` ACL permissions are able to read the Consul Connect CA configuration when explicitly configured with the `/v1/connect/ca/configuration` endpoint, including the private key. This allows the user to effectively privilege escalate by enabling the ability to mint certificates for any Consul Connect services. This would potentially allow them to masquerade (receive/send traffic) as any service in the mesh. -- This PR increases the permissions required to read the Connect CA's private key when it was configured via the `/connect/ca/configuration` endpoint. They are now `operator:write`.
2020-11-19 17:14:48 +00:00
| `YES` | `all` | `none` | `operator:write` <sup>1</sup> |
maintenance complete, pending markdown-page component addition
2020-12-08 23:24:36 +00:00
<sup>1</sup> ACL required was <code>operator:read</code> prior to versions 1.8.6,
1.7.10, and 1.6.10.
initial
2020-04-06 20:27:35 +00:00
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
initial
2020-04-06 20:27:35 +00:00
$ curl \
http://127.0.0.1:8500/v1/connect/ca/configuration
```
### Sample Response
```json
{
"Provider": "consul",
"Config": {
"LeafCertTTL": "72h",
"RotationPeriod": "2160h",
"IntermediateCertTTL": "8760h"
},
"CreateIndex": 5,
"ModifyIndex": 5
}
```
## Update CA Configuration
This endpoint updates the configuration for the CA. If this results in a
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
new root certificate being used, the [Root Rotation](/docs/connect/ca#root-certificate-rotation) process will be triggered.
initial
2020-04-06 20:27:35 +00:00
| Method | Path | Produces |
| ------ | --------------------------- | ------------------ |
| `PUT` | `/connect/ca/configuration` | `application/json` |
The table below shows this endpoint's support for
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
[blocking queries](/api/features/blocking),
[consistency modes](/api/features/consistency),
[agent caching](/api/features/caching), and
remove internal /index.html
2020-04-09 23:20:00 +00:00
[required ACLs](/api#authentication).
initial
2020-04-06 20:27:35 +00:00
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ---------------- |
| `NO` | `none` | `none` | `operator:write` |
### Parameters
- `Provider` `(string: <required>)` - Specifies the CA provider type to use.
- `Config` `(map[string]string: <required>)` - The raw configuration to use
for the chosen provider. For more information on configuring the Connect CA
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
providers, see [Provider Config](/docs/connect/ca).
initial
2020-04-06 20:27:35 +00:00
- `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change
connect/ca: Allow ForceWithoutCrossSigning for all providers This allows setting ForceWithoutCrossSigning when reconfiguring the CA for any provider, in order to forcibly move to a new root in cases where the old provider isn't reachable or able to cross-sign for whatever reason.
2021-01-29 21:38:11 +00:00
should be forced to complete even if the current CA doesn't support cross
initial
2020-04-06 20:27:35 +00:00
signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without
replace internal .html link extensions
2020-04-09 23:46:54 +00:00
Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
initial
2020-04-06 20:27:35 +00:00
for more detail.
### Sample Payload
```json
{
"Provider": "consul",
"Config": {
"LeafCertTTL": "72h",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----...",
"RootCert": "-----BEGIN CERTIFICATE-----...",
"RotationPeriod": "2160h",
"IntermediateCertTTL": "8760h"
},
"ForceWithoutCrossSigning": false
}
```
### Sample Request
update dependencies
2020-05-19 18:32:38 +00:00
```shell-session
initial
2020-04-06 20:27:35 +00:00
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/connect/ca/configuration
```