From 21742020f011c90bed4dd507dfb0b5600f328413 Mon Sep 17 00:00:00 2001
From: Alexander Scheel <alex.scheel@hashicorp.com>
Date: Tue, 12 Sep 2023 11:35:37 -0400
Subject: [PATCH] Add API docs on Transit X.509 certificates (#22998)

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
---
 website/content/api-docs/secret/transit.mdx | 81 +++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx
index 2cf9b167e41f..d187ede55f2a 100644
--- a/website/content/api-docs/secret/transit.mdx
+++ b/website/content/api-docs/secret/transit.mdx
@@ -507,6 +507,85 @@ $ curl \
     http://127.0.0.1:8200/v1/transit/keys/my-key/rotate
 ```
 
+## Sign CSR
+
+This endpoint signs a CSR with the `:name` key, allowing the key material
+never to leave Transit. If no template CSR is specified, an empty CSR is
+signed, otherwise, a copy of the specified CSR with key material replaced
+with this key material is signed.
+
+| Method | Path                      |
+| :----- | :------------------------ |
+| `POST` | `/transit/keys/:name/csr` |
+
+### Parameters
+
+ - `name` `(string: <required>)` - Specifies the name of the key to
+   sign the CSR with. This is specified as part of the URL.
+
+ - `version` `(string: "")` - Specifies the version of the CSR key to
+   use for signing.  If the version is set to `latest` or is not set,
+   the current key will be returned.
+
+ - `csr` `(string: "")` - Optional PEM-encoded CSR template to use
+   as a basis for the new CSR signed by this key. If not set, an empty
+   CSR is used.
+
+### Sample request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    http://127.0.0.1:8200/v1/transit/keys/my-key/csr
+```
+
+### Sample response
+
+```json
+{
+  "data": {
+    "name": "my-key",
+    "version": 1,
+    "csr": "-----BEGIN ..."
+  }
+}
+```
+
+## Set Certificate Chain
+
+This endpoint sets the certificate chain associated with the `:name` key,
+allowing the key material never to leave Transit and for certificates to
+be tracked in a single mount. Note that this allows updating and rotating
+the chain as it will overwrite any previously set certificate chain.
+
+| Method | Path                                  |
+| :----- | :------------------------------------ |
+| `POST` | `/transit/keys/:name/set-certificate` |
+
+### Parameters
+
+ - `name` `(string: <required>)` - Specifies the name of the key to
+   import the certificate chain against. This is specified as part of the
+   URL.
+
+ - `version` `(string: "")` - Specifies the version of the key to import the
+   chain against.  If the version is set to `latest` or is not set, the current
+   key will be returned.
+
+ - `certificate_chain` `(string: "")` - Optional PEM-encoded CSR template to use
+   as a basis for the new CSR signed by this key. If not set, an empty
+   CSR is used.
+
+### Sample request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    http://127.0.0.1:8200/v1/transit/keys/my-key/set-certificate
+```
+
 ## Securely export key
 
 This endpoint returns a wrapped copy of the `source` key, protected by the
@@ -582,6 +661,8 @@ be valid.
   - `hmac-key`
   - `public-key`, to return the corresponding public keys of private key
     asymmetric keys (EC with NIST P-curves or Ed25519 and RSA).
+  - `certificate-chain`, to return the imported certificate chain (via
+    `set-certificate`) corresponding to this key and version.
 
 - `name` `(string: <required>)` – Specifies the name of the key to read
   information about. This is specified as part of the URL.