github.com/outbrain/consul@v1.4.5/website/source/api/connect/ca.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Certificate Authority - Connect - HTTP API
     4  sidebar_current: api-connect-ca
     5  description: |-
     6    The /connect/ca endpoints provide tools for interacting with Connect's
     7    Certificate Authority mechanism via Consul's HTTP API.
     8  ---
     9  
    10  # Certificate Authority (CA) - Connect HTTP API
    11  
    12  The `/connect/ca` endpoints provide tools for interacting with Connect's
    13  Certificate Authority mechanism.
    14  
    15  ## List CA Root Certificates
    16  
    17  This endpoint returns the current list of trusted CA root certificates in
    18  the cluster.
    19  
    20  | Method | Path                         | Produces                   |
    21  | ------ | ---------------------------- | -------------------------- |
    22  | `GET`  | `/connect/ca/roots`          | `application/json`         |
    23  
    24  The table below shows this endpoint's support for
    25  [blocking queries](/api/index.html#blocking-queries),
    26  [consistency modes](/api/index.html#consistency-modes),
    27  [agent caching](/api/index.html#agent-caching), and
    28  [required ACLs](/api/index.html#acls).
    29  
    30  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required     |
    31  | ---------------- | ----------------- | ------------- | ---------------- |
    32  | `YES`            | `all`             | `none`        | `operator:read`  |
    33  
    34  ### Sample Request
    35  
    36  ```text
    37  $ curl \
    38      http://127.0.0.1:8500/v1/connect/ca/roots
    39  ```
    40  
    41  ### Sample Response
    42  
    43  ```json
    44  {
    45      "ActiveRootID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
    46      "TrustDomain": "7f42f496-fbc7-8692-05ed-334aa5340c1e.consul",
    47      "Roots": [
    48          {
    49              "ID": "c7:bd:55:4b:64:80:14:51:10:a4:b9:b9:d7:e0:75:3f:86:ba:bb:24",
    50              "Name": "Consul CA Root Cert",
    51              "SerialNumber": 7,
    52              "SigningKeyID": "32:64:3a:30:39:3a:35:64:3a:38:34:3a:62:39:3a:38:39:3a:34:62:3a:64:64:3a:65:33:3a:38:38:3a:62:62:3a:39:63:3a:65:32:3a:62:32:3a:36:39:3a:38:31:3a:31:66:3a:34:62:3a:61:36:3a:66:64:3a:34:64:3a:64:66:3a:65:65:3a:37:34:3a:36:33:3a:66:33:3a:37:34:3a:35:35:3a:63:61:3a:62:30:3a:62:35:3a:36:35",
    53              "NotBefore": "2018-05-25T21:39:23Z",
    54              "NotAfter": "2028-05-22T21:39:23Z",
    55              "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",
    56              "IntermediateCerts": null,
    57              "Active": true,
    58              "CreateIndex": 8,
    59              "ModifyIndex": 8
    60          }
    61      ]
    62  }
    63  ```
    64  
    65  ## Get CA Configuration
    66  
    67  This endpoint returns the current CA configuration.
    68  
    69  | Method | Path                         | Produces                   |
    70  | ------ | ---------------------------- | -------------------------- |
    71  | `GET`  | `/connect/ca/configuration`  | `application/json`         |
    72  
    73  The table below shows this endpoint's support for
    74  [blocking queries](/api/index.html#blocking-queries),
    75  [consistency modes](/api/index.html#consistency-modes),
    76  [agent caching](/api/index.html#agent-caching), and
    77  [required ACLs](/api/index.html#acls).
    78  
    79  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
    80  | ---------------- | ----------------- | ------------- | --------------- |
    81  | `YES`            | `all`             | `none`        | `operator:read` |
    82  
    83  ### Sample Request
    84  
    85  ```text
    86  $ curl \
    87      http://127.0.0.1:8500/v1/connect/ca/configuration
    88  ```
    89  
    90  ### Sample Response
    91  
    92  ```json
    93  {
    94      "Provider": "consul",
    95      "Config": {
    96          "LeafCertTTL": "72h",
    97          "RotationPeriod": "2160h"
    98      },
    99      "CreateIndex": 5,
   100      "ModifyIndex": 5
   101  }
   102  ```
   103  
   104  ## Update CA Configuration
   105  
   106  This endpoint updates the configuration for the CA. If this results in a
   107  new root certificate being used, the [Root Rotation]
   108  (/docs/connect/ca.html#root-certificate-rotation) process will be triggered.
   109  
   110  | Method | Path                         | Produces                   |
   111  | ------ | ---------------------------- | -------------------------- |
   112  | `PUT`  | `/connect/ca/configuration`  | `application/json`         |
   113  
   114  The table below shows this endpoint's support for
   115  [blocking queries](/api/index.html#blocking-queries),
   116  [consistency modes](/api/index.html#consistency-modes),
   117  [agent caching](/api/index.html#agent-caching), and
   118  [required ACLs](/api/index.html#acls).
   119  
   120  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
   121  | ---------------- | ----------------- | ------------- | --------------- |
   122  | `NO`             | `none`            | `none`        | `operator:write`|
   123  
   124  ### Parameters
   125  
   126  - `Provider` `(string: <required>)` - Specifies the CA provider type to use.
   127  
   128  - `Config` `(map[string]string: <required>)` - The raw configuration to use
   129  for the chosen provider. For more information on configuring the Connect CA
   130  providers, see [Provider Config](/docs/connect/ca.html).
   131  
   132  ### Sample Payload
   133  
   134  ```json
   135  {
   136      "Provider": "consul",
   137      "Config": {
   138          "LeafCertTTL": "72h",
   139          "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----...",
   140          "RootCert": "-----BEGIN CERTIFICATE-----...",
   141          "RotationPeriod": "2160h"
   142      }
   143  }
   144  ```
   145  
   146  ### Sample Request
   147  
   148  ```text
   149  $ curl \
   150      --request PUT \
   151      --data @payload.json \
   152      http://127.0.0.1:8500/v1/connect/ca/configuration
   153  ```