diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx
index 1b720003eaa2..11c7cceb2df2 100644
--- a/website/content/api-docs/secret/pki.mdx
+++ b/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: "")` - 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: "")` - 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: "")` - 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: "")` - 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: "")` - 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: "")` - 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
+
+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