vault Transit secrets engine layout docs page title Transit Secrets Engines doesn t store any secrets The transit secrets engine for Vault encrypts decrypts data in transit It

Answer:
---
layout: docs
page_title: Transit - Secrets Engines
description: >-
  The transit secrets engine for Vault encrypts/decrypts data in-transit. It
  doesn't store any secrets.
---

# Transit secrets engine

The transit secrets engine handles cryptographic functions on data in-transit.
Vault doesn't store the data sent to the secrets engine. It can also be viewed
as "cryptography as a service" or "encryption as a service". The transit secrets
engine can also sign and verify data; generate hashes and HMACs of data; and act
as a source of random bytes.

The primary use case for `transit` is to encrypt data from applications while
still storing that encrypted data in some primary data store. This relieves the
burden of proper encryption/decryption from application developers and pushes
the burden onto the operators of Vault.

Key derivation is supported, which allows the same key to be used for multiple
purposes by deriving a new key based on a user-supplied context value. In this
mode, convergent encryption can optionally be supported, which allows the same
input values to produce the same ciphertext.

Datakey generation allows processes to request a high-entropy key of a given
bit length be returned to them, encrypted with the named key. Normally this will
also return the key in plaintext to allow for immediate use, but this can be
disabled to accommodate auditing requirements.

## Working set management

The Transit engine supports versioning of keys. Key versions that are earlier
than a key's specified `min_decryption_version` gets archived, and the rest of
the key versions belong to the working set. This is a performance consideration
to keep key loading fast, as well as a security consideration: by disallowing
decryption of old versions of keys, found ciphertext corresponding to obsolete
(but sensitive) data can not be decrypted by most users, but in an emergency
the `min_decryption_version` can be moved back to allow for legitimate
decryption.

Currently this archive is stored in a single storage entry. With some storage
backends, notably those using Raft or Paxos for HA capabilities, frequent
rotation may lead to a storage entry size for the archive that is larger than
the storage backend can handle. For frequent rotation needs, using named keys
that correspond to time bounds (e.g. five-minute periods floored to the closest
multiple of five) may provide a good alternative, allowing for several keys to
be live at once and a deterministic way to decide which key to use at any given
time.

## NIST rotation guidance

Periodic rotation of the encryption keys is recommended, even in the absence of
compromise. For AES-GCM keys, rotation should occur before approximately 232
encryptions have been performed by a key version, following the guidelines of NIST
publication 800-38D. It is recommended that operators estimate the
encryption rate of a key and use that to determine a frequency of rotation
that prevents the guidance limits from being reached. For example, if one determines
that the estimated rate is 40 million operations per day, then rotating a key every
three months is sufficient.

## Key types

As of now, the transit secrets engine supports the following key types (all key
types also generate separate HMAC keys):

- `aes128-gcm96`: AES-GCM with a 128-bit AES key and a 96-bit nonce; supports
  encryption, decryption, key derivation, and convergent encryption
- `aes256-gcm96`: AES-GCM with a 256-bit AES key and a 96-bit nonce; supports
  encryption, decryption, key derivation, and convergent encryption (default)
- `chacha20-poly1305`: ChaCha20-Poly1305 with a 256-bit key; supports
  encryption, decryption, key derivation, and convergent encryption
- `ed25519`: Ed25519; supports signing, signature verification, and key
  derivation
- `ecdsa-p256`: ECDSA using curve P-256; supports signing and signature
  verification
- `ecdsa-p384`: ECDSA using curve P-384; supports signing and signature
  verification
- `ecdsa-p521`: ECDSA using curve P-521; supports signing and signature
  verification
- `rsa-2048`: 2048-bit RSA key; supports encryption, decryption, signing, and
  signature verification
- `rsa-3072`: 3072-bit RSA key; supports encryption, decryption, signing, and
  signature verification
- `rsa-4096`: 4096-bit RSA key; supports encryption, decryption, signing, and
  signature verification
- `hmac`: HMAC; supporting HMAC generation and verification.
- `managed_key`: Managed key; supports a variety of operations depending on the
  backing key management solution. See [Managed Keys](/vault/docs/enterprise/managed-keys)
  for more information. <EnterpriseAlert inline="true" />
- `aes128-cmac`: CMAC with a 128-bit AES key; supporting CMAC generation and verification. <EnterpriseAlert inline="true" />
- `aes256-cmac`: CMAC with a 256-bit AES key; supporting CMAC generation and verification. <EnterpriseAlert inline="true" />

~> **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 operations 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.

RSA operations use one of the following methods:

 - OAEP (encrypt, decrypt), with SHA-256 hash function and MGF,
 - PSS (sign, verify), with configurable hash function also used for MGF, and
 - PKCS#1v1.5: (sign, verify), with configurable hash function.

## Convergent encryption

Convergent encryption is a mode where the same set of plaintext+context always
result in the same ciphertext. It does this by deriving a key using a key
derivation function but also by deterministically deriving a nonce. Because
these properties differ for any combination of plaintext and ciphertext over a
keyspace the size of 2^256, the risk of nonce reuse is near zero.

This has many practical uses. One common usage mode is to allow values to be stored
encrypted in a database, but with limited lookup/query support, so that rows
with the same value for a specific field can be returned from a query.

To accommodate for any needed upgrades to the algorithm, different versions of
convergent encryption have historically been supported:

- Version 1 required the client to provide their own nonce, which is highly
  flexible but if done incorrectly can be dangerous. This was only in Vault
  0.6.1, and keys using this version cannot be upgraded.
- Version 2 used an algorithmic approach to deriving the parameters. However,
  the algorithm used was susceptible to offline plaintext-confirmation attacks,
  which could allow attackers to brute force decryption if the plaintext size
  was small. Keys using version 2 can be upgraded by simply performing a rotate
  operation to a new key version; existing values can then be rewrapped against
  the new key version and will use the version 3 algorithm.
- Version 3 uses a different algorithm designed to be resistant to offline
  plaintext-confirmation attacks. It is similar to AES-SIV in that it uses a
  PRF to generate the nonce from the plaintext.

## Setup

Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.

1. Enable the Transit secrets engine:

   ```text
   $ vault secrets enable transit
   Success! Enabled the transit secrets engine at: transit/
   ```

   By default, the secrets engine will mount at the name of the engine. To
   enable the secrets engine at a different path, use the `-path` argument.

1. Create a named encryption key:

   ```text
   $ vault write -f transit/keys/my-key
   Success! Data written to: transit/keys/my-key
   ```

   Usually each application has its own encryption key.

## Usage

After the secrets engine is configured and a user/machine has a Vault token with
the proper permission, it can use this secrets engine.

1.  Encrypt some plaintext data using the `/encrypt` endpoint with a named key:

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

    ```text
    $ vault write transit/encrypt/my-key plaintext=$(echo "my secret data" | base64)

    Key           Value
    ---           -----
    ciphertext    vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==
    ```

    The returned ciphertext starts with `vault:v1:`. The first prefix (`vault`)
    identifies that it has been wrapped by Vault. The `v1` indicates the key
    version 1 was used to encrypt the plaintext; therefore, when you rotate
    keys, Vault knows which version to use for decryption. The rest is a base64
    concatenation of the initialization vector (IV) and ciphertext.

    Note that Vault does not _store_ any of this data. The caller is responsible
    for storing the encrypted ciphertext. When the caller wants the plaintext,
    it must provide the ciphertext back to Vault to decrypt the value.

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

1.  Decrypt a piece of data using the `/decrypt` endpoint with a named key:

    ```text
    $ vault write transit/decrypt/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

    Key          Value
    ---          -----
    plaintext    bXkgc2VjcmV0IGRhdGEK
    ```

    The resulting data is base64-encoded (see the note above for details on
    why). Decode it to get the raw plaintext:

    ```text
    $ base64 --decode <<< "bXkgc2VjcmV0IGRhdGEK"
    my secret data
    ```

    It is also possible to script this decryption using some clever shell
    scripting in one command:

    ```text
    $ vault write -field=plaintext transit/decrypt/my-key ciphertext=... | base64 --decode
    my secret data
    ```

    Using ACLs, it is possible to restrict using the transit secrets engine such
    that trusted operators can manage the named keys, and applications can only
    encrypt or decrypt using the named keys they need access to.

1.  Rotate the underlying encryption key. This will generate a new encryption key
    and add it to the keyring for the named key:

    ```text
    $ vault write -f transit/keys/my-key/rotate
    Success! Data written to: transit/keys/my-key/rotate
    ```

    Future encryptions will use this new key. Old data can still be decrypted
    due to the use of a key ring.

1.  Upgrade already-encrypted data to a new key. Vault will decrypt the value
    using the appropriate key in the keyring and then encrypt the resulting
    plaintext with the newest key in the keyring.

    ```text
    $ vault write transit/rewrap/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

    Key           Value
    ---           -----
    ciphertext    vault:v2:0VHTTBb2EyyNYHsa3XiXsvXOQSLKulH+NqS4eRZdtc2TwQCxqJ7PUipvqQ==
    ```

    This process **does not** reveal the plaintext data. As such, a Vault policy
    could grant almost an untrusted process the ability to "rewrap" encrypted
    data, since the process would not be able to get access to the plaintext
    data.

## Bring your own key (BYOK)

~> **Note:** Key import functionality supports cases in which there is a need to bring
in an existing key from an HSM or other outside system. It is more secure to
have Transit generate and manage a key within Vault.

### Via the Command Line

The Vault command line tool [includes a helper](/vault/docs/commands/transit/) to perform the steps described
in Manual below.

### Via the API

First, the wrapping key needs to be read from transit:

```text
$ vault read transit/wrapping_key
```

The wrapping key will be a 4096-bit RSA public key.

Then the wrapping key is used to create the ciphertext input for the `import` endpoint,
as described below. In the below, the target key refers to the key being imported.

### HSM

If the key is being imported from an HSM that supports PKCS#11, there are
two possible scenarios:

- If the HSM supports the CKM_RSA_AES_KEY_WRAP mechanism, that can be used to wrap the
  target key using the wrapping key.

- Otherwise, two mechanisms can be combined to wrap the target key. First, a 256-bit AES key should
  be generated and then used to wrap the target key using the CKM_AES_KEY_WRAP_KWP mechanism.
  Then the AES key should be wrapped under the wrapping key using the CKM_RSA_PKCS_OAEP mechanism
  using MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.

The ciphertext is constructed by appending the wrapped target key to the wrapped AES key.

The ciphertext bytes should be base64-encoded.

### Manual process

If the target key is not stored in an HSM or KMS, the following steps can be used to construct
the ciphertext for the input of the `import` endpoint:

- Generate an ephemeral 256-bit AES key.

- Wrap the target key using the ephemeral AES key with AES-KWP.

~> Note: When wrapping a symmetric key (such as an AES or ChaCha20 key), wrap
   the raw bytes of the key. For instance, with an AES 128-bit key, this'll be
   a byte array 16 characters in length that will directly be wrapped without
   base64 or other encodings.

When wrapping an asymmetric key
   (such as a RSA or ECDSA key), wrap the **PKCS8** encoded format of this
   key, in raw DER/binary form. Do not apply PEM encoding to this blob prior
   to encryption and do not base64 encode it.

- Wrap the AES key under the Vault wrapping key using RSAES-OAEP with MGF1 and
  either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.

- Delete the ephemeral AES key.

- Append the wrapped target key to the wrapped AES key.

- Base64 encode the result.

For more details about wrapping the key for import into transit, see the
[key wrapping guide](/vault/docs/secrets/transit/key-wrapping-guide).

## Tutorial

Refer to the [Encryption as a Service: Transit Secrets
Engine](/vault/tutorials/encryption-as-a-service/eaas-transit)
tutorial to learn how to use the transit secrets engine to handle cryptographic functions on data in-transit.

## API

The Transit secrets engine has a full HTTP API. Please see the
[Transit secrets engine API](/vault/api-docs/secret/transit) for more
details.

layout  docs page title  Transit   Secrets Engines description       The transit secrets engine for Vault encrypts decrypts data in transit  It   doesn t store any secrets         Transit secrets engine  The transit secrets engine handles cryptographic functions on data in transit  Vault doesn t store the data sent to the secrets engine  It can also be viewed as  cryptography as a service  or  encryption as a service   The transit secrets engine can also sign and verify data  generate hashes and HMACs of data  and act as a source of random bytes   The primary use case for  transit  is to encrypt data from applications while still storing that encrypted data in some primary data store  This relieves the burden of proper encryption decryption from application developers and pushes the burden onto the operators of Vault   Key derivation is supported  which allows the same key to be used for multiple purposes by deriving a new key based on a user supplied context value  In this mode  convergent encryption can optionally be supported  which allows the same input values to produce the same ciphertext   Datakey generation allows processes to request a high entropy key of a given bit length be returned to them  encrypted with the named key  Normally this will also return the key in plaintext to allow for immediate use  but this can be disabled to accommodate auditing requirements      Working set management  The Transit engine supports versioning of keys  Key versions that are earlier than a key s specified  min decryption version  gets archived  and the rest of the key versions belong to the working set  This is a performance consideration to keep key loading fast  as well as a security consideration  by disallowing decryption of old versions of keys  found ciphertext corresponding to obsolete  but sensitive  data can not be decrypted by most users  but in an emergency the  min decryption version  can be moved back to allow for legitimate decryption   Currently this archive is stored in a single storage entry  With some storage backends  notably those using Raft or Paxos for HA capabilities  frequent rotation may lead to a storage entry size for the archive that is larger than the storage backend can handle  For frequent rotation needs  using named keys that correspond to time bounds  e g  five minute periods floored to the closest multiple of five  may provide a good alternative  allowing for several keys to be live at once and a deterministic way to decide which key to use at any given time      NIST rotation guidance  Periodic rotation of the encryption keys is recommended  even in the absence of compromise  For AES GCM keys  rotation should occur before approximately 2 sup 32  sup  encryptions have been performed by a key version  following the guidelines of NIST publication 800 38D  It is recommended that operators estimate the encryption rate of a key and use that to determine a frequency of rotation that prevents the guidance limits from being reached  For example  if one determines that the estimated rate is 40 million operations per day  then rotating a key every three months is sufficient      Key types  As of now  the transit secrets engine supports the following key types  all key types also generate separate HMAC keys       aes128 gcm96   AES GCM with a 128 bit AES key and a 96 bit nonce  supports   encryption  decryption  key derivation  and convergent encryption    aes256 gcm96   AES GCM with a 256 bit AES key and a 96 bit nonce  supports   encryption  decryption  key derivation  and convergent encryption  default     chacha20 poly1305   ChaCha20 Poly1305 with a 256 bit key  supports   encryption  decryption  key derivation  and convergent encryption    ed25519   Ed25519  supports signing  signature verification  and key   derivation    ecdsa p256   ECDSA using curve P 256  supports signing and signature   verification    ecdsa p384   ECDSA using curve P 384  supports signing and signature   verification    ecdsa p521   ECDSA using curve P 521  supports signing and signature   verification    rsa 2048   2048 bit RSA key  supports encryption  decryption  signing  and   signature verification    rsa 3072   3072 bit RSA key  supports encryption  decryption  signing  and   signature verification    rsa 4096   4096 bit RSA key  supports encryption  decryption  signing  and   signature verification    hmac   HMAC  supporting HMAC generation and verification     managed key   Managed key  supports a variety of operations depending on the   backing key management solution  See  Managed Keys   vault docs enterprise managed keys    for more information   EnterpriseAlert inline  true        aes128 cmac   CMAC with a 128 bit AES key  supporting CMAC generation and verification   EnterpriseAlert inline  true        aes256 cmac   CMAC with a 256 bit AES key  supporting CMAC generation and verification   EnterpriseAlert inline  true           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 operations 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   RSA operations use one of the following methods      OAEP  encrypt  decrypt   with SHA 256 hash function and MGF     PSS  sign  verify   with configurable hash function also used for MGF  and    PKCS 1v1 5   sign  verify   with configurable hash function      Convergent encryption  Convergent encryption is a mode where the same set of plaintext context always result in the same ciphertext  It does this by deriving a key using a key derivation function but also by deterministically deriving a nonce  Because these properties differ for any combination of plaintext and ciphertext over a keyspace the size of 2 256  the risk of nonce reuse is near zero   This has many practical uses  One common usage mode is to allow values to be stored encrypted in a database  but with limited lookup query support  so that rows with the same value for a specific field can be returned from a query   To accommodate for any needed upgrades to the algorithm  different versions of convergent encryption have historically been supported     Version 1 required the client to provide their own nonce  which is highly   flexible but if done incorrectly can be dangerous  This was only in Vault   0 6 1  and keys using this version cannot be upgraded    Version 2 used an algorithmic approach to deriving the parameters  However    the algorithm used was susceptible to offline plaintext confirmation attacks    which could allow attackers to brute force decryption if the plaintext size   was small  Keys using version 2 can be upgraded by simply performing a rotate   operation to a new key version  existing values can then be rewrapped against   the new key version and will use the version 3 algorithm    Version 3 uses a different algorithm designed to be resistant to offline   plaintext confirmation attacks  It is similar to AES SIV in that it uses a   PRF to generate the nonce from the plaintext      Setup  Most secrets engines must be configured in advance before they can perform their functions  These steps are usually completed by an operator or configuration management tool   1  Enable the Transit secrets engine         text      vault secrets enable transit    Success  Enabled the transit secrets engine at  transit             By default  the secrets engine will mount at the name of the engine  To    enable the secrets engine at a different path  use the   path  argument   1  Create a named encryption key         text      vault write  f transit keys my key    Success  Data written to  transit keys my key            Usually each application has its own encryption key      Usage  After the secrets engine is configured and a user machine has a Vault token with the proper permission  it can use this secrets engine   1   Encrypt some plaintext data using the   encrypt  endpoint with a named key         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          text       vault write transit encrypt my key plaintext   echo  my secret data    base64       Key           Value                             ciphertext    vault v1 8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w                The returned ciphertext starts with  vault v1    The first prefix   vault       identifies that it has been wrapped by Vault  The  v1  indicates the key     version 1 was used to encrypt the plaintext  therefore  when you rotate     keys  Vault knows which version to use for decryption  The rest is a base64     concatenation of the initialization vector  IV  and ciphertext       Note that Vault does not  store  any of this data  The caller is responsible     for storing the encrypted ciphertext  When the caller wants the plaintext      it must provide the ciphertext back to Vault to decrypt the value          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   1   Decrypt a piece of data using the   decrypt  endpoint with a named key          text       vault write transit decrypt my key ciphertext vault v1 8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w        Key          Value                            plaintext    bXkgc2VjcmV0IGRhdGEK              The resulting data is base64 encoded  see the note above for details on     why   Decode it to get the raw plaintext          text       base64   decode      bXkgc2VjcmV0IGRhdGEK      my secret data              It is also possible to script this decryption using some clever shell     scripting in one command          text       vault write  field plaintext transit decrypt my key ciphertext       base64   decode     my secret data              Using ACLs  it is possible to restrict using the transit secrets engine such     that trusted operators can manage the named keys  and applications can only     encrypt or decrypt using the named keys they need access to   1   Rotate the underlying encryption key  This will generate a new encryption key     and add it to the keyring for the named key          text       vault write  f transit keys my key rotate     Success  Data written to  transit keys my key rotate              Future encryptions will use this new key  Old data can still be decrypted     due to the use of a key ring   1   Upgrade already encrypted data to a new key  Vault will decrypt the value     using the appropriate key in the keyring and then encrypt the resulting     plaintext with the newest key in the keyring          text       vault write transit rewrap my key ciphertext vault v1 8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w        Key           Value                             ciphertext    vault v2 0VHTTBb2EyyNYHsa3XiXsvXOQSLKulH NqS4eRZdtc2TwQCxqJ7PUipvqQ                This process   does not   reveal the plaintext data  As such  a Vault policy     could grant almost an untrusted process the ability to  rewrap  encrypted     data  since the process would not be able to get access to the plaintext     data      Bring your own key  BYOK        Note    Key import functionality supports cases in which there is a need to bring in an existing key from an HSM or other outside system  It is more secure to have Transit generate and manage a key within Vault       Via the Command Line  The Vault command line tool  includes a helper   vault docs commands transit   to perform the steps described in Manual below       Via the API  First  the wrapping key needs to be read from transit      text   vault read transit wrapping key      The wrapping key will be a 4096 bit RSA public key   Then the wrapping key is used to create the ciphertext input for the  import  endpoint  as described below  In the below  the target key refers to the key being imported       HSM  If the key is being imported from an HSM that supports PKCS 11  there are two possible scenarios     If the HSM supports the CKM RSA AES KEY WRAP mechanism  that can be used to wrap the   target key using the wrapping key     Otherwise  two mechanisms can be combined to wrap the target key  First  a 256 bit AES key should   be generated and then used to wrap the target key using the CKM AES KEY WRAP KWP mechanism    Then the AES key should be wrapped under the wrapping key using the CKM RSA PKCS OAEP mechanism   using MGF1 and either SHA 1  SHA 224  SHA 256  SHA 384  or SHA 512   The ciphertext is constructed by appending the wrapped target key to the wrapped AES key   The ciphertext bytes should be base64 encoded       Manual process  If the target key is not stored in an HSM or KMS  the following steps can be used to construct the ciphertext for the input of the  import  endpoint     Generate an ephemeral 256 bit AES key     Wrap the target key using the ephemeral AES key with AES KWP      Note  When wrapping a symmetric key  such as an AES or ChaCha20 key   wrap    the raw bytes of the key  For instance  with an AES 128 bit key  this ll be    a byte array 16 characters in length that will directly be wrapped without    base64 or other encodings  br    br   When wrapping an asymmetric key     such as a RSA or ECDSA key   wrap the   PKCS8   encoded format of this    key  in raw DER binary form  Do not apply PEM encoding to this blob prior    to encryption and do not base64 encode it     Wrap the AES key under the Vault wrapping key using RSAES OAEP with MGF1 and   either SHA 1  SHA 224  SHA 256  SHA 384  or SHA 512     Delete the ephemeral AES key     Append the wrapped target key to the wrapped AES key     Base64 encode the result   For more details about wrapping the key for import into transit  see the  key wrapping guide   vault docs secrets transit key wrapping guide       Tutorial  Refer to the  Encryption as a Service  Transit Secrets Engine   vault tutorials encryption as a service eaas transit  tutorial to learn how to use the transit secrets engine to handle cryptographic functions on data in transit      API  The Transit secrets engine has a full HTTP API  Please see the  Transit secrets engine API   vault api docs secret transit  for more details


vault page title Key Wrapping for Transit Key Import Transit Secrets Engines layout docs Details about wrapping keys for import into the transit secrets engine The bring your own key BYOK functionality for the transit Key wrapping for transit key import

Answer:
---
layout: docs
page_title: Key Wrapping for Transit Key Import - Transit - Secrets Engines
description: |-
  Details about wrapping keys for import into the transit secrets engine.
---

# Key wrapping for transit key import

The "bring your own key" (BYOK) functionality for the transit
secrets engine allows users to import keys that were generated
outside of Vault into the transit secrets engine.

This document describes the process for wrapping an externally-generated
key (the target key) for import into Vault. It describes the processes
for importing a software-stored key using Golang and for importing a key
that is stored in an HSM.

### Mount the secrets engine

```shell-session
$ vault secrets enable transit
Success! Enabled the transit secrets engine at: transit/
```

### Retrieve the transit wrapping key

```shell-session
$ vault read transit/wrapping_key
```

This returns a 4096-bit RSA key.

The steps after this depend on whether the key is stored using
a software solution or in an HSM.

### Software example (Go)

This example assumes that the key is stored in software using the
variable name `key`. It demonstrates how to wrap the target key using
Golang crypto libraries.

Once you have the wrapping key, you can parse it using the `encoding/pem`
and `crypto/x509` libraries (the example code below assumes that the wrapping
key has been written to a variable called `wrappingKeyString`):

```
keyBlock, _ := pem.Decode([]byte(wrappingKeyString))
parsedKey, err := x509.ParsePKIXPublicKey(keyBlock.Bytes)
if err != nil {
    return err
}
```

Then generate an ephemeral AES key for wrapping the target key.
This example uses Golang's `crypto/rand` library for generating the key:

```
ephemeralAESKey := make([]byte, 32)
_, err := rand.Read(ephemeralAESKey)
if err != nil {
        return err
}
```

~> **NOTE**: Be sure to securely delete the ephemeral AES key once it
has been used!

Google's [tink library](https://pkg.go.dev/github.com/google/tink/go@v1.6.1/kwp/subtle)
provides a function for performing the key wrap operation:

```
wrapKWP, err := subtle.NewKWP(aesKey)
if err != nil {
        return err
}
wrappedTargetKey, err := wrapKWP.Wrap(key)
if err != nil {
        return err
}
```

Then encrypt the ephemeral AES key using the transit wrapping key:

```
wrappedAESKey, err := rsa.EncryptOAEP(
        sha256.New(),
        rand.Reader,
        wrappingKey,
        ephemeralAESKey,
        []byte{},
)
if err != nil {
        return err
}
```

Note that though this example uses SHA256, Vault also supports the use of
SHA1, SHA384, or SHA512. The hash function that was used at this step will
need to be provided as a parameter when importing the key.

Finally, concatenate the wrapped keys into a single byte string.
The leftmost 4096 bits of the string should be the wrapped AES key, and
the remaining bits should be the wrapped target key. Then the resulting
bytes should be base64-encoded.

```
combinedCiphertext := append(wrappedAESKey, wrappedTargetKey...)
base64Ciphertext := base64.StdEncoding.EncodeToString(combinedCiphertext)
```

This is the ciphertext that should be provided to Vault when importing a
key into the transit secrets engine.

```shell-session
$ vault write transit/keys/test-key/import ciphertext=$CIPHERTEXT hash_function=SHA256 type=$KEY_TYPE
```

### AWS CloudHSM example

This example demonstrates how to import a key into the transit secrets engine from
an AWS CloudHSM cluster. The process and mechanisms used will apply to importing
a key from an HSM in general, but the details will differ between HSMs.

For information on creating and communicating with an AWS CloudHSM cluster, see
the [Getting Started guide in the AWS CloudHSM documentation](https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html).

Communication with the HSM uses AWS's `key_mgmt_util` tool. For help setting that
up, see the [Getting Started page for key_mgmt_util](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-getting-started.html).

The first step is writing the transit wrapping key to the HSM. This involves
creating a new RSA public key object with the key returned by transit's
`wrapping_key` endpoint.

```shell-session
$ importPubKey -f wrapping_key.pem -l "vault-transit-wrapping-key"
```

This will create the public key in the HSM with all of the necessary permissions.
If you're using a different tool, make sure that the usage for the wrapping key
includes the attribute `CKA_WRAP`.

The next step is wrapping the target key using the wrapping key. If the
ID of the target key is `1` and the wrapping key is `2`, the command looks like this:

```shell-session
$ wrapKey -noheader -k 1 -w 2 -t 3 -m 7 -out ciphertext.key
```

The `-m 7` flag specifies the mechanism to use for the key wrapping. For AWS CloudHSM,
7 corresponds to the PKCS11 mechanism `CKM_AES_RSA_KEY_WRAP` ([see the AWS documentation for details](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-wrapKey.html)).
The `-t 3` flag specifies `SHA256` as the hash function. The result is written to a
file called `ciphertext.key`. The `noheader` flag ensures that the ciphertext does
not include an AWS-specific header.

The output from this is a binary file, which needs to be base64-encoded when it
is provided to Vault.

```shell-session
$ export CIPHERTEXT=$(base64 ciphertext.key)
$ vault write transit/keys/test-key/import ciphertext=$CIPHERTEXT hash_function=SHA256 type=$KEY_TYPE
```

Once the key has been imported, it can be used like any other transit key.

layout  docs page title  Key Wrapping for Transit Key Import   Transit   Secrets Engines description       Details about wrapping keys for import into the transit secrets engine         Key wrapping for transit key import  The  bring your own key   BYOK  functionality for the transit secrets engine allows users to import keys that were generated outside of Vault into the transit secrets engine   This document describes the process for wrapping an externally generated key  the target key  for import into Vault  It describes the processes for importing a software stored key using Golang and for importing a key that is stored in an HSM       Mount the secrets engine     shell session   vault secrets enable transit Success  Enabled the transit secrets engine at  transit           Retrieve the transit wrapping key     shell session   vault read transit wrapping key      This returns a 4096 bit RSA key   The steps after this depend on whether the key is stored using a software solution or in an HSM       Software example  Go   This example assumes that the key is stored in software using the variable name  key   It demonstrates how to wrap the target key using Golang crypto libraries   Once you have the wrapping key  you can parse it using the  encoding pem  and  crypto x509  libraries  the example code below assumes that the wrapping key has been written to a variable called  wrappingKeyString         keyBlock       pem Decode   byte wrappingKeyString   parsedKey  err    x509 ParsePKIXPublicKey keyBlock Bytes  if err    nil       return err        Then generate an ephemeral AES key for wrapping the target key  This example uses Golang s  crypto rand  library for generating the key       ephemeralAESKey    make   byte  32     err    rand Read ephemeralAESKey  if err    nil           return err             NOTE    Be sure to securely delete the ephemeral AES key once it has been used   Google s  tink library  https   pkg go dev github com google tink go v1 6 1 kwp subtle  provides a function for performing the key wrap operation       wrapKWP  err    subtle NewKWP aesKey  if err    nil           return err   wrappedTargetKey  err    wrapKWP Wrap key  if err    nil           return err        Then encrypt the ephemeral AES key using the transit wrapping key       wrappedAESKey  err    rsa EncryptOAEP          sha256 New            rand Reader          wrappingKey          ephemeralAESKey            byte      if err    nil           return err        Note that though this example uses SHA256  Vault also supports the use of SHA1  SHA384  or SHA512  The hash function that was used at this step will need to be provided as a parameter when importing the key   Finally  concatenate the wrapped keys into a single byte string  The leftmost 4096 bits of the string should be the wrapped AES key  and the remaining bits should be the wrapped target key  Then the resulting bytes should be base64 encoded       combinedCiphertext    append wrappedAESKey  wrappedTargetKey     base64Ciphertext    base64 StdEncoding EncodeToString combinedCiphertext       This is the ciphertext that should be provided to Vault when importing a key into the transit secrets engine      shell session   vault write transit keys test key import ciphertext  CIPHERTEXT hash function SHA256 type  KEY TYPE           AWS CloudHSM example  This example demonstrates how to import a key into the transit secrets engine from an AWS CloudHSM cluster  The process and mechanisms used will apply to importing a key from an HSM in general  but the details will differ between HSMs   For information on creating and communicating with an AWS CloudHSM cluster  see the  Getting Started guide in the AWS CloudHSM documentation  https   docs aws amazon com cloudhsm latest userguide getting started html    Communication with the HSM uses AWS s  key mgmt util  tool  For help setting that up  see the  Getting Started page for key mgmt util  https   docs aws amazon com cloudhsm latest userguide key mgmt util getting started html    The first step is writing the transit wrapping key to the HSM  This involves creating a new RSA public key object with the key returned by transit s  wrapping key  endpoint      shell session   importPubKey  f wrapping key pem  l  vault transit wrapping key       This will create the public key in the HSM with all of the necessary permissions  If you re using a different tool  make sure that the usage for the wrapping key includes the attribute  CKA WRAP    The next step is wrapping the target key using the wrapping key  If the ID of the target key is  1  and the wrapping key is  2   the command looks like this      shell session   wrapKey  noheader  k 1  w 2  t 3  m 7  out ciphertext key      The   m 7  flag specifies the mechanism to use for the key wrapping  For AWS CloudHSM  7 corresponds to the PKCS11 mechanism  CKM AES RSA KEY WRAP    see the AWS documentation for details  https   docs aws amazon com cloudhsm latest userguide key mgmt util wrapKey html    The   t 3  flag specifies  SHA256  as the hash function  The result is written to a file called  ciphertext key   The  noheader  flag ensures that the ciphertext does not include an AWS specific header   The output from this is a binary file  which needs to be base64 encoded when it is provided to Vault      shell session   export CIPHERTEXT   base64 ciphertext key    vault write transit keys test key import ciphertext  CIPHERTEXT hash function SHA256 type  KEY TYPE      Once the key has been imported  it can be used like any other transit key


vault management of cryptographic keys in various key management service KMS providers page title Key Management Secrets Engines Key management secrets engine The key management secrets engine provides a consistent workflow for distribution and lifecycle layout docs

Answer:
---
layout: docs
page_title: Key Management - Secrets Engines
description: >-
  The key management secrets engine provides a consistent workflow for distribution and lifecycle
  management of cryptographic keys in various key management service (KMS) providers.
---

# Key management secrets engine

@include 'alerts/enterprise-and-hcp.mdx'

Key management secrets engine requires [Vault
Enterprise](https://www.hashicorp.com/products/vault/pricing) with the Advanced Data
Protection (ADP) module.

The key management secrets engine provides a consistent workflow for distribution and lifecycle
management of cryptographic keys in various key management service (KMS) providers. It allows
organizations to maintain centralized control of their keys in Vault while still taking advantage
of cryptographic capabilities native to the KMS providers.

The secrets engine generates and owns original copies of key material. When an operator decides
to distribute and manage the lifecycle of a key in one of the [supported KMS providers](#kms-providers),
a copy of the key material is distributed. This provides additional durability and disaster
recovery means for the complete lifecycle of the key in the KMS provider.

Key material will always be securely transferred in accordance with the
[key import specification](#kms-providers) of the supported KMS providers.

## Setup

Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.

1. Enable the key management secrets engine:

   ```shell-session
   $ vault secrets enable keymgmt
   Success! Enabled the keymgmt secrets engine at: keymgmt/
   ```

   By default, the secrets engine will mount at the name of the engine. To enable
   the secrets engine at a different path, use the `-path` argument.

## Usage

After the secrets engine is mounted and a user/machine has a Vault token with
the proper permission, it can use this secrets engine to generate, distribute, and
manage the lifecycle of cryptographic keys in [supported KMS providers](#kms-providers).

1. Create a named cryptographic key of a specified type:

   ```shell-session
   $ vault write -f keymgmt/key/example-key type="rsa-2048"
   Success! Data written to: keymgmt/key/example-key
   ```

   Keys created by the secrets engine are considered general-purpose until
   they're distributed to a KMS provider.

1. Configure a KMS provider:

   ```shell-session
   $ vault write keymgmt/kms/example-kms \
       provider="azurekeyvault" \
       key_collection="keyvault-name" \
       credentials=client_id="a0454cd1-e28e-405e-bc50-7477fa8a00b7" \
       credentials=client_secret="eR%HizuCVEpAKgeaUEx" \
       credentials=tenant_id="cd4bf224-d114-4f96-9bbc-b8f45751c43f"
   ```

   Conceptually, a KMS provider resource represents a destination for keys to be distributed to
   and subsequently managed in. It is configured using a generic set of parameters. The values
   supplied to the generic set of parameters will differ depending on the specified `provider`.

   This operation creates a KMS provider that represents a named Azure Key Vault instance.
   This is accomplished by specifying the `azurekeyvault` provider along with other provider-specific
   parameter values. For details on how to configure each supported KMS provider, see the
   [KMS Providers](#kms-providers) section.

1. Distribute a key to a KMS provider:

   ```shell-session
   $ vault write keymgmt/kms/example-kms/key/example-key \
       purpose="encrypt,decrypt" \
       protection="hsm"
   ```

   This operation distributes a **copy** of the named key to the KMS provider with a specific
   `purpose` and `protection`. The `purpose` defines the set of cryptographic capabilities
   that the key will have in the KMS provider. The `protection` defines where cryptographic
   operations are performed with the key in the KMS provider. See the API documentation for a list of
   supported [purpose](/vault/api-docs/secret/key-management#purpose) and [protection](/vault/api-docs/secret/key-management#protection)
   values.

   ~> **Note:** The amount of time it takes to distribute a key to a KMS provider is proportional to the
   number of versions that the key has. If a timeout occurs when distributing a key to a KMS
   provider, you may need to increase the [VAULT_CLIENT_TIMEOUT](/vault/docs/commands#vault_client_timeout).

1. Rotate a key:

   ```shell-session
   $ vault write -f keymgmt/key/example-key/rotate
   ```

   Rotating a key creates a new key version that contains new key material. The key will be rotated
   in both Vault and the KMS provider that the key has been distributed to. The new key version
   will be enabled and set as the current version for cryptographic operations in the KMS provider.

1. Enable or disable key versions:

   ```shell-session
   $ vault write keymgmt/key/example-key min_enabled_version=2
   ```

   The `min_enabled_version` of a key can be updated in order to enable or disable sequences of
   key versions. All versions of the key less than the `min_enabled_version` will be disabled for
   cryptographic operations in the KMS provider that the key has been distributed to. Setting a
   `min_enabled_version` of `0` means that all key versions will be enabled.

1. Remove a key from a KMS provider:

   ```shell-session
   $ vault delete keymgmt/kms/example-kms/key/example-key
   ```

   This operation results in the key being deleted from the KMS provider. The key will still exist
   in the secrets engine and can be redistributed to a KMS provider at a later time.

   To permanently delete the key from the secrets engine, the [delete key](/vault/api-docs/secret/key-management#delete-key)
   API may be invoked.

## Key types

The key management secrets engine supports generation of the following key types:

- `aes256-gcm96` - AES-GCM with a 256-bit AES key and a 96-bit nonce (symmetric)
- `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)
- `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)

## KMS providers

The key management secrets engine supports lifecycle management of keys in the following
KMS providers:

- [Azure Key Vault](/vault/docs/secrets/key-management/azurekeyvault)
- [AWS KMS](/vault/docs/secrets/key-management/awskms)
- [GCP Cloud KMS](/vault/docs/secrets/key-management/gcpkms)

Refer to the provider-specific documentation for details on how to properly configure each provider.

## Compatibility

The following table defines which key types are compatible with each KMS provider.

| Key Type       | Azure Key Vault | AWS KMS | GCP Cloud KMS |
| -------------- | --------------- | ------- | ------------- |
| `aes256-gcm96` | No              | **Yes** | **Yes**       |
| `rsa-2048`     | **Yes**         | No      | **Yes**       |
| `rsa-3072`     | **Yes**         | No      | **Yes**       |
| `rsa-4096`     | **Yes**         | No      | **Yes**       |
| `ecdsa-p256`   | No              | No      | **Yes**       |
| `ecdsa-p384`   | No              | No      | **Yes**       |
| `ecdsa-p521`   | No              | No      | No            |

## API

The key management secrets engine has a full HTTP API. Please see the
[Key Management Secrets Engine API](/vault/api-docs/secret/key-management) for more
details.

layout  docs page title  Key Management   Secrets Engines description       The key management secrets engine provides a consistent workflow for distribution and lifecycle   management of cryptographic keys in various key management service  KMS  providers         Key management secrets engine   include  alerts enterprise and hcp mdx   Key management secrets engine requires  Vault Enterprise  https   www hashicorp com products vault pricing  with the Advanced Data Protection  ADP  module   The key management secrets engine provides a consistent workflow for distribution and lifecycle management of cryptographic keys in various key management service  KMS  providers  It allows organizations to maintain centralized control of their keys in Vault while still taking advantage of cryptographic capabilities native to the KMS providers   The secrets engine generates and owns original copies of key material  When an operator decides to distribute and manage the lifecycle of a key in one of the  supported KMS providers   kms providers   a copy of the key material is distributed  This provides additional durability and disaster recovery means for the complete lifecycle of the key in the KMS provider   Key material will always be securely transferred in accordance with the  key import specification   kms providers  of the supported KMS providers      Setup  Most secrets engines must be configured in advance before they can perform their functions  These steps are usually completed by an operator or configuration management tool   1  Enable the key management secrets engine         shell session      vault secrets enable keymgmt    Success  Enabled the keymgmt secrets engine at  keymgmt             By default  the secrets engine will mount at the name of the engine  To enable    the secrets engine at a different path  use the   path  argument      Usage  After the secrets engine is mounted and a user machine has a Vault token with the proper permission  it can use this secrets engine to generate  distribute  and manage the lifecycle of cryptographic keys in  supported KMS providers   kms providers    1  Create a named cryptographic key of a specified type         shell session      vault write  f keymgmt key example key type  rsa 2048     Success  Data written to  keymgmt key example key            Keys created by the secrets engine are considered general purpose until    they re distributed to a KMS provider   1  Configure a KMS provider         shell session      vault write keymgmt kms example kms          provider  azurekeyvault           key collection  keyvault name           credentials client id  a0454cd1 e28e 405e bc50 7477fa8a00b7           credentials client secret  eR HizuCVEpAKgeaUEx           credentials tenant id  cd4bf224 d114 4f96 9bbc b8f45751c43f             Conceptually  a KMS provider resource represents a destination for keys to be distributed to    and subsequently managed in  It is configured using a generic set of parameters  The values    supplied to the generic set of parameters will differ depending on the specified  provider       This operation creates a KMS provider that represents a named Azure Key Vault instance     This is accomplished by specifying the  azurekeyvault  provider along with other provider specific    parameter values  For details on how to configure each supported KMS provider  see the     KMS Providers   kms providers  section   1  Distribute a key to a KMS provider         shell session      vault write keymgmt kms example kms key example key          purpose  encrypt decrypt           protection  hsm             This operation distributes a   copy   of the named key to the KMS provider with a specific     purpose  and  protection   The  purpose  defines the set of cryptographic capabilities    that the key will have in the KMS provider  The  protection  defines where cryptographic    operations are performed with the key in the KMS provider  See the API documentation for a list of    supported  purpose   vault api docs secret key management purpose  and  protection   vault api docs secret key management protection     values           Note    The amount of time it takes to distribute a key to a KMS provider is proportional to the    number of versions that the key has  If a timeout occurs when distributing a key to a KMS    provider  you may need to increase the  VAULT CLIENT TIMEOUT   vault docs commands vault client timeout    1  Rotate a key         shell session      vault write  f keymgmt key example key rotate            Rotating a key creates a new key version that contains new key material  The key will be rotated    in both Vault and the KMS provider that the key has been distributed to  The new key version    will be enabled and set as the current version for cryptographic operations in the KMS provider   1  Enable or disable key versions         shell session      vault write keymgmt key example key min enabled version 2            The  min enabled version  of a key can be updated in order to enable or disable sequences of    key versions  All versions of the key less than the  min enabled version  will be disabled for    cryptographic operations in the KMS provider that the key has been distributed to  Setting a     min enabled version  of  0  means that all key versions will be enabled   1  Remove a key from a KMS provider         shell session      vault delete keymgmt kms example kms key example key            This operation results in the key being deleted from the KMS provider  The key will still exist    in the secrets engine and can be redistributed to a KMS provider at a later time      To permanently delete the key from the secrets engine  the  delete key   vault api docs secret key management delete key     API may be invoked      Key types  The key management secrets engine supports generation of the following key types      aes256 gcm96    AES GCM with a 256 bit AES key and a 96 bit nonce  symmetric     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     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      KMS providers  The key management secrets engine supports lifecycle management of keys in the following KMS providers      Azure Key Vault   vault docs secrets key management azurekeyvault     AWS KMS   vault docs secrets key management awskms     GCP Cloud KMS   vault docs secrets key management gcpkms   Refer to the provider specific documentation for details on how to properly configure each provider      Compatibility  The following table defines which key types are compatible with each KMS provider     Key Type         Azure Key Vault   AWS KMS   GCP Cloud KMS                                                                     aes256 gcm96    No                  Yes       Yes              rsa 2048          Yes             No          Yes              rsa 3072          Yes             No          Yes              rsa 4096          Yes             No          Yes              ecdsa p256      No                No          Yes              ecdsa p384      No                No          Yes              ecdsa p521      No                No        No                  API  The key management secrets engine has a full HTTP API  Please see the  Key Management Secrets Engine API   vault api docs secret key management  for more details


vault key management secrets engine using azurekeyvault provider Configure the key management secrets engine and distribute the Vault managed keys to the target Azure Key Vault instance To manage the lifecycle of the Azure Key Vault keys you need to setup the page title Azure Key Vault setup guide layout docs Setup guide Azure Key Vault

Answer:
---
layout: docs
page_title: Azure Key Vault setup guide
description: Configure the key management secrets engine, and distribute the Vault-managed keys to the target Azure Key Vault instance.
---

# Setup guide - Azure Key Vault

To manage the lifecycle of the Azure Key Vault keys, you need to setup the
key management secrets engine using `azurekeyvault` provider.

## Setup

1. Enable the key management secrets engine.

    ```shell-session
    $ vault secrets enable keymgmt
    Success! Enabled the keymgmt secrets engine at: keymgmt/
    ```

1. Configure a KMS provider resource named, `example-kms`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms \
        provider="azurekeyvault" \
        key_collection="keyvault-name" \
        credentials=client_id="a0454cd1-e28e-405e-bc50-7477fa8a00b7" \
        credentials=client_secret="eR%HizuCVEpAKgeaUEx" \
        credentials=tenant_id="cd4bf224-d114-4f96-9bbc-b8f45751c43f"
    ```

    The command specified the following:

    - The full path to this KMS provider instance in Vault
      (`keymgmt/kms/example-kms`).
    - A key collection, which corresponds to the name of the key vault instance
      in Azure.
    - The KMS provider is set to `azurekeyvault`.
    - Azure client ID credential, that can also be specified with
      `AZURE_CLIENT_ID` environment variable.
    - Azure client secret credential, that can also be specified with
      `AZURE_CLIENT_SECRET `environment variable.
    - Azure tenant ID credential, that can also be specified with
      `AZURE_TENANT_ID` environment variable.

<Tip title="API documentation">

Refer to the Azure Key Vault [API
documentation](/vault/api-docs/secret/key-management/azurekeyvault) for a
detailed description of individual configuration parameters.

</Tip>

## Usage

1. Write a pair of RSA-2048 keys to the secrets engine. The following command
   will write a new key of type **rsa-2048** to the path `keymgmt/key/rsa-1`.

    ```shell-session
    $ vault write keymgmt/key/rsa-1 type="rsa-2048"
    Success! Data written to: keymgmt/key/rsa-1
    ```

    The key management secrets engine currently supports generation of the key
    types specified in [Key
    Types](/vault/docs/secrets/key-management#key-types).

    Based on the
    [Compatibility](/vault/docs/secrets/key-management#compatibility) section of
    the documentation, Azure Key Vault currently supports use of RSA-2048,
    RSA-3072, and RSA-4096 key types.

1. Read the **rsa-1** key you created. Use JSON as the output and pipe that into
   `jq`.

    ```shell-session
    $ vault read -format=json keymgmt/key/rsa-1 | jq
    ```

1. To use the keys you wrote, you must distribute them to the key vault.
   Distribute the **rsa-1** key to the key vault at the path
   `keymgmt/kms/example-kms/key/rsa-1`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms/key/rsa-1 \
        purpose="encrypt,decrypt" \
        protection="hsm"
    ```

    Here you are instructing Vault to distribute the key and specify that its
    purpose is only to encrypt and decrypt. The protection type is dependent on
    the cloud provider and the value is either `hsm` or `software`. In the case
    of Azure, you specify `hsm` for the protection type. The key will be
    securely delivered to the key vault instance according to the [Azure Bring
    Your Own
    Key](https://docs.microsoft.com/en-us/azure/key-vault/keys/byok-specification)
    (BYOK) specification.

1. You can list the keys that have been distributed to the Azure Key Vault instance.

    ```shell-session
    $ vault list keymgmt/kms/keyvault/key/
    Keys
    ----
    rsa-1
    ```

1. Rotate the rsa-1 key.

    ```shell-session
    $ vault write -f keymgmt/key/rsa-1/rotate
    Success! Data written to: keymgmt/key/rsa-1/rotate
    ```

1. Confirm successful key rotation by reading the key, and getting the value of
   `.data.latest_version`.

    ```shell-session
    $  vault read -format=json keymgmt/key/rsa-1 | jq '.data.latest_version'
    2
    ```

## Azure private link

The secrets engine can be configured to communicate with Azure Key Vault
instances using [Azure Private
Endpoints](https://docs.microsoft.com/en-us/azure/private-link/private-endpoint-overview).
Follow the guide at [Integrate Key Vault with Azure Private
Link](https://docs.microsoft.com/en-us/azure/key-vault/general/private-link-service?tabs=portal)
to set up a Private Endpoint for your target Key Vault instance in Azure. The
Private Endpoint must be network reachable by Vault. This means Vault needs to
be running in the same virtual network or a peered virtual network to properly
resolve the Key Vault domain name to the Private Endpoint IP address.

The Private Endpoint configuration relies on a correct [Azure Private
DNS](https://docs.microsoft.com/en-us/azure/dns/private-dns-overview)
integration. From the host that Vault is running on, follow the steps in
[Validate that the private link connection
works](https://docs.microsoft.com/en-us/azure/key-vault/general/private-link-service?tabs=portal#validate-that-the-private-link-connection-works)
to ensure that the Key Vault domain name resolves to the Private Endpoint IP
address you've configured.

```shell-session
$ nslookup <keyvault-name>.vault.azure.net

Non-authoritative answer:
Name:
Address:  10.0.2.5 (private IP address)
Aliases:  <keyvault-name>.vault.azure.net
          <keyvault-name>.privatelink.vaultcore.azure.net
```

The secrets engine doesn't require special configuration to communicate with a
Key Vault instance over an Azure Private Endpoint. For example, the given [KMS
configuration](/vault/docs/secrets/key-management/azurekeyvault#configuration)
will result in the secrets engine resolving a Key Vault domain name of
`keyvault-name.vault.azure.net` to the Private Endpoint IP address. Note that
it's possible to change the Key Vault DNS suffix using the
[environment](/vault/api-docs/secret/key-management/azurekeyvault#environment)
configuration parameter or `AZURE_ENVIRONMENT` environment variable.

## Terraform example

If you are familiar with [Terraform](/terraform/), you can use it to deploy the
necessary Azure infrastructure.

```hcl
provider "azuread" {
  version = "=0.11.0"
}

provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy = true
    }
  }
}

resource "random_id" "app_rg_name" {
  byte_length = 3
}

resource "random_id" "keyvault_name" {
  byte_length = 3
}

data "azurerm_client_config" "current" {}

resource "azuread_application" "key_vault_app" {
  name                       = "app-${random_id.app_rg_name.hex}"
  homepage                   = "http://homepage${random_id.app_rg_name.b64_url}"
  identifier_uris            = ["http://uri${random_id.app_rg_name.b64_url}"]
  reply_urls                 = ["http://replyur${random_id.app_rg_name.b64_url}"]
  available_to_other_tenants = false
  oauth2_allow_implicit_flow = true
}

resource "azuread_service_principal" "key_vault_sp" {
  application_id               = azuread_application.key_vault_app.application_id
  app_role_assignment_required = false
}

resource "random_password" "password" {
  length           = 24
  special          = true
  override_special = "%@"
}

resource "azuread_service_principal_password" "key_vault_sp_pwd" {
  service_principal_id = azuread_service_principal.key_vault_sp.id
  value                = random_password.password.result
  end_date             = "2099-01-01T01:02:03Z"
}

resource "azurerm_resource_group" "key_vault_rg" {
  name     = "learn-rg-${random_id.app_rg_name.hex}"
  location = "West US"
}

resource "azurerm_key_vault" "key_vault_kv" {
  name                = "learn-keyvault-${random_id.keyvault_name.hex}"
  location            = azurerm_resource_group.key_vault_rg.location
  resource_group_name = azurerm_resource_group.key_vault_rg.name
  sku_name            = "premium"
  soft_delete_enabled = true
  tenant_id           = data.azurerm_client_config.current.tenant_id

  access_policy {
    tenant_id = data.azurerm_client_config.current.tenant_id
    object_id = data.azurerm_client_config.current.object_id
    key_permissions = [
      "backup",
      "create",
      "decrypt",
      "delete",
      "encrypt",
      "get",
      "import",
      "list",
      "purge",
      "recover",
      "restore",
      "sign",
      "unwrapKey",
      "update",
      "verify",
      "wrapKey"
    ]
  }

  access_policy {
    tenant_id = data.azurerm_client_config.current.tenant_id
    object_id = azuread_service_principal.key_vault_sp.object_id
    key_permissions = [
      "create",
      "delete",
      "get",
      "import",
      "update"
    ]
  }
}

output "key_vault_1_name" {
  value = azurerm_key_vault.key_vault_kv.name
}

output "tenant_id" {
  value = data.azurerm_client_config.current.tenant_id
}

output "client_id" {
  value = azuread_application.key_vault_app.application_id
}

output "client_secret" {
  value = azuread_service_principal_password.key_vault_sp_pwd.value
}
```

layout  docs page title  Azure Key Vault setup guide description  Configure the key management secrets engine  and distribute the Vault managed keys to the target Azure Key Vault instance         Setup guide   Azure Key Vault  To manage the lifecycle of the Azure Key Vault keys  you need to setup the key management secrets engine using  azurekeyvault  provider      Setup  1  Enable the key management secrets engine          shell session       vault secrets enable keymgmt     Success  Enabled the keymgmt secrets engine at  keymgmt           1  Configure a KMS provider resource named   example kms           shell session       vault write keymgmt kms example kms           provider  azurekeyvault            key collection  keyvault name            credentials client id  a0454cd1 e28e 405e bc50 7477fa8a00b7            credentials client secret  eR HizuCVEpAKgeaUEx            credentials tenant id  cd4bf224 d114 4f96 9bbc b8f45751c43f               The command specified the following         The full path to this KMS provider instance in Vault         keymgmt kms example kms          A key collection  which corresponds to the name of the key vault instance       in Azure        The KMS provider is set to  azurekeyvault         Azure client ID credential  that can also be specified with        AZURE CLIENT ID  environment variable        Azure client secret credential  that can also be specified with        AZURE CLIENT SECRET  environment variable        Azure tenant ID credential  that can also be specified with        AZURE TENANT ID  environment variable    Tip title  API documentation    Refer to the Azure Key Vault  API documentation   vault api docs secret key management azurekeyvault  for a detailed description of individual configuration parameters     Tip      Usage   1  Write a pair of RSA 2048 keys to the secrets engine  The following command    will write a new key of type   rsa 2048   to the path  keymgmt key rsa 1            shell session       vault write keymgmt key rsa 1 type  rsa 2048      Success  Data written to  keymgmt key rsa 1              The key management secrets engine currently supports generation of the key     types specified in  Key     Types   vault docs secrets key management key types        Based on the      Compatibility   vault docs secrets key management compatibility  section of     the documentation  Azure Key Vault currently supports use of RSA 2048      RSA 3072  and RSA 4096 key types   1  Read the   rsa 1   key you created  Use JSON as the output and pipe that into     jq           shell session       vault read  format json keymgmt key rsa 1   jq          1  To use the keys you wrote  you must distribute them to the key vault     Distribute the   rsa 1   key to the key vault at the path     keymgmt kms example kms key rsa 1           shell session       vault write keymgmt kms example kms key rsa 1           purpose  encrypt decrypt            protection  hsm               Here you are instructing Vault to distribute the key and specify that its     purpose is only to encrypt and decrypt  The protection type is dependent on     the cloud provider and the value is either  hsm  or  software   In the case     of Azure  you specify  hsm  for the protection type  The key will be     securely delivered to the key vault instance according to the  Azure Bring     Your Own     Key  https   docs microsoft com en us azure key vault keys byok specification       BYOK  specification   1  You can list the keys that have been distributed to the Azure Key Vault instance          shell session       vault list keymgmt kms keyvault key      Keys              rsa 1          1  Rotate the rsa 1 key          shell session       vault write  f keymgmt key rsa 1 rotate     Success  Data written to  keymgmt key rsa 1 rotate          1  Confirm successful key rotation by reading the key  and getting the value of      data latest version           shell session        vault read  format json keymgmt key rsa 1   jq   data latest version      2             Azure private link  The secrets engine can be configured to communicate with Azure Key Vault instances using  Azure Private Endpoints  https   docs microsoft com en us azure private link private endpoint overview   Follow the guide at  Integrate Key Vault with Azure Private Link  https   docs microsoft com en us azure key vault general private link service tabs portal  to set up a Private Endpoint for your target Key Vault instance in Azure  The Private Endpoint must be network reachable by Vault  This means Vault needs to be running in the same virtual network or a peered virtual network to properly resolve the Key Vault domain name to the Private Endpoint IP address   The Private Endpoint configuration relies on a correct  Azure Private DNS  https   docs microsoft com en us azure dns private dns overview  integration  From the host that Vault is running on  follow the steps in  Validate that the private link connection works  https   docs microsoft com en us azure key vault general private link service tabs portal validate that the private link connection works  to ensure that the Key Vault domain name resolves to the Private Endpoint IP address you ve configured      shell session   nslookup  keyvault name  vault azure net  Non authoritative answer  Name  Address   10 0 2 5  private IP address  Aliases    keyvault name  vault azure net            keyvault name  privatelink vaultcore azure net      The secrets engine doesn t require special configuration to communicate with a Key Vault instance over an Azure Private Endpoint  For example  the given  KMS configuration   vault docs secrets key management azurekeyvault configuration  will result in the secrets engine resolving a Key Vault domain name of  keyvault name vault azure net  to the Private Endpoint IP address  Note that it s possible to change the Key Vault DNS suffix using the  environment   vault api docs secret key management azurekeyvault environment  configuration parameter or  AZURE ENVIRONMENT  environment variable       Terraform example   If you are familiar with  Terraform   terraform    you can use it to deploy the necessary Azure infrastructure      hcl provider  azuread      version     0 11 0     provider  azurerm      features       key vault         purge soft delete on destroy   true              resource  random id   app rg name      byte length   3    resource  random id   keyvault name      byte length   3    data  azurerm client config   current      resource  azuread application   key vault app      name                          app   random id app rg name hex     homepage                      http   homepage  random id app rg name b64 url     identifier uris                http   uri  random id app rg name b64 url      reply urls                     http   replyur  random id app rg name b64 url      available to other tenants   false   oauth2 allow implicit flow   true    resource  azuread service principal   key vault sp      application id                 azuread application key vault app application id   app role assignment required   false    resource  random password   password      length             24   special            true   override special           resource  azuread service principal password   key vault sp pwd      service principal id   azuread service principal key vault sp id   value                  random password password result   end date                2099 01 01T01 02 03Z     resource  azurerm resource group   key vault rg      name        learn rg   random id app rg name hex     location    West US     resource  azurerm key vault   key vault kv      name                   learn keyvault   random id keyvault name hex     location              azurerm resource group key vault rg location   resource group name   azurerm resource group key vault rg name   sku name               premium    soft delete enabled   true   tenant id             data azurerm client config current tenant id    access policy       tenant id   data azurerm client config current tenant id     object id   data azurerm client config current object id     key permissions            backup          create          decrypt          delete          encrypt          get          import          list          purge          recover          restore          sign          unwrapKey          update          verify          wrapKey               access policy       tenant id   data azurerm client config current tenant id     object id   azuread service principal key vault sp object id     key permissions            create          delete          get          import          update               output  key vault 1 name      value   azurerm key vault key vault kv name    output  tenant id      value   data azurerm client config current tenant id    output  client id      value   azuread application key vault app application id    output  client secret      value   azuread service principal password key vault sp pwd value


vault To manage the lifecycle of the GCP Cloud KMS key rings you need to setup the Setup guide GCP Cloud KMS Configure the key management secrets engine and distribute the Vault managed keys to the target GCP Cloud KMS page title GCP Cloud KMS Key Management Secrets Engines layout docs key management secrets engine using gcpckms provider

Answer:
---
layout: docs
page_title: GCP Cloud KMS - Key Management - Secrets Engines
description: Configure the key management secrets engine, and distribute the Vault-managed keys to the target GCP Cloud KMS.
---

# Setup guide - GCP Cloud KMS

To manage the lifecycle of the GCP Cloud KMS key rings, you need to setup the
key management secrets engine using `gcpckms` provider.

## Setup

1. Enable the key management secrets engine.

    ```shell-session
    $ vault secrets enable keymgmt
    ```

1. Configure the KMS provider resource named, `example-kms`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms \
        provider="gcpckms" \
        key_collection="projects/<project-id>/locations/<location>/keyRings/<keyring>" \
        credentials=service_account_file="/path/to/service_account/credentials.json"
    ```

    The command specified the following:

    - The full path to this KMS provider instance in Vault
      (`keymgmt/kms/example-kms`).
    - The KMS provider type is set to `gcpckms`.
    - A key collection, which refers to the [resource
      ID](https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id)
      of an existing GCP Cloud KMS key ring; this value cannot be changed after
      creation.
    - Credentials file to use for authentication with GCP Cloud KMS. Supplying
      values for this parameter is optional, as credentials may also be
      specified as the `GOOGLE_CREDENTIALS` environment variable or default
      application credentials.

<Tip title="API documentation">

Refer to the GCP Cloud KMS [API
documentation](/vault/api-docs/secret/key-management/gcpkms) for a detailed
description of individual configuration parameters.

</Tip>

## Usage

1. Write a new key of type **aes256-gcm96** to the path `keymgmt/key/aes256-gcm96`.

    ```shell-session
    $ vault write keymgmt/key/aes256-gcm96 type="aes256-gcm96"
    ```

1. Read the **aes256-gcm96** key, use JSON as the output, and pipe that into `jq`.

    ```shell-session
    $ vault read -format=json keymgmt/key/aes256-gcm96 | jq
    ```

    **Example output:**

    <CodeBlockConfig hideClipboard>

    ```json
    {
        "request_id": "631f98de-b755-9863-40db-f789ff9ff10a",
        "lease_id": "",
        "lease_duration": 0,
        "renewable": false,
        "data": {
            "deletion_allowed": false,
            "latest_version": 1,
            "min_enabled_version": 1,
            "name": "aes256-gcm96",
            "type": "aes256-gcm96",
            "versions": {
            "1": {
                "creation_time": "2021-11-16T13:07:17.878864-05:00"
            }
            }
        },
        "warnings": null
    }
    ```

    </CodeBlockConfig>

    Notice the value of `versions`; it is **1** since this is the first version
    of the key that Vault knows about. This will figure into the example on key
    rotation later.

1. To use the keys you wrote, you must distribute them to the Cloud KMS. Add the
   **aes256-gcm96** key to the Cloud KMS at the path
   `keymgmt/kms/example-kms/key/aes256-gcm96`.

    ```shell-session
    $ vault write keymgmt/kms/example-kms/key/aes256-gcm96 \
        purpose="encrypt,decrypt" \
        protection="hsm"
    ```

1. List the keys that have been distributed to the Cloud KMS instance.

    ```shell-session
    $ vault list keymgmt/kms/gcpckms/key/
    Keys
    ----
    aes256-gcm96
    ```

1. Rotate the key.

    ```shell-session
    $ vault write -f keymgmt/key/aes256-gcm96/rotate
    ```

1. Confirm successful key rotation by reading the key, and get the value of
   `.data.latest_version`.

    ```shell-session
    $  vault read -format=json keymgmt/key/aes256-gcm96 | jq '.data.latest_version'
    2
    ```

    The key is now at version 2; in the Cloud Console, the key will be expected
    to have a different version string than the original value under **Primary
    version** as shown in the Cloud Console UI screenshot.

layout  docs page title  GCP Cloud KMS   Key Management   Secrets Engines description  Configure the key management secrets engine  and distribute the Vault managed keys to the target GCP Cloud KMS         Setup guide   GCP Cloud KMS   To manage the lifecycle of the GCP Cloud KMS key rings  you need to setup the key management secrets engine using  gcpckms  provider      Setup  1  Enable the key management secrets engine          shell session       vault secrets enable keymgmt          1  Configure the KMS provider resource named   example kms           shell session       vault write keymgmt kms example kms           provider  gcpckms            key collection  projects  project id  locations  location  keyRings  keyring             credentials service account file   path to service account credentials json               The command specified the following         The full path to this KMS provider instance in Vault         keymgmt kms example kms          The KMS provider type is set to  gcpckms         A key collection  which refers to the  resource       ID  https   cloud google com kms docs resource hierarchy retrieve resource id        of an existing GCP Cloud KMS key ring  this value cannot be changed after       creation        Credentials file to use for authentication with GCP Cloud KMS  Supplying       values for this parameter is optional  as credentials may also be       specified as the  GOOGLE CREDENTIALS  environment variable or default       application credentials     Tip title  API documentation    Refer to the GCP Cloud KMS  API documentation   vault api docs secret key management gcpkms  for a detailed description of individual configuration parameters     Tip      Usage   1  Write a new key of type   aes256 gcm96   to the path  keymgmt key aes256 gcm96            shell session       vault write keymgmt key aes256 gcm96 type  aes256 gcm96           1  Read the   aes256 gcm96   key  use JSON as the output  and pipe that into  jq           shell session       vault read  format json keymgmt key aes256 gcm96   jq                Example output          CodeBlockConfig hideClipboard          json                request id    631f98de b755 9863 40db f789ff9ff10a            lease id                lease duration   0           renewable   false           data                  deletion allowed   false               latest version   1               min enabled version   1               name    aes256 gcm96                type    aes256 gcm96                versions                  1                      creation time    2021 11 16T13 07 17 878864 05 00                                                  warnings   null                      CodeBlockConfig       Notice the value of  versions   it is   1   since this is the first version     of the key that Vault knows about  This will figure into the example on key     rotation later   1  To use the keys you wrote  you must distribute them to the Cloud KMS  Add the      aes256 gcm96   key to the Cloud KMS at the path     keymgmt kms example kms key aes256 gcm96           shell session       vault write keymgmt kms example kms key aes256 gcm96           purpose  encrypt decrypt            protection  hsm           1  List the keys that have been distributed to the Cloud KMS instance          shell session       vault list keymgmt kms gcpckms key      Keys              aes256 gcm96          1  Rotate the key          shell session       vault write  f keymgmt key aes256 gcm96 rotate          1  Confirm successful key rotation by reading the key  and get the value of      data latest version           shell session        vault read  format json keymgmt key aes256 gcm96   jq   data latest version      2               The key is now at version 2  in the Cloud Console  the key will be expected     to have a different version string than the original value under   Primary     version   as shown in the Cloud Console UI screenshot


vault page title One Time SSH Passwords OTP SSH Secrets Engines host using a helper command on the remote host to perform verification to issue a One Time Password every time a client wants to SSH into a remote The One Time SSH Password OTP SSH secrets engine type allows a Vault server layout docs One Time SSH passwords

Answer:
---
layout: docs
page_title: One-Time SSH Passwords (OTP) - SSH - Secrets Engines
description: |-
  The One-Time SSH Password (OTP) SSH secrets engine type allows a Vault server
  to issue a One-Time Password every time a client wants to SSH into a remote
  host using a helper command on the remote host to perform verification.
---

# One-Time SSH passwords

The One-Time SSH Password (OTP) SSH secrets engine type allows a Vault server to
issue a One-Time Password every time a client wants to SSH into a remote host
using a helper command on the remote host to perform verification.

An authenticated client requests credentials from the Vault server and, if
authorized, is issued an OTP. When the client establishes an SSH connection to
the desired remote host, the OTP used during SSH authentication is received by
the Vault helper, which then validates the OTP with the Vault server. The Vault
server then deletes this OTP, ensuring that it is only used once.

Since the Vault server is contacted during SSH connection establishment, every
login attempt and the correlating Vault lease information is logged to the audit
secrets engine.

See [Vault-SSH-Helper](https://github.com/hashicorp/vault-ssh-helper) for
details on the helper.

This page will show a quick start for this secrets engine. For detailed
documentation on every path, use `vault path-help` after mounting the secrets
engine.

### Drawbacks

The main concern with the OTP secrets engine type is the remote host's
connection to Vault; if compromised, an attacker could spoof the Vault server
returning a successful request. This risk can be mitigated by using TLS for the
connection to Vault and checking certificate validity; future enhancements to
this secrets engine may allow for extra security on top of what TLS provides.

### Mount the secrets engine

```shell-session
$ vault secrets enable ssh
Successfully mounted 'ssh' at 'ssh'!
```

### Create a role

Create a role with the `key_type` parameter set to `otp`. All of the machines
represented by the role's CIDR list should have helper properly installed and
configured.

```shell-session
$ vault write ssh/roles/otp_key_role \
    key_type=otp \
    default_user=username \
    cidr_list=x.x.x.x/y,m.m.m.m/n
Success! Data written to: ssh/roles/otp_key_role
```

### Create a credential

Create an OTP credential for an IP of the remote host that belongs to
`otp_key_role`.

```shell-session
$ vault write ssh/creds/otp_key_role ip=x.x.x.x
Key            	Value
lease_id       	ssh/creds/otp_key_role/73bbf513-9606-4bec-816c-5a2f009765a5
lease_duration 	600
lease_renewable	false
port           	22
username       	username
ip             	x.x.x.x
key            	2f7e25a2-24c9-4b7b-0d35-27d5e5203a5c
key_type       	otp
```

### Establish an SSH session

```shell-session
$ ssh username@x.x.x.x
Password: <Enter OTP>
username@x.x.x.x:~$
```

### Automate it!

A single CLI command can be used to create a new OTP and invoke SSH with the
correct parameters to connect to the host.

```shell-session
$ vault ssh -role otp_key_role -mode otp username@x.x.x.x
OTP for the session is `b4d47e1b-4879-5f4e-ce5c-7988d7986f37`
[Note: Install `sshpass` to automate typing in OTP]
Password: <Enter OTP>
```

The OTP will be entered automatically using `sshpass` if it is installed.

```shell-session
$ vault ssh -role otp_key_role -mode otp -strict-host-key-checking=no username@x.x.x.x
username@<IP of remote host>:~$
```

Note: `sshpass` cannot handle host key checking. Host key checking can be
disabled by setting `-strict-host-key-checking=no`.

## Tutorial

Refer to the [SSH Secrets Engine: One-Time SSH
Password](/vault/tutorials/secrets-management/ssh-otp) tutorial
to learn how to use the Vault SSH secrets engine to secure authentication and authorization for access to machines.

## API

The SSH secrets engine has a full HTTP API. Please see the
[SSH secrets engine API](/vault/api-docs/secret/ssh) for more
details.

layout  docs page title  One Time SSH Passwords  OTP    SSH   Secrets Engines description       The One Time SSH Password  OTP  SSH secrets engine type allows a Vault server   to issue a One Time Password every time a client wants to SSH into a remote   host using a helper command on the remote host to perform verification         One Time SSH passwords  The One Time SSH Password  OTP  SSH secrets engine type allows a Vault server to issue a One Time Password every time a client wants to SSH into a remote host using a helper command on the remote host to perform verification   An authenticated client requests credentials from the Vault server and  if authorized  is issued an OTP  When the client establishes an SSH connection to the desired remote host  the OTP used during SSH authentication is received by the Vault helper  which then validates the OTP with the Vault server  The Vault server then deletes this OTP  ensuring that it is only used once   Since the Vault server is contacted during SSH connection establishment  every login attempt and the correlating Vault lease information is logged to the audit secrets engine   See  Vault SSH Helper  https   github com hashicorp vault ssh helper  for details on the helper   This page will show a quick start for this secrets engine  For detailed documentation on every path  use  vault path help  after mounting the secrets engine       Drawbacks  The main concern with the OTP secrets engine type is the remote host s connection to Vault  if compromised  an attacker could spoof the Vault server returning a successful request  This risk can be mitigated by using TLS for the connection to Vault and checking certificate validity  future enhancements to this secrets engine may allow for extra security on top of what TLS provides       Mount the secrets engine     shell session   vault secrets enable ssh Successfully mounted  ssh  at  ssh            Create a role  Create a role with the  key type  parameter set to  otp   All of the machines represented by the role s CIDR list should have helper properly installed and configured      shell session   vault write ssh roles otp key role       key type otp       default user username       cidr list x x x x y m m m m n Success  Data written to  ssh roles otp key role          Create a credential  Create an OTP credential for an IP of the remote host that belongs to  otp key role       shell session   vault write ssh creds otp key role ip x x x x Key             Value lease id        ssh creds otp key role 73bbf513 9606 4bec 816c 5a2f009765a5 lease duration  600 lease renewable false port            22 username        username ip              x x x x key             2f7e25a2 24c9 4b7b 0d35 27d5e5203a5c key type        otp          Establish an SSH session     shell session   ssh username x x x x Password   Enter OTP  username x x x x             Automate it   A single CLI command can be used to create a new OTP and invoke SSH with the correct parameters to connect to the host      shell session   vault ssh  role otp key role  mode otp username x x x x OTP for the session is  b4d47e1b 4879 5f4e ce5c 7988d7986f37   Note  Install  sshpass  to automate typing in OTP  Password   Enter OTP       The OTP will be entered automatically using  sshpass  if it is installed      shell session   vault ssh  role otp key role  mode otp  strict host key checking no username x x x x username  IP of remote host          Note   sshpass  cannot handle host key checking  Host key checking can be disabled by setting   strict host key checking no       Tutorial  Refer to the  SSH Secrets Engine  One Time SSH Password   vault tutorials secrets management ssh otp  tutorial to learn how to use the Vault SSH secrets engine to secure authentication and authorization for access to machines      API  The SSH secrets engine has a full HTTP API  Please see the  SSH secrets engine API   vault api docs secret ssh  for more details