backport of commit 74f1c4a (#27375)

Co-authored-by: Kit Haines <[email protected]>

website/content/api-docs/secret/pki.mdx

@@ -672,10 +672,11 @@ It is suggested to limit access to the path-overridden issue endpoint (on
   signed certificate. This field is validated against `allowed_user_ids` on
   the role.
 
-- `metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A blank
-  or base 64 encoded value to be associated with the certificate's serial
-  number. The role's `no_store_metadata` must be set to false, otherwise an
-  error is returned when specified.
+- `cert_metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A base 64
+  encoded value or an empty string to associate with the certificate's serial
+  number. The role's no_store_metadata must be set to false, otherwise an
+  error is returned when specified. To retrieve metadata see:
+  [Read Certificate Metadata](#read-certificate-metadata)
 
 #### Sample payload
 
@@ -903,10 +904,11 @@ It is suggested to limit access to the path-overridden sign endpoint (on
   signed certificate. This field is validated against `allowed_user_ids` on
   the role.
 
-- `metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A blank
-  or base 64 encoded value to be associated with the certificate's serial
-  number. The role's `no_store_metadata` must be set to false, otherwise an
-  error is returned when specified.
+- `cert_metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A base 64
+  encoded value or an empty string to associate with the certificate's serial
+  number. The role's no_store_metadata must be set to false, otherwise an
+  error is returned when specified. To retrieve metadata see:
+  [Read Certificate Metadata](#read-certificate-metadata)
 
 #### Sample payload
 
@@ -1474,10 +1476,12 @@ have access.**
   User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the
   signed certificate. No validation on names is performed using this endpoint.
 
-- `metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A blank
-  or base 64 encoded value to be associated with the certificate's serial
-  number. The role's `no_store_metadata` must be set to false, otherwise an
-  error is returned when specified.
+- `cert_metadata` `(string: "")` - <EnterpriseAlert inline="true" /> A base 64
+  encoded value or an empty string to associate with the certificate's serial
+  number. A role must be passed to sign-verbatim, and that role's
+  no_store_metadata must be set to false, otherwise an error is returned when
+  specified. To retrieve metadata see:
+  [Read Certificate Metadata](#read-certificate-metadata)
 
 #### Sample payload
 
@@ -2176,13 +2180,53 @@ $ curl \
   "data": {
     "issuer_id": "e27bf456-51e1-d937-0001-4a609184fd9b",
     "expiration": "2022-11-02T14:41:47.327515Z",
-    "metadata": "user-provided-metadata",
+    "cert_metadata": "dXNlci1wcm92aWRlZC1tZXRhZGF0YQ==",
     "role": "role-name",
     "serial_number": "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72"
   }
 }
 ```
 
+#### Sample cert_metadata fetch
+
+```shell-session
+$ base64 --decode <<< $(vault read --field=cert_metadata pki/cert-metadata/67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72 )
+user-provided-metadata
+```
+
+### List Certificate Metadata <EnterpriseAlert inline="true" />
+
+This endpoint returns a list of stored certificate metadata. Only the
+serial numbers of the certificates the metadata is associated with are
+returned, not the certificate metadata itself.
+
+| Method | Path                 |
+| :----- | :------------------- |
+| `LIST` | `/pki/cert-metadata` |
+
+#### Sample request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request LIST \
+    http://127.0.0.1:8200/v1/pki/cert-metadata
+```
+
+#### Sample response
+
+```json
+{
+  "auth": null,
+  "data": {
+    "keys": ["38:1f:29:ad:99:e8:c9:ae:7b:33:4d:b2:a5:c8:30:7c:71:93:77:ee", "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72"]
+  },
+  "lease_duration": 0,
+  "lease_id": "",
+  "renewable": false
+}
+```
+
 ---
 
 ## Managing keys and issuers