| --- |
| layout: api |
| page_title: Transit - Secrets Engines - HTTP API |
| description: This is the API documentation for the Vault Transit secrets engine. |
| --- |
| |
| # Transit secrets engine (API) |
| |
| This is the API documentation for the Vault Transit secrets engine. For general |
| information about the usage and operation of the Transit secrets engine, please |
| see the [transit documentation](/vault/docs/secrets/transit). |
| |
| This documentation assumes the transit secrets engine is enabled at the |
| `/transit` path in Vault. Since it is possible to enable secrets engines at any |
| location, please update your API calls accordingly. |
| |
| ## Create key |
| |
| This endpoint creates a new named encryption key of the specified type. The |
| values set here cannot be changed after key creation. |
| |
| | Method | Path | |
| | :----- | :-------------------- | |
| | `POST` | `/transit/keys/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| create. This is specified as part of the URL. |
| |
| - `convergent_encryption` `(bool: false)` – If enabled, the key will support |
| convergent encryption, where the same plaintext creates the same ciphertext. |
| This requires _derived_ to be set to `true`. When enabled, each |
| encryption(/decryption/rewrap/datakey) operation will derive a `nonce` value |
| rather than randomly generate it. |
| |
| - `derived` `(bool: false)` – Specifies if key derivation is to be used. If |
| enabled, all encrypt/decrypt requests to this named key must provide a context |
| which is used for key derivation. |
| |
| - `exportable` `(bool: false)` - Enables keys to be exportable. This |
| allows for all the valid keys in the key ring to be exported. Once set, this |
| cannot be disabled. |
| |
| - `allow_plaintext_backup` `(bool: false)` - If set, enables taking backup of |
| named key in the plaintext format. Once set, this cannot be disabled. |
| |
| - `type` `(string: "aes256-gcm96")` – Specifies the type of key to create. The |
| currently-supported types are: |
| |
| - `aes128-gcm96` – AES-128 wrapped with GCM using a 96-bit nonce size AEAD |
| (symmetric, supports derivation and convergent encryption) |
| - `aes256-gcm96` – AES-256 wrapped with GCM using a 96-bit nonce size AEAD |
| (symmetric, supports derivation and convergent encryption, default) |
| - `chacha20-poly1305` – ChaCha20-Poly1305 AEAD (symmetric, supports |
| derivation and convergent encryption) |
| - `ed25519` – ED25519 (asymmetric, supports derivation). When using |
| derivation, a sign operation with the same context will derive the same |
| key and signature; this is a signing analogue to `convergent_encryption`. |
| - `ecdsa-p256` – ECDSA using the P-256 elliptic curve (asymmetric) |
| - `ecdsa-p384` – ECDSA using the P-384 elliptic curve (asymmetric) |
| - `ecdsa-p521` – ECDSA using the P-521 elliptic curve (asymmetric) |
| - `rsa-2048` - RSA with bit size of 2048 (asymmetric) |
| - `rsa-3072` - RSA with bit size of 3072 (asymmetric) |
| - `rsa-4096` - RSA with bit size of 4096 (asymmetric) |
| - `hmac` - HMAC (HMAC generation, verification) |
| - `managed_key` - External key configured via the [Managed Keys](/vault/docs/enterprise/managed-keys) feature (enterprise only) |
| |
| ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified |
| and thus should not be used: `chacha20-poly1305` and `ed25519`. |
| |
| ~> **Note**: All key types support HMAC through the use of a second randomly |
| generated key created key creation time or rotation. The HMAC key type only |
| supports HMAC, and behaves identically to other algorithms with |
| respect to the HMAC operations but supports key import. By default, |
| the HMAC key type uses a 256-bit key. |
| |
| ~> **Note**: When key type is `managed_key`, either the `managed_key_name` or |
| `managed_key_id` parameter must be specified. |
| - `key_size` `(int: "0", optional)` - The key size in bytes for algorithms |
| that allow variable key sizes. Currently only applicable to HMAC, where |
| it must be between 32 and 512 bytes. |
| - `auto_rotate_period` `(duration: "0", optional)` – The period at which |
| this key should be rotated automatically. Setting this to "0" (the default) |
| will disable automatic key rotation. This value cannot be shorter than one |
| hour. Uses [duration format strings](/vault/docs/concepts/duration-format). |
| - `managed_key_name` `(string: "")` - The name of the managed key to use for this transit key. |
| - `managed_key_id` `(string: "")` - The UUID of the managed key to use for this transit key. |
| ### Sample payload |
| |
| ```json |
| { |
| "type": "ecdsa-p256", |
| "derived": true |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key |
| ``` |
| |
| ## Import key |
| |
| This endpoint imports existing key material into a new transit-managed encryption key. |
| To import key material into an existing key, see the `import_version/` endpoint. |
| |
| This supports one of two forms: |
| |
| 1. Private/Symmetric Key import, requiring the `ciphertext`, `hash_function` |
| parameters be set (and automatically deriving the public key), or |
| 2. Public Key-only import, restricting the operations that can be done with |
| this key, and requiring only the `public_key` parameter. |
| |
| The remaining parameters (including `name`, `type`, `allow_rotation`, |
| `derived`, `context`, `exportable`, `allow_plaintext_backup`, and |
| `auto_rotate_period`) remain the same across both versions of this call. |
| |
| | Method | Path | |
| | :----- | :--------------------------- | |
| | `POST` | `/transit/keys/:name/import` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| create. This is specified as part of the URL. |
| |
| - `ciphertext` `(string: <required>)` - A base64-encoded string that contains |
| two values: an ephemeral 256-bit AES key wrapped using the wrapping key |
| returned by Vault and the encryption of the import key material under the |
| provided AES key. The wrapped AES key should be the first 512 bytes of the |
| ciphertext, and the encrypted key material should be the remaining bytes. |
| See the BYOK section of the [Transit secrets engine documentation](/vault/docs/secrets/transit#bring-your-own-key-byok) |
| for more information on constructing the ciphertext. If `public_key` is set, |
| this field is not required. |
| |
| - `hash_function` `(string: "SHA256")` - The hash function used for the |
| RSA-OAEP step of creating the ciphertext. Supported hash functions are: |
| `SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512`. If not specified, |
| the hash function defaults to SHA256. |
| |
| - `type` `(string: <required>)` – Specifies the type of key to create. The |
| currently-supported types are: |
| |
| - `aes128-gcm96` – AES-128 wrapped with GCM using a 96-bit nonce size AEAD |
| (symmetric, supports derivation and convergent encryption) |
| - `aes256-gcm96` – AES-256 wrapped with GCM using a 96-bit nonce size AEAD |
| (symmetric, supports derivation and convergent encryption, default) |
| - `chacha20-poly1305` – ChaCha20-Poly1305 AEAD (symmetric, supports |
| derivation and convergent encryption) |
| - `ed25519` – ED25519 (asymmetric, supports derivation). When using |
| derivation, a sign operation with the same context will derive the same |
| key and signature; this is a signing analogue to `convergent_encryption`. |
| - `ecdsa-p256` – ECDSA using the P-256 elliptic curve (asymmetric) |
| - `ecdsa-p384` – ECDSA using the P-384 elliptic curve (asymmetric) |
| - `ecdsa-p521` – ECDSA using the P-521 elliptic curve (asymmetric) |
| - `rsa-2048` - RSA with bit size of 2048 (asymmetric) |
| - `rsa-3072` - RSA with bit size of 3072 (asymmetric) |
| - `rsa-4096` - RSA with bit size of 4096 (asymmetric) |
| |
| - `public_key` `(string: "", optional)` - A plaintext PEM public key to be |
| imported. This limits the operations available under this key to verification |
| and encryption, depending on the key type and algorithm, as no private key |
| is available. |
| |
| - `allow_rotation` `(bool: false)` - If set, the imported key can be rotated |
| within Vault by using the `rotate` endpoint. |
| |
| ~> **NOTE**: Once an imported key is rotated within Vault, it will no longer |
| support importing key material with the `import_version` endpoint. |
| |
| - `derived` `(bool: false)` – Specifies if key derivation is to be used. If |
| enabled, all encrypt/decrypt requests to this named key must provide a context |
| which is used for key derivation. |
| |
| - `context` `(string: "")` - A base64-encoded string providing a context for |
| key derivation. Required if `derived` is set to `true`. |
| |
| - `exportable` `(bool: false)` - Enables keys to be exportable. This |
| allows for all the valid keys in the key ring to be exported. Once set, this |
| cannot be disabled. |
| |
| - `allow_plaintext_backup` `(bool: false)` - If set, enables taking backup of |
| named key in the plaintext format. Once set, this cannot be disabled. |
| |
| - `auto_rotate_period` `(duration: "0", optional)` – The period at which |
| this key should be rotated automatically. Setting this to "0" (the default) |
| will disable automatic key rotation. This value cannot be shorter than one |
| hour. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "type": "ed25519", |
| "ciphertext": "..." |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key/import |
| ``` |
| |
| ## Import key version |
| |
| This endpoint imports new key material into an existing imported key. |
| |
| See description and note in [Import Key](#import-key) above about importing |
| public and private keys. |
| |
| Notably, using this method, a private key matching a public key can be |
| imported at a later date. |
| |
| | Method | Path | |
| | :----- | :----------------------------------- | |
| | `POST` | `/transit/keys/:name/import_version` | |
| |
| ~> **Note**: Keys whose material was generated by Vault do not support |
| importing key material. Only keys that were previously imported into |
| Vault can import new key material from an external source. |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| create. This is specified as part of the URL. |
| |
| - `ciphertext` `(string: <required>)` - A base64-encoded string that contains |
| two values: an ephemeral 256-bit AES key wrapped using the wrapping key |
| returned by Vault and the encryption of the import key material under the |
| provided AES key. The wrapped AES key should be the first 512 bytes of the |
| ciphertext, and the encrypted key material should be the remaining bytes. |
| See the BYOK section of the [Transit secrets engine documentation](/vault/docs/secrets/transit#bring-your-own-key-byok) |
| for more information on constructing the ciphertext. |
| |
| - `hash_function` `(string: "SHA256")` - The hash function used for the |
| RSA-OAEP step of creating the ciphertext. Supported hash functions are: |
| `SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512`. If not specified, |
| the hash function defaults to SHA256. |
| |
| - `public_key` `(string: "", optional)` - A plaintext PEM public key to be |
| imported. This limits the operations available under this key to verification |
| and encryption, depending on the key type and algorithm, as no private key |
| is available. |
| |
| - `version` `(int, optional)` - Key version to be updated, if left empty, |
| a new version will be created unless a private key is specified and the |
| 'Latest' key is missing a private key. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "ciphertext": "..." |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key/import_version |
| ``` |
| |
| ## Get wrapping key |
| |
| This endpoint is used to retrieve the wrapping key to use for importing keys. |
| The returned key will be a 4096-bit RSA public key. |
| |
| | Method | Path | |
| | :---- | :---------------------- | |
| | `GET` | `/transit/wrapping_key` | |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request GET \ |
| http://127.0.0.1:8200/v1/transit/wrapping_key |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "public_key": "..." |
| }, |
| } |
| ``` |
| |
| ## Read key |
| |
| This endpoint returns information about a named encryption key. The `keys` |
| object shows the creation time of each key version; the values are not the keys |
| themselves. Depending on the type of key, different information may be returned, |
| e.g. an asymmetric key will return its public key in a standard format for the |
| type. |
| |
| | Method | Path | |
| | :----- | :-------------------- | |
| | `GET` | `/transit/keys/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| read. This is specified as part of the URL. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "type": "aes256-gcm96", |
| "deletion_allowed": false, |
| "derived": false, |
| "exportable": false, |
| "allow_plaintext_backup": false, |
| "keys": { |
| "1": 1442851412 |
| }, |
| "min_decryption_version": 1, |
| "min_encryption_version": 0, |
| "name": "foo", |
| "supports_encryption": true, |
| "supports_decryption": true, |
| "supports_derivation": true, |
| "supports_signing": false, |
| "imported": false |
| } |
| } |
| ``` |
| |
| The `keys` attribute lists each version of the key, and the time that key was created as seconds since the Unix epoch. |
| The sample response shows a key that was created on September 22, 2015 7:50:12 PM GMT, and has not been rotated. |
| |
| The fields `supports_encryption`, `supports_decryption`, `supports_derivation` and `supports_signing` are |
| derived from the type of the key, and indicate which operations may be performed with it. |
| |
| ## List keys |
| |
| This endpoint returns a list of keys. Only the key names are returned (not the |
| actual keys themselves). |
| |
| | Method | Path | |
| | :----- | :-------------- | |
| | `LIST` | `/transit/keys` | |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request LIST \ |
| http://127.0.0.1:8200/v1/transit/keys |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "keys": ["foo", "bar"] |
| }, |
| "lease_duration": 0, |
| "lease_id": "", |
| "renewable": false |
| } |
| ``` |
| |
| ## Delete key |
| |
| This endpoint deletes a named encryption key. It will no longer be possible to |
| decrypt any data encrypted with the named key. Because this is a potentially |
| catastrophic operation, the `deletion_allowed` tunable must be set in the key's |
| `/config` endpoint. |
| |
| | Method | Path | |
| | :------- | :-------------------- | |
| | `DELETE` | `/transit/keys/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| delete. This is specified as part of the URL. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request DELETE \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key |
| ``` |
| |
| ## Update key configuration |
| |
| This endpoint allows tuning configuration values for a given key. (These values |
| are returned during a read operation on the named key.) |
| |
| | Method | Path | |
| | :----- | :--------------------------- | |
| | `POST` | `/transit/keys/:name/config` | |
| |
| ### Parameters |
| |
| - `min_decryption_version` `(int: 0)` – Specifies the minimum version of |
| ciphertext allowed to be decrypted. Adjusting this as part of a key rotation |
| policy can prevent old copies of ciphertext from being decrypted, should they |
| fall into the wrong hands. For signatures, this value controls the minimum |
| version of signature that can be verified against. For HMACs, this controls |
| the minimum version of a key allowed to be used as the key for verification. |
| |
| - `min_encryption_version` `(int: 0)` – Specifies the minimum version of the |
| key that can be used to encrypt plaintext, sign payloads, or generate HMACs. |
| Must be `0` (which will use the latest version) or a value greater or equal |
| to `min_decryption_version`. |
| |
| - `deletion_allowed` `(bool: false)` - Specifies if the key is allowed to be |
| deleted. |
| |
| - `exportable` `(bool: false)` - Enables keys to be exportable. This |
| allows for all the valid keys in the key ring to be exported. Once set, this |
| cannot be disabled. |
| |
| - `allow_plaintext_backup` `(bool: false)` - If set, enables taking backup of |
| named key in the plaintext format. Once set, this cannot be disabled. |
| |
| - `auto_rotate_period` `(duration: "", optional)` – The period at which this |
| key should be rotated automatically. Setting this to "0" will disable automatic |
| key rotation. This value cannot be shorter than one hour. When no value is |
| provided, the period remains unchanged. Uses [duration format strings](/vault/docs/concepts/duration-format). |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "deletion_allowed": true |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key/config |
| ``` |
| |
| ## Rotate key |
| |
| This endpoint rotates the version of the named key. After rotation, new |
| plaintext requests will be encrypted with the new version of the key. To upgrade |
| ciphertext to be encrypted with the latest version of the key, use the `rewrap` |
| endpoint. This is only supported with keys that support encryption and |
| decryption operations. |
| |
| For algorithms with a configurable key size, the rotated key will use the same |
| key size as the previous version. |
| |
| ~> **Note**: For imported keys, rotation is only supported if the |
| `allow_rotation` field was set to `true` on import. Once an imported key is |
| rotated within Vault, it will not support further import operations. |
| |
| | Method | Path | |
| | :----- | :--------------------------- | |
| | `POST` | `/transit/keys/:name/rotate` | |
| |
| ### Parameters |
| |
| - `managed_key_name` `(string: "")` - The name of the managed key to use for this transit key. |
| - `managed_key_id` `(string: "")` - The UUID of the managed key to use for this transit key. |
| |
| ~> **Note**: If the key to be rotated is of type `managed_key`, either the `managed_key_name` or |
| the `managed_key_id` for the new key must be provided. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key/rotate |
| ``` |
| |
| ## Securely export key |
| |
| This endpoint returns a wrapped copy of the `source` key, protected by the |
| `destination` key using BYOK method accepted by the |
| `/transit/keys/:name/import` API. This allows an operator using two separate |
| Vault instances to secure established shared key material, withing exposing |
| either key in plaintext and needing to run a manual BYOK import using the |
| CLI helper utility. |
| |
| | Method | Path | |
| | :----- | :----------------------------------------------------- | |
| | `GET` | `/transit/byok-export/:destination/:source(/:version)` | |
| |
| ### Parameters |
| |
| - `destination` `(string: <required>)` - Specifies the name of the key to |
| encrypt the `source` key to: this is usually another mount or cluster's |
| wrapping key (from `/transit/wrapping_key`). This is specified as part of |
| the URL. |
| |
| ~> Note: This destination key type must be an RSA key type. |
| |
| - `source` `(string: <required>)` - Specifies the source key to encrypt, to |
| copy (encrypted) to another cluster. This is specified as part of the URL. |
| |
| - `version` `(string: "")` - Specifies the version of the source key to |
| wrap. If omitted, all versions of the key will be returned. This is |
| specified as part of the URL. If the version is set to `latest`, the |
| current key will be returned. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| http://127.0.0.1:8200/v1/transit/byok-export/wrapping-key/to-be-shared-key/1 |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "name": "foo", |
| "keys": { |
| "1": "H/0T+CKQ8I82KJWpPk ... additional response elided ...", |
| } |
| } |
| } |
| ``` |
| |
| |
| ## Export key |
| |
| This endpoint returns the named key. The `keys` object shows the value of the |
| key for each version. If `version` is specified, the specific version will be |
| returned. If `latest` is provided as the version, the current key will be |
| provided. Depending on the type of key, different information may be returned. |
| The key must be exportable to support this operation and the version must still |
| be valid. |
| |
| | Method | Path | |
| | :----- | :------------------------------------------- | |
| | `GET` | `/transit/export/:key_type/:name(/:version)` | |
| |
| ### Parameters |
| |
| - `key_type` `(string: <required>)` – Specifies the type of the key to export. |
| This is specified as part of the URL. Valid values are: |
| |
| - `encryption-key` |
| - `signing-key` |
| - `hmac-key` |
| - `public-key`, to return the corresponding public keys of private key |
| asymmetric keys (EC with NIST P-curves or Ed25519 and RSA). |
| |
| - `name` `(string: <required>)` – Specifies the name of the key to read |
| information about. This is specified as part of the URL. |
| |
| - `version` `(string: "")` – Specifies the version of the key to read. If omitted, |
| all versions of the key will be returned. This is specified as part of the |
| URL. If the version is set to `latest`, the current key will be returned. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| http://127.0.0.1:8200/v1/transit/export/encryption-key/my-key/1 |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "name": "foo", |
| "keys": { |
| "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=", |
| "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE=" |
| } |
| } |
| } |
| ``` |
| |
| ## Write keys configuration |
| |
| This endpoint maintains global configuration across all keys. This |
| allows removing the upsert capability of the `/encrypt/:key` endpoint, |
| preventing new keys from being created if none exists. |
| |
| | Method | Path | |
| | :----- | :--------------------- | |
| | `POST` | `/transit/config/keys` | |
| |
| ### Parameters |
| |
| - `disable_upsert` `(bool: false)` - Specifies whether to disable upserting on |
| encryption (automatic creation of unknown keys). |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "disable_upsert": true |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/config/keys |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "disable_upsert": true, |
| } |
| } |
| ``` |
| |
| ## Read keys configuration |
| |
| This endpoint maintains global configuration across all keys. This |
| allows removing the upsert capability of the `/encrypt/:key` endpoint, |
| preventing new keys from being created if none exists. |
| |
| | Method | Path | |
| | :----- | :--------------------- | |
| | `GET` | `/transit/config/keys` | |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| http://127.0.0.1:8200/v1/transit/config/keys |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "disable_upsert": false, |
| } |
| } |
| ``` |
| |
| ## Encrypt data |
| |
| This endpoint encrypts the provided plaintext using the named key. This path |
| supports the `create` and `update` policy capabilities as follows: if the user |
| has the `create` capability for this endpoint in their policies, and the key |
| does not exist, it will be upserted with default values (whether the key |
| requires derivation depends on whether the context parameter is empty or not). |
| If the user only has `update` capability and the key does not exist, an error |
| will be returned. |
| |
| ~> Note: If upsert is disallowed by global keys configuration, `create` |
| requests will behave like `update` requests. |
| |
| | Method | Path | |
| | :----- | :----------------------- | |
| | `POST` | `/transit/encrypt/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| encrypt against. This is specified as part of the URL. |
| |
| - `plaintext` `(string: <required>)` – Specifies **base64 encoded** plaintext to |
| be encoded. |
| |
| - `associated_data` `(string: "")` - Specifies **base64 encoded** associated |
| data (also known as additional data or AAD) to also be authenticated with |
| AEAD ciphers (`aes128-gcm96`, `aes256-gcm`, and `chacha20-poly1305`). |
| |
| - `context` `(string: "")` – Specifies the **base64 encoded** context for key |
| derivation. This is required if key derivation is enabled for this key. |
| |
| - `key_version` `(int: 0)` – Specifies the version of the key to use for |
| encryption. If not set, uses the latest version. Must be greater than or |
| equal to the key's `min_encryption_version`, if set. |
| |
| - `nonce` `(string: "")` – Specifies the **base64 encoded** nonce value. This |
| must be provided if convergent encryption is enabled for this key and the key |
| was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The |
| value must be exactly 96 bits (12 bytes) long and the user must ensure that |
| for any given context (and thus, any given encryption key) this nonce value is |
| **never reused**. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items to be |
| encrypted in a single batch. When this parameter is set, if the parameters |
| 'plaintext', 'context' and 'nonce' are also set, they will be ignored. |
| Any batch output will preserve the order of the batch input. The |
| format for the input is: |
| |
| ```json |
| [ |
| { |
| "context": "c2FtcGxlY29udGV4dA==", |
| "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" |
| }, |
| { |
| "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", |
| "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" |
| } |
| ] |
| ``` |
| |
| - `type` `(string: "aes256-gcm96")` –This parameter is required when encryption |
| key is expected to be created. When performing an upsert operation, the type |
| of key to create. |
| |
| - `convergent_encryption` `(string: "")` – This parameter will only be used when |
| a key is expected to be created. Whether to support convergent encryption. |
| This is only supported when using a key with key derivation enabled and will |
| require all requests to carry both a context and 96-bit (12-byte) nonce. The |
| given nonce will be used in place of a randomly generated nonce. As a result, |
| when the same context and nonce are supplied, the same ciphertext is |
| generated. It is _very important_ when using this mode that you ensure that |
| all nonces are unique for a given context. Failing to do so will severely |
| impact the ciphertext's security. |
| |
| - `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails |
| to encrypt due to a bad input, but other batch items succeed, the HTTP response |
| code is 400 (Bad Request). Some applications may want to treat partial failures |
| differently. Providing the parameter returns the given response code integer |
| instead of a failed status code in this case. If all values fail an error |
| code is still returned. Be warned that some failures (such as failure to |
| decrypt) could be indicative of a security breach and should not be |
| ignored. |
| |
| ~>**NOTE:** All plaintext data **must be base64-encoded**. The reason for this |
| requirement is that Vault does not require that the plaintext is "text". It |
| could be a binary file such as a PDF or image. The easiest safe transport |
| mechanism for this data as part of a JSON payload is to base64-encode it. |
| |
| ### Sample payload |
| |
| Fist, encode the plaintext with base64: |
| |
| ```shell-session |
| $ echo "the quick brown fox" | base64 |
| dGhlIHF1aWNrIGJyb3duIGZveAo= |
| ``` |
| |
| Use the base64-encoded plaintext in the payload: |
| |
| ```json |
| { |
| "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" |
| } |
| ``` |
| |
| !> Vault HTTP API imposes a maximum request size of 32MB to prevent a denial of service attack. This can be tuned per [`listener` block](/vault/docs/configuration/listener/tcp) in the Vault server configuration. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/encrypt/my-key |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" |
| } |
| } |
| ``` |
| |
| ## Decrypt data |
| |
| This endpoint decrypts the provided ciphertext using the named key. |
| |
| | Method | Path | |
| | :----- | :----------------------- | |
| | `POST` | `/transit/decrypt/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| decrypt against. This is specified as part of the URL. |
| |
| - `ciphertext` `(string: <required>)` – Specifies the ciphertext to decrypt. |
| |
| - `associated_data` `(string: "")` - Specifies **base64 encoded** associated |
| data (also known as additional data or AAD) to also be authenticated with |
| AEAD ciphers (`aes128-gcm96`, `aes256-gcm`, and `chacha20-poly1305`). |
| |
| - `context` `(string: "")` – Specifies the **base64 encoded** context for key |
| derivation. This is required if key derivation is enabled. |
| |
| - `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during |
| encryption. Must be provided if convergent encryption is enabled for this key |
| and the key was generated with Vault 0.6.1. Not required for keys created in |
| 0.6.2+. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items to be |
| decrypted in a single batch. When this parameter is set, if the parameters |
| 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. |
| Any batch output will preserve the order of the batch input. Format |
| for the input goes like this: |
| |
| ```json |
| [ |
| { |
| "context": "c2FtcGxlY29udGV4dA==", |
| "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" |
| }, |
| { |
| "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", |
| "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" |
| } |
| ] |
| ``` |
| - `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails |
| to encrypt due to a bad input, but other batch items succeed, the HTTP response |
| code is 400 (Bad Request). Some applications may want to treat partial failures |
| differently. Providing the parameter returns the given response code integer |
| instead of a failed status code in this case. If all values fail an error |
| code is still returned. Be warned that some failures (such as failure to |
| decrypt) could be indicative of a security breach and should not be |
| ignored. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/decrypt/my-key |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" |
| } |
| } |
| ``` |
| |
| ## Rewrap data |
| |
| This endpoint rewraps the provided ciphertext using the latest version of the |
| named key. Because this never returns plaintext, it is possible to delegate this |
| functionality to untrusted users or scripts. |
| |
| | Method | Path | |
| | :----- | :---------------------- | |
| | `POST` | `/transit/rewrap/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| re-encrypt against. This is specified as part of the URL. |
| |
| - `ciphertext` `(string: <required>)` – Specifies the ciphertext to re-encrypt. |
| |
| - `context` `(string: "")` – Specifies the **base64 encoded** context for key |
| derivation. This is required if key derivation is enabled. |
| |
| - `key_version` `(int: 0)` – Specifies the version of the key to use for the |
| operation. If not set, uses the latest version. Must be greater than or equal |
| to the key's `min_encryption_version`, if set. |
| |
| - `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during |
| encryption. Must be provided if convergent encryption is enabled for this key |
| and the key was generated with Vault 0.6.1. Not required for keys created in |
| 0.6.2+. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items to be |
| re-encrypted in a single batch. When this parameter is set, if the parameters |
| 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. |
| Any batch output will preserve the order of the batch input. Format |
| for the input goes like this: |
| |
| ```json |
| [ |
| { |
| "context": "c2FtcGxlY29udGV4dA==", |
| "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" |
| }, |
| { |
| "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", |
| "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" |
| } |
| ] |
| ``` |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/rewrap/my-key |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "ciphertext": "vault:v2:abcdefgh" |
| } |
| } |
| ``` |
| |
| ## Generate data key |
| |
| This endpoint generates a new high-entropy key and the value encrypted with the |
| named key. Optionally return the plaintext of the key 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 a key. 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/datakey/:type/:name` | |
| |
| ### Parameters |
| |
| - `type` `(string: <required>)` – Specifies the type of key to generate. If |
| `plaintext`, the plaintext key will be returned along with the ciphertext. If |
| `wrapped`, only the ciphertext value will be returned. This is specified as |
| part of the URL. |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| use to encrypt the datakey. This is specified as part of the URL. |
| |
| - `context` `(string: "")` – Specifies the key derivation context, provided as a |
| base64-encoded string. This must be provided if derivation is enabled. |
| |
| - `nonce` `(string: "")` – Specifies a nonce value, provided as base64 encoded. |
| Must be provided if convergent encryption is enabled for this key and the key |
| was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The |
| value must be exactly 96 bits (12 bytes) long and the user must ensure that |
| for any given context (and thus, any given encryption key) this nonce value is |
| **never reused**. |
| |
| - `bits` `(int: 256)` – Specifies the number of bits in the desired key. Can be |
| 128, 256, or 512. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "context": "Ab3==" |
| } |
| ``` |
| |
| ### 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": { |
| "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", |
| "ciphertext": "vault:v1:abcdefgh" |
| } |
| } |
| ``` |
| |
| ## Generate random bytes |
| |
| This endpoint returns high-quality random bytes of the specified length. |
| |
| | Method | Path | |
| | :----- | :----------------------------------- | |
| | `POST` | `/transit/random(/:source)(/:bytes)` | |
| |
| ### Parameters |
| |
| - `bytes` `(int: 32)` – Specifies the number of bytes to return. This value can |
| be specified either in the request body, or as a part of the URL. |
| |
| - `format` `(string: "base64")` – Specifies the output encoding. Valid options |
| are `hex` or `base64`. |
| |
| - `source` `(string: "platform")` - Specifies the source of the requested bytes. |
| `platform`, the default, sources bytes from the platform's entropy source. |
| `seal` sources from entropy augmentation (enterprise only). |
| `all` mixes bytes from all available sources. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "format": "hex" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/random/164 |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo=" |
| } |
| } |
| ``` |
| |
| ## Hash data |
| |
| This endpoint returns the cryptographic hash of given data using the specified |
| algorithm. |
| |
| | Method | Path | |
| | :----- | :--------------------------- | |
| | `POST` | `/transit/hash(/:algorithm)` | |
| |
| ### Parameters |
| |
| - `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This |
| can also be specified as part of the URL. Currently-supported algorithms are: |
| |
| - `sha2-224` |
| - `sha2-256` |
| - `sha2-384` |
| - `sha2-512` |
| - `sha3-224` |
| - `sha3-256` |
| - `sha3-384` |
| - `sha3-512` |
| |
| ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified |
| and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and |
| `sha3-512`. |
| |
| - `input` `(string: <required>)` – Specifies the **base64 encoded** input data. |
| |
| - `format` `(string: "hex")` – Specifies the output encoding. This can be either |
| `hex` or `base64`. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "input": "adba32==" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/hash/sha2-512 |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo=" |
| } |
| } |
| ``` |
| |
| ## Generate HMAC |
| |
| This endpoint returns the digest of given data using the specified hash |
| algorithm and the named key. The key can be of any type supported by `transit`, |
| as each `transit` key version has an independent, random 256-bit HMAC secret key. If |
| the key is of a type that supports rotation, the latest (current) version will |
| be used. |
| |
| | Method | Path | |
| | :----- | :--------------------------------- | |
| | `POST` | `/transit/hmac/:name(/:algorithm)` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| generate hmac against. This is specified as part of the URL. |
| |
| - `key_version` `(int: 0)` – Specifies the version of the key to use for the |
| operation. If not set, uses the latest version. Must be greater than or equal |
| to the key's `min_encryption_version`, if set. |
| |
| - `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This |
| can also be specified as part of the URL. Currently-supported algorithms are: |
| |
| - `sha2-224` |
| - `sha2-256` |
| - `sha2-384` |
| - `sha2-512` |
| - `sha3-224` |
| - `sha3-256` |
| - `sha3-384` |
| - `sha3-512` |
| |
| ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified |
| and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and |
| `sha3-512`. |
| |
| - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of |
| `input` or `batch_input` must be supplied. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items for processing. |
| When this parameter is set, if the parameter 'input' is also set, it will be |
| ignored. Responses are returned in the 'batch_results' array component of the |
| 'data' element of the response. Any batch output will preserve the order of |
| the batch input. If the input data value of an item is invalid, the |
| corresponding item in the 'batch_results' will have the key 'error' with a value |
| describing the error. The format for batch_input is: |
| |
| ```json |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==" |
| }, |
| { |
| "input": "aGVsbG8gd29ybGQuCg==" |
| } |
| ] |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/hmac/my-key/sha2-512 |
| ``` |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "input": "adba32==" |
| } |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo=" |
| } |
| } |
| ``` |
| |
| ### Sample payload with batch_input |
| |
| ```json |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==" |
| }, |
| { |
| "input": "adba32==" |
| }, |
| {}, |
| { |
| "input": "" |
| } |
| ] |
| } |
| ``` |
| |
| ### Sample response for batch_input |
| |
| ```json |
| { |
| "data": { |
| "batch_results": [ |
| { |
| "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP" |
| }, |
| { |
| "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP" |
| }, |
| { |
| "error": "missing input for HMAC" |
| }, |
| { |
| "hmac": "vault:v1:/wsSP6iQ9ECO9RRkefKLXey9sDntzSjoiW0vBrWfUsYB0ISroyC6plUt/jN7gcOv9O+Ecow" |
| } |
| ] |
| } |
| } |
| ``` |
| |
| ## Sign data |
| |
| This endpoint returns the cryptographic signature of the given data using the |
| named key and the specified hash algorithm. The key must be of a type that |
| supports signing. |
| |
| | Method | Path | |
| | :----- | :-------------------------------------- | |
| | `POST` | `/transit/sign/:name(/:hash_algorithm)` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key to |
| use for signing. This is specified as part of the URL. |
| |
| - `key_version` `(int: 0)` – Specifies the version of the key to use for |
| signing. If not set, uses the latest version. Must be greater than or equal |
| to the key's `min_encryption_version`, if set. |
| |
| - `hash_algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use for |
| supporting key types (notably, not including `ed25519` which specifies its |
| own hash algorithm). This can also be specified as part of the URL. |
| Currently-supported algorithms are: |
| |
| - `sha1` |
| - `sha2-224` |
| - `sha2-256` |
| - `sha2-384` |
| - `sha2-512` |
| - `sha3-224` |
| - `sha3-256` |
| - `sha3-384` |
| - `sha3-512` |
| - `none` |
| |
| ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified |
| and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and |
| `sha3-512`. |
| |
| ~> ** Warning:** `sha1` should be considered a compromised algorithm and used |
| only for legacy applications. Signing using SHA-1 can be blocked by operators by |
| assigning the following policy corresponding to a named key: |
| |
| ```hcl |
| path "/transit/sign/:name/sha1" { |
| capabilities = ["deny"] |
| } |
| ``` |
| |
| ~> **Note**: using `hash_algorithm=none` requires setting `prehashed=true` |
| and `signature_algorithm=pkcs1v15`. This generates a `PKCSv1_5_NoOID` |
| signature rather than the `PKCSv1_5_DERnull` signature type usually |
| created. See [RFC 3447 Section 9.2](https://www.rfc-editor.org/rfc/rfc3447#section-9.2). |
| |
| - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of |
| `input` or `batch_input` must be supplied. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items for processing. |
| When this parameter is set, any supplied 'input' or 'context' parameters will be |
| ignored. Responses are returned in the 'batch_results' array component of the |
| 'data' element of the response. Any batch output will preserve the order of the |
| batch input. If the input data value of an item is invalid, the |
| corresponding item in the 'batch_results' will have the key 'error' with a value |
| describing the error. The format for batch_input is: |
| |
| ```json |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==", |
| "context": "abcd" |
| }, |
| { |
| "input": "aGVsbG8gd29ybGQuCg==", |
| "context": "efgh" |
| } |
| ] |
| } |
| ``` |
| |
| - `context` `(string: "")` - Base64 encoded context for key derivation. |
| Required if key derivation is enabled; currently only available with ed25519 |
| keys. |
| |
| - `prehashed` `(bool: false)` - Set to `true` when the input is already hashed. |
| If the key type is `rsa-2048`, `rsa-3072` or `rsa-4096`, then the algorithm used to hash |
| the input should be indicated by the `hash_algorithm` parameter. Just as the |
| value to sign should be the base64-encoded representation of the exact binary |
| data you want signed, when set, `input` is expected to be base64-encoded |
| binary hashed data, not hex-formatted. (As an example, on the command line, |
| you could generate a suitable input via `openssl dgst -sha256 -binary | base64`.) |
| |
| - `signature_algorithm` `(string: "pss")` – When using a RSA key, specifies the RSA |
| signature algorithm to use for signing. Supported signature types are: |
| |
| - `pss` |
| - `pkcs1v15` |
| |
| - `marshaling_algorithm` `(string: "asn1")` – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are: |
| |
| - `asn1`: The default, used by OpenSSL and X.509 |
| - `jws`: The version used by JWS (and thus for JWTs). Selecting this will |
| also change the output encoding to URL-safe Base64 encoding instead of |
| standard Base64-encoding. |
| |
| - `salt_length` `(string: "auto")` – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. Options are: |
| |
| - `auto`: The default used by Golang (causing the salt to be as large as possible when signing) |
| - `hash`: Causes the salt length to equal the length of the hash used in the signature |
| - An integer between the minimum and the maximum permissible salt lengths for the given RSA key size. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/sign/my-key/sha2-512 |
| ``` |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "input": "adba32==" |
| } |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI=" |
| } |
| } |
| ``` |
| |
| ### Sample payload with batch_input |
| |
| Given an ed25519 key with derived keys set, the context parameter is expected for each batch_input item, and |
| the response will include the derived public key for each item. |
| |
| ``` |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==", |
| "context": "efgh" |
| }, |
| { |
| "input": "adba32==", |
| "context": "abcd" |
| }, |
| {} |
| ] |
| } |
| ``` |
| |
| ### Sample response for batch_input |
| |
| ``` |
| { |
| "data": { |
| "batch_results": [ |
| { |
| "signature": "vault:v1:+R3cxAy6j4KriYzAyExU6p1glnyT/eLDSaUZO7gr8a8kgi/zSynNbOBSDJcGaAfLD1OF2hGupYBYTjmZMNoVAA==", |
| "publickey": "2fQIaaem7+EhSGs3jUebAS/8qP2+sUrmxOmgqZIZc0c=" |
| }, |
| { |
| "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA==", |
| "publickey": "goDXuePo7L9z6HOw+a54O4HeV189BLECK9nAUudwp4Y=" |
| }, |
| { |
| "error": "missing input" |
| } |
| ] |
| }, |
| } |
| ``` |
| |
| ## Verify signed data |
| |
| This endpoint returns whether the provided signature is valid for the given |
| data. |
| |
| | Method | Path | |
| | :----- | :---------------------------------------- | |
| | `POST` | `/transit/verify/:name(/:hash_algorithm)` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` – Specifies the name of the encryption key that |
| was used to generate the signature or HMAC. |
| |
| - `hash_algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This |
| can also be specified as part of the URL. Currently-supported algorithms are: |
| |
| - `sha1` |
| - `sha2-224` |
| - `sha2-256` |
| - `sha2-384` |
| - `sha2-512` |
| - `sha3-224` |
| - `sha3-256` |
| - `sha3-384` |
| - `sha3-512` |
| - `none` |
| |
| ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified |
| and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and |
| `sha3-512`. |
| |
| ~> ** Warning:** `sha1` should be considered a compromised algorithm. Signatures |
| verified using the algorithm could be forgeries. Verification using SHA-1 can |
| be blocked by operators by assigning the following policy corresponding to a |
| named key: |
| |
| ```hcl |
| path "/transit/verify/:name/sha1" { |
| capabilities = ["deny"] |
| } |
| ``` |
| |
| ~> **Note**: using `hash_algorithm=none` requires setting `prehashed=true` |
| and `signature_algorithm=pkcs1v15`. This verifies a `PKCSv1_5_NoOID` |
| signature rather than the `PKCSv1_5_DERnull` signature type usually |
| verified. See [RFC 3447 Section 9.2](https://www.rfc-editor.org/rfc/rfc3447#section-9.2). |
| |
| - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of |
| `input` or `batch_input` must be supplied. |
| |
| - `signature` `(string: "")` – Specifies the signature output from the |
| `/transit/sign` function. Either this must be supplied or `hmac` must be |
| supplied. |
| |
| - `hmac` `(string: "")` – Specifies the signature output from the |
| `/transit/hmac` function. Either this must be supplied or `signature` must be |
| supplied. |
| |
| - `reference` `(string: "")` - |
| A user-supplied string that will be present in the `reference` field on the |
| corresponding `batch_results` item in the response, to assist in understanding |
| which result corresponds to a particular input. Only valid on batch requests |
| when using ‘batch_input’ below. |
| |
| - `batch_input` `(array<object>: nil)` – Specifies a list of items for processing. |
| When this parameter is set, any supplied 'input', 'hmac' or 'signature' parameters |
| will be ignored. 'batch_input' items should contain an 'input' parameter and |
| either an 'hmac' or 'signature' parameter. All items in the batch must consistently |
| supply either 'hmac' or 'signature' parameters. It is an error for some items to |
| supply 'hmac' while others supply 'signature'. Responses are returned in the |
| 'batch_results' array component of the 'data' element of the response. Any batch |
| output will preserve the order of the batch input. If the input data value of an |
| item is invalid, the corresponding item in the 'batch_results' will have the key |
| 'error' with a value describing the error. The format for batch_input is: |
| |
| ```json |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==", |
| "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP" |
| }, |
| { |
| "input": "aGVsbG8gd29ybGQuCg==", |
| "hmac": "vault:v1:/wsSP6iQ9ECO9RRkefKLXey9sDntzSjoiW0vBrWfUsYB0ISroyC6plUt/jN7gcOv9O+Ecow" |
| } |
| ] |
| } |
| ``` |
| |
| - `context` `(string: "")` - Base64 encoded context for key derivation. |
| Required if key derivation is enabled; currently only available with ed25519 |
| keys. |
| |
| - `prehashed` `(bool: false)` - Set to `true` when the input is already |
| hashed. If the key type is `rsa-2048`, `rsa-3072` or `rsa-4096`, then the algorithm used |
| to hash the input should be indicated by the `hash_algorithm` parameter. |
| |
| - `signature_algorithm` `(string: "pss")` – When using a RSA key, specifies the RSA |
| signature algorithm to use for signature verification. Supported signature types |
| are: |
| |
| - `pss` |
| - `pkcs1v15` |
| |
| - `marshaling_algorithm` `(string: "asn1")` – Specifies the way in which the signature was originally marshaled. This currently only applies to ECDSA keys. Supported types are: |
| |
| - `asn1`: The default, used by OpenSSL and X.509 |
| - `jws`: The version used by JWS (and thus for JWTs). Selecting this will |
| also expect the input encoding to URL-safe Base64 encoding instead of |
| standard Base64-encoding. |
| |
| - `salt_length` `(string: "auto")` – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. Options are: |
| |
| - `auto`: The default used by Golang (causing the salt to be as large as possible when signing) |
| - `hash`: Causes the salt length to equal the length of the hash used in the signature |
| - An integer between the minimum and the maximum permissible salt lengths for the given RSA key size. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/verify/my-key/sha2-512 |
| ``` |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "input": "abcd13==", |
| "signature": "vault:v1:MEUCIQCyb869d7KWuA..." |
| } |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "valid": true |
| } |
| } |
| ``` |
| |
| ### Sample payload with batch_input |
| |
| ``` |
| { |
| "batch_input": [ |
| { |
| "input": "adba32==", |
| "context": "abcd", |
| "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA==" |
| }, |
| { |
| "input": "adba32==", |
| "context": "efgh", |
| "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA==" |
| }, |
| { |
| "input": "", |
| "context": "abcd", |
| "signature": "vault:v1:C/pxm5V1RI6kqudLdbLdj5Bpm2P38FKgvxoV69oNXphvJukRcQIqjZO793jCa2JPYPG21Y7vquDWy/Ff4Ma4AQ==" |
| } |
| ] |
| } |
| ``` |
| |
| ### Sample response for batch_input |
| |
| ``` |
| { |
| "data": { |
| "batch_results": [ |
| { |
| "valid": true |
| }, |
| { |
| "valid": false |
| }, |
| { |
| "valid": true |
| } |
| ] |
| }, |
| } |
| ``` |
| |
| ## Backup key |
| |
| This endpoint returns a plaintext backup of a named key. The backup contains all |
| the configuration data and keys of all the versions along with the HMAC key. |
| The response from this endpoint can be used with the `/restore` endpoint to |
| restore the key. |
| |
| | Method | Path | |
| | :----- | :---------------------- | |
| | `GET` | `/transit/backup/:name` | |
| |
| ### Parameters |
| |
| - `name` `(string: <required>)` - Name of the key. |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| http://127.0.0.1:8200/v1/transit/backup/aes |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| { |
| "data": { |
| "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg==" |
| } |
| } |
| ``` |
| |
| ## Restore key |
| |
| This endpoint restores the backup as a named key. This will restore the key |
| configurations and all the versions of the named key along with HMAC keys. The |
| input to this endpoint should be the output of `/backup` endpoint. |
| |
| ~> For safety, by default the backend will refuse to restore to an existing |
| key. If you want to reuse a key name, it is recommended you delete the key |
| before restoring. It is a good idea to attempt restoring to a different key |
| name first to verify that the operation successfully completes. |
| |
| | Method | Path | |
| | :----- | :------------------------- | |
| | `POST` | `/transit/restore(/:name)` | |
| |
| ### Parameters |
| |
| - `backup` `(string: <required>)` - Backed up key data to be restored. This |
| should be the output from the `/backup` endpoint. |
| |
| - `name` `(string: <optional>)` - If set, this will be the name of the |
| restored key. |
| |
| - `force` `(bool: false)` - If set, force the restore to proceed even if a key |
| by this name already exists. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg==" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/restore |
| ``` |
| |
| ## Trim key |
| |
| This endpoint trims older key versions setting a minimum version for the |
| keyring. Once trimmed, previous versions of the key cannot be recovered. |
| |
| | Method | Path | |
| | :----- | :------------------------- | |
| | `POST` | `/transit/keys/:name/trim` | |
| |
| ### Parameters |
| |
| - `min_available_version` `(int: <required>)` - The minimum available version |
| for the key ring. All versions before this version will be permanently |
| deleted. This value can at most be equal to the lesser of |
| `min_decryption_version` and `min_encryption_version`. This is not allowed to |
| be set when either `min_encryption_version` or `min_decryption_version` is set |
| to zero. |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "min_available_version": 2 |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/keys/my-key/trim |
| ``` |
| |
| ## Configure cache |
| |
| This endpoint is used to configure the transit engine's cache. Note that configuration |
| changes will not be applied until the transit plugin is reloaded which can be achieved |
| using the [`/sys/plugins/reload/backend`][sys-plugin-reload-backend] endpoint. |
| |
| | Method | Path | |
| | :----- | :---------------------- | |
| | `POST` | `/transit/cache-config` | |
| |
| ### Parameters |
| |
| - `size` `(int: 0)` - Specifies the size in terms of number of entries. A size of |
| `0` means unlimited. A _Least Recently Used_ (LRU) caching strategy is used for a |
| non-zero cache size. Must be 0 (default) or a value greater or equal to 10 (minimum cache size). |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "size": 456 |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/transit/cache-config |
| ``` |
| |
| ## Read transit cache configuration |
| |
| This endpoint retrieves configurations for the transit engine's cache. |
| |
| | Method | Path | |
| | :----- | :---------------------- | |
| | `GET` | `/transit/cache-config` | |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." |
| --request GET \ |
| http://127.0.0.1:8200/v1/transit/cache-config |
| ``` |
| |
| ### Sample response |
| |
| ```json |
| "data": { |
| "size": 0 |
| }, |
| ``` |
| |
| ## Managed keys <EnterpriseAlert inline="true" /> |
| |
| Managed Keys can be used with the Transit Secrets Engine to perform cryptographic operations. Currently, |
| [Sign Data](#sign-data) and [Verify Signed Data](#verify-signed-data) are well-supported across all the managed key types. |
| |
| Only PKCS#11 managed keys support [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) operations at this time. We |
| are planning on adding support for AWS, GCP and Azure managed keys at a later time. |
| |
| When a Transit key is created of type `managed_key`, Transit will look up the key by name or ID, and will |
| attempt to generate the key when key generation is allowed (as specified when the [Create/Update Managed Key](/vault/api-docs/system/managed-keys#create-update-managed-key) |
| endpoint is called). Key generation is currently supported for cloud KMSes and for certain PKCS#11 mechanisms |
| on HSMs. This is a best effort operation, so certain KMS/HSM/key configurations will require the key to exist |
| externally prior to use with Transit. |
| |
| For key types and mechanisms that require an IV, this value can be provided via the `nonce` parameter of |
| the [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) endpoints. |
| |
| Signing and verifying data with a Managed Key through Transit may require pre-hashing of the data. Transit |
| can be informed that data is pre-hashed with the `prehashed` parameter of the [Sign Data](#sign-data) and |
| [Verify Signed Data](#verify-signed-data) endpoints. |
| |