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