v1.14.6/website/content/api-docs/secret/transit.mdx

---
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.