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..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 @@ -1201,6 +1201,79 @@ $ curl \ } ``` +## Generate multiple data keys + +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` | + +### Path parameters + +- `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. + +### Request parameters + +- `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.