1--- 2layout: "docs" 3page_title: "Transit - Secrets Engines" 4sidebar_title: "Transit" 5sidebar_current: "docs-secrets-transit" 6description: |- 7 The transit secrets engine for Vault encrypts/decrypts data in-transit. It doesn't store any secrets. 8--- 9 10# Transit Secrets Engine 11 12The transit secrets engine handles cryptographic functions on data in-transit. 13Vault doesn't store the data sent to the secrets engine. It can also be viewed 14as "cryptography as a service" or "encryption as a service". The transit secrets 15engine can also sign and verify data; generate hashes and HMACs of data; and act 16as a source of random bytes. 17 18The primary use case for `transit` is to encrypt data from applications while 19still storing that encrypted data in some primary data store. This relieves the 20burden of proper encryption/decryption from application developers and pushes 21the burden onto the operators of Vault. 22 23Key derivation is supported, which allows the same key to be used for multiple 24purposes by deriving a new key based on a user-supplied context value. In this 25mode, convergent encryption can optionally be supported, which allows the same 26input values to produce the same ciphertext. 27 28Datakey generation allows processes to request a high-entropy key of a given 29bit length be returned to them, encrypted with the named key. Normally this will 30also return the key in plaintext to allow for immediate use, but this can be 31disabled to accommodate auditing requirements. 32 33## Working Set Management 34 35This secrets engine does not currently delete keys. Keys that are out of the 36working set (earlier than a key's specified `min_decryption_version` are 37instead archived. This is a performance consideration to keep key loading fast, 38as well as a security consideration: by disallowing decryption of old versions 39of keys, found ciphertext corresponding to obsolete (but sensitive) data can 40not be decrypted by most users, but in an emergency the 41`min_decryption_version` can be moved back to allow for legitimate decryption. 42 43Currently this archive is stored in a single storage entry. With some storage 44backends, notably those using Raft or Paxos for HA capabilities, frequent 45rotation may lead to a storage entry size for the archive that is larger than 46the storage backend can handle. For frequent rotation needs, using named keys 47that correspond to time bounds (e.g. five-minute periods floored to the closest 48multiple of five) may provide a good alternative, allowing for several keys to 49be live at once and a deterministic way to decide which key to use at any given 50time. 51 52## Key Types 53 54As of now, the transit secrets engine supports the following key types (all key 55types also generate separate HMAC keys): 56 57* `aes256-gcm96`: AES-GCM with a 256-bit AES key and a 96-bit nonce; supports 58 encryption, decryption, key derivation, and convergent encryption 59* `chacha20-poly1305`: ChaCha20-Poly1305 with a 256-bit key; supports 60 encryption, decryption, key derivation, and convergent encryption 61* `ed25519`: Ed25519; supports signing, signature verification, and key 62 derivation 63* `ecdsa-p256`: ECDSA using curve P256; supports signing and signature 64 verification 65* `rsa-2048`: 2048-bit RSA key; supports encryption, decryption, signing, and 66 signature verification 67* `rsa-4096`: 4096-bit RSA key; supports encryption, decryption, signing, and 68 signature verification 69 70## Convergent Encryption 71 72Convergent encryption is a mode where the same set of plaintext+context always 73result in the same ciphertext. It does this by deriving a key using a key 74derivation function but also by deterministically deriving a nonce. Because 75these properties differ for any combination of plaintext and ciphertext over a 76keyspace the size of 2^256, the risk of nonce reuse is near zero. 77 78This has many practical uses. A key usage mode is to allow values to be stored 79encrypted in a database, but with limited lookup/query support, so that rows 80with the same value for a specific field can be returned from a query. 81 82To accommodate for any needed upgrades to the algorithm, different versions of 83convergent encryption have historically been supported: 84 85* Version 1 required the client to provide their own nonce, which is highly 86 flexible but if done incorrectly can be dangerous. This was only in Vault 87 0.6.1, and keys using this version cannot be upgraded. 88* Version 2 used an algorithmic approach to deriving the parameters. However, 89 the algorithm used was susceptible to offline plaintext-confirmation attacks, 90 which could allow attackers to brute force decryption if the plaintext size 91 was small. Keys using version 2 can be upgraded by simply performing a rotate 92 operation to a new key version; existing values can then be rewrapped against 93 the new key version and will use the version 3 algorithm. 94* Version 3 uses a different algorithm designed to be resistant to offline 95 plaintext-confirmation attacks. It is similar to AES-SIV in that it uses a 96 PRF to generate the nonce from the plaintext. 97 98## Setup 99 100Most secrets engines must be configured in advance before they can perform their 101functions. These steps are usually completed by an operator or configuration 102management tool. 103 1041. Enable the Transit secrets engine: 105 106 ```text 107 $ vault secrets enable transit 108 Success! Enabled the transit secrets engine at: transit/ 109 ``` 110 111 By default, the secrets engine will mount at the name of the engine. To 112 enable the secrets engine at a different path, use the `-path` argument. 113 1141. Create a named encryption key: 115 116 ```text 117 $ vault write -f transit/keys/my-key 118 Success! Data written to: transit/keys/my-key 119 ``` 120 121 Usually each application has its own encryption key. 122 123## Usage 124 125After the secrets engine is configured and a user/machine has a Vault token with 126the proper permission, it can use this secrets engine. 127 1281. Encrypt some plaintext data using the `/encrypt` endpoint with a named key: 129 130 ```text 131 $ vault write transit/encrypt/my-key plaintext=$(base64 <<< "my secret data") 132 133 Key Value 134 --- ----- 135 ciphertext vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w== 136 ``` 137 138 All plaintext data **must be base64-encoded**. The reason for this 139 requirement is that Vault does not require that the plaintext is "text". It 140 could be a binary file such as a PDF or image. The easiest safe transport 141 mechanism for this data as part of a JSON payload is to base64-encode it. 142 143 Note that Vault does not _store_ any of this data. The caller is responsible 144 for storing the encrypted ciphertext. When the caller wants the plaintext, 145 it must provide the ciphertext back to Vault to decrypt the value. 146 147 !> Vault HTTP API imposes a maximum request size of 32MB to prevent a denial 148 of service attack. This can be tuned per [`listener` 149 block](/docs/configuration/listener/tcp.html) in the Vault server 150 configuration. 151 1521. Decrypt a piece of data using the `/decrypt` endpoint with a named key: 153 154 ```text 155 $ vault write transit/decrypt/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w== 156 157 Key Value 158 --- ----- 159 plaintext bXkgc2VjcmV0IGRhdGEK 160 ``` 161 162 The resulting data is base64-encoded (see the note above for details on 163 why). Decode it to get the raw plaintext: 164 165 ```text 166 $ base64 --decode <<< "bXkgc2VjcmV0IGRhdGEK" 167 my secret data 168 ``` 169 170 It is also possible to script this decryption using some clever shell 171 scripting in one command: 172 173 ```text 174 $ vault write -field=plaintext transit/decrypt/my-key ciphertext=... | base64 --decode 175 my secret data 176 ``` 177 178 Using ACLs, it is possible to restrict using the transit secrets engine such 179 that trusted operators can manage the named keys, and applications can only 180 encrypt or decrypt using the named keys they need access to. 181 1821. Rotate the underlying encryption key. This will generate a new encryption key 183and add it to the keyring for the named key: 184 185 ```text 186 $ vault write -f transit/keys/my-key/rotate 187 Success! Data written to: transit/keys/my-key/rotate 188 ``` 189 190 Future encryptions will use this new key. Old data can still be decrypted 191 due to the use of a key ring. 192 1931. Upgrade already-encrypted data to a new key. Vault will decrypt the value 194using the appropriate key in the keyring and then encrypted the resulting 195plaintext with the newest key in the keyring. 196 197 ```text 198 $ vault write transit/rewrap/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w== 199 200 Key Value 201 --- ----- 202 ciphertext vault:v2:0VHTTBb2EyyNYHsa3XiXsvXOQSLKulH+NqS4eRZdtc2TwQCxqJ7PUipvqQ== 203 ``` 204 205 This process **does not** reveal the plaintext data. As such, a Vault policy 206 could grant almost an untrusted process the ability to "rewrap" encrypted 207 data, since the process would not be able to get access to the plaintext 208 data. 209 210## API 211 212The Transit secrets engine has a full HTTP API. Please see the 213[Transit secrets engine API](/api/secret/transit/index.html) for more 214details. 215