From c49bf1df60508ee8f86409f299de3ddad7e6bf98 Mon Sep 17 00:00:00 2001 From: rculpepper Date: Mon, 11 Aug 2025 13:58:38 -0400 Subject: [PATCH 1/2] add docs for datakeys endpoint --- .../content/api-docs/secret/transit.mdx | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx index 0e4956b498..31db6fc919 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx @@ -1201,6 +1201,77 @@ $ curl \ } ``` +## Generate multiple data keys + +This endpoint generates a specified number of new high-entropy keys and encrypts them with the +named key. Optionally return the plaintext of the keys as well. Whether plaintext +is returned depends on the path; as a result, you can use Vault ACL policies to +control whether a user is allowed to retrieve the plaintext value of the keys. This +is useful if you want an untrusted user or operation to generate keys that are +then made available to trusted users. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/transit/datakeys/:type/:name` | + +### Parameters + +- `type` `(string: )` – Specifies the type of keys to generate. If + `plaintext`, the plaintext keys will be returned along with the ciphertexts. If + `wrapped`, only the ciphertext values will be returned. This is specified as + part of the URL. + +- `name` `(string: )` – Specifies the name of the encryption key to + use to encrypt the datakeys. This is specified as part of the URL. + +- `count` `(int: )` - Specifies the number of keys to generate. + +- `bits` `(int: 256)` – Specifies the number of bits in the desired keys. Can be + 128, 256, or 512. + +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. Leave `key_version` unset to use the latest version. `key_version` + must be unset or greater than or equal to the associated + `min_encryption_version` value. + +### Sample payload + +```json +{ + "count": "2" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transit/datakey/plaintext/my-key +``` + +### Sample response + +```json +{ + "data": { + "key_pairs": [ + { + "ciphertext": "vault:v1:MA8yD4Neu2VtwrDbU8rcxPWGvkjK0ARquXyyiNMI+j34RNagvo0cu3l3e1HjEKL55I2k0PfTfAOisZMB", + "plaintext": "HT/dnq7RO9c5RloxMHGPDWUjscqdHLa0KAful8X12wg=" + }, + { + "ciphertext": "vault:v1:yOLlOVe6azNVuoZYARps+RHHJYr5x0Jror6DmjcAcXTFmXwfqiSjaEcl3GNdbofohfKfBawM4jxrtN+3", + "plaintext": "0srJIA4MVjNVkm9JR2in8KlMAmN0n+l8RLT7S9W9ESs=" + } + ], + "key_version": 1 + } +} +``` + ## Generate random bytes This endpoint returns high-quality random bytes of the specified length. From 486021701aca79bd6decbfe1a5ea513a7e186de3 Mon Sep 17 00:00:00 2001 From: Rachel Culpepper <84159930+rculpepper@users.noreply.github.com> Date: Tue, 16 Sep 2025 14:27:39 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../content/api-docs/secret/transit.mdx | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx index 31db6fc919..0b2ab12486 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx @@ -1203,26 +1203,28 @@ $ curl \ ## Generate multiple data keys -This endpoint generates a specified number of new high-entropy keys and encrypts them with the -named key. Optionally return the plaintext of the keys as well. Whether plaintext -is returned depends on the path; as a result, you can use Vault ACL policies to -control whether a user is allowed to retrieve the plaintext value of the keys. This -is useful if you want an untrusted user or operation to generate keys that are -then made available to trusted users. +The data keys endpoint generates the specified number of new, high-entropy keys. +Vault always returns keys encrypted with the provided named and optionally +returns the associated plaintext. + +You can use Vault ACL policies to control which users can retrieve the plaintext +value of the keys. For example, to allow untrusted users or operations to +generate keys that are then available to trusted users. | Method | Path | | :----- | :----------------------------- | | `POST` | `/transit/datakeys/:type/:name` | -### Parameters +### Path parameters -- `type` `(string: )` – Specifies the type of keys to generate. If - `plaintext`, the plaintext keys will be returned along with the ciphertexts. If - `wrapped`, only the ciphertext values will be returned. This is specified as - part of the URL. +- `type` `(enum: )` – Specifies the type of keys to generate. + - `plaintext` - return the plaintext keys along with the ciphertexts + - `wrapped` - only return the ciphertext values. - `name` `(string: )` – Specifies the name of the encryption key to - use to encrypt the datakeys. This is specified as part of the URL. + use to encrypt the datakeys. + +### Request parameters - `count` `(int: )` - Specifies the number of keys to generate.