1--- 2layout: "docs" 3page_title: "Secret Backend: Transit" 4sidebar_current: "docs-secrets-transit" 5description: |- 6 The transit secret backend for Vault encrypts/decrypts data in-transit. It doesn't store any secrets. 7--- 8 9# Transit Secret Backend 10 11Name: `transit` 12 13The transit secret backend is used to encrypt/decrypt data in-transit. Vault 14doesn't store the data sent to the backend. It can also be viewed as "encryption 15as a service." 16 17The primary use case for the transit backend is to encrypt data from 18applications while still storing that encrypted data in some primary data 19store. This relieves the burden of proper encryption/decryption from 20application developers and pushes the burden onto the operators of Vault. 21Operators of Vault generally include the security team at an organization, 22which means they can ensure that data is encrypted/decrypted properly. 23 24Additionally, since encrypt/decrypt operations must enter the audit log, 25any decryption event is recorded. 26 27Due to Vault's flexible ACLs, other interesting use-cases are possible. For 28instance, one set of Internet-facing servers can be given permission to encrypt 29with a named key but not decrypt with it; a separate set of servers not 30directly connected to the Internet can then perform decryption, reducing the 31data's attack surface. 32 33As of Vault 0.2, the transit backend supports doing key derivation. This 34allows data to be encrypted within a context such that the same context must be 35used for decryption. This can be used to enable per-transaction unique keys which 36further increase the security of data at rest. 37 38As of Vault 0.3, the transit backend gained two new key features: key rotation 39and datakey generation. 40 41Key rotation allows a new version of the named key to be generated. All data 42encrypted with the key will use the newest version of the key; previously 43encrypted data can be decrypted using old versions of the key. Administrators 44can control which previous versions of a key are available for decryption, to 45prevent an attacker gaining an old copy of ciphertext to be able to successfully 46decrypt it. At any time, a legitimate user can "rewrap" the data, providing an 47old version of the ciphertext and receiving a new version encrypted with the 48latest key. Because rewrapping does not expose the plaintext, using Vault's ACL 49system, this can even be safely performed by unprivileged users or cron jobs. 50 51Datakey generation allows processes to request a high-entropy key of a given 52bit length be returned to them, encrypted with the named key. Normally this will 53also return the key in plaintext to allow for immediate use, but this can be 54disabled to accommodate auditing requirements. 55 56N.B.: As part of adding rotation support, the initial version of a named key 57now produces ciphertext starting with version 1, i.e. containing `:v1:`. 58Existing keys, when rotated, will jump to version 2 despite their previous 59ciphertext output containing `:v0:`. Decryption, however, treats version 0 and 60version 1 the same, so old ciphertext will still work. 61 62This page will show a quick start for this backend. For detailed documentation 63on every path, use `vault path-help` after mounting the backend. 64 65## Quick Start 66 67The first step to using the transit backend is to mount it. Unlike the `generic` 68backend, the `transit` backend is not mounted by default. 69 70``` 71$ vault mount transit 72Successfully mounted 'transit' at 'transit'! 73``` 74 75The next step is to create a named encryption key. A named key is used so that 76many different applications can use the transit backend with independent keys. 77This is done by doing a write against the backend: 78 79``` 80$ vault write -f transit/keys/foo 81Success! Data written to: transit/keys/foo 82``` 83 84This will create the "foo" named key in the transit backend. We can inspect 85the settings of the "foo" key by reading it: 86 87``` 88$ vault read transit/keys/foo 89Key Value 90cipher_mode aes-gcm 91deletion_allowed false 92derived false 93keys map[1:1.459861712e+09] 94latest_version 1 95min_decryption_version 1 96name foo 97```` 98 99Now, if we wanted to encrypt a piece of plain text, we use the encrypt 100endpoint using our named key: 101 102``` 103$ echo -n "the quick brown fox" | base64 | vault write transit/encrypt/foo plaintext=- 104Key Value 105ciphertext vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv 106``` 107 108The encryption endpoint expects the plaintext to be provided as a base64 encoded 109strings, so we must first convert it. Vault does not store the plaintext or the 110ciphertext, but only handles it _in transit_ for processing. The application 111is free to store the ciphertext in a database or file at rest. 112 113To decrypt, we simply use the decrypt endpoint using the same named key: 114 115``` 116$ vault write transit/decrypt/foo ciphertext=vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv 117Key Value 118plaintext dGhlIHF1aWNrIGJyb3duIGZveAo= 119 120$ echo "dGhlIHF1aWNrIGJyb3duIGZveAo=" | base64 -d 121the quick brown fox 122``` 123 124Using ACLs, it is possible to restrict using the transit backend such 125that trusted operators can manage the named keys, and applications can 126only encrypt or decrypt using the named keys they need access to. 127 128## API 129 130### /transit/keys/ 131#### POST 132 133<dl class="api"> 134 <dt>Description</dt> 135 <dd> 136 Creates a new named encryption key. 137 </dd> 138 139 <dt>Method</dt> 140 <dd>POST</dd> 141 142 <dt>URL</dt> 143 <dd>`/transit/keys/<name>`</dd> 144 145 <dt>Parameters</dt> 146 <dd> 147 <ul> 148 <li> 149 <span class="param">derived</span> 150 <span class="param-flags">optional</span> 151 Boolean flag indicating if key derivation MUST be used. 152 If enabled, all encrypt/decrypt requests to this named key 153 must provide a context which is used for key derivation. 154 Defaults to false. 155 </li> 156 </ul> 157 </dd> 158 159 <dt>Returns</dt> 160 <dd> 161 A `204` response code. 162 </dd> 163</dl> 164 165#### GET 166 167<dl class="api"> 168 <dt>Description</dt> 169 <dd> 170 Returns information about a named encryption key. The `keys` object shows 171 the creation time of each key version; the values are not the keys 172 themselves. 173 </dd> 174 175 <dt>Method</dt> 176 <dd>GET</dd> 177 178 <dt>URL</dt> 179 <dd>`/transit/keys/<name>`</dd> 180 181 <dt>Parameters</dt> 182 <dd> 183 None 184 </dd> 185 186 <dt>Returns</dt> 187 <dd> 188 189 ```javascript 190 { 191 "data": { 192 "cipher_mode": "aes-gcm", 193 "deletion_allowed": false, 194 "derived": false, 195 "keys": { 196 "1": 1442851412 197 }, 198 "min_decryption_version": 0, 199 "name": "foo" 200 } 201 } 202 ``` 203 204 </dd> 205</dl> 206 207#### DELETE 208 209<dl class="api"> 210 <dt>Description</dt> 211 <dd> 212 Deletes a named encryption key. 213 It will no longer be possible to decrypt any data encrypted with the 214 named key. Because this is a potentially catastrophic operation, the 215 `deletion_allowed` tunable must be set in the key's `/config` endpoint. 216 </dd> 217 218 <dt>Method</dt> 219 <dd>DELETE</dd> 220 221 <dt>URL</dt> 222 <dd>`/transit/keys/<name>`</dd> 223 224 <dt>Parameters</dt> 225 <dd> 226 None 227 </dd> 228 229 <dt>Returns</dt> 230 <dd> 231 A `204` response code. 232 </dd> 233</dl> 234 235### /transit/keys/config 236#### POST 237 238<dl class="api"> 239 <dt>Description</dt> 240 <dd> 241 Allows tuning configuration values for a given key. (These values are 242 returned during a read operation on the named key.) 243 </dd> 244 245 <dt>Method</dt> 246 <dd>POST</dd> 247 248 <dt>URL</dt> 249 <dd>`/transit/keys/<name>/config`</dd> 250 251 <dt>Parameters</dt> 252 <dd> 253 <ul> 254 <li> 255 <span class="param">min_decryption_version</span> 256 <span class="param-flags">optional</span> 257 The minimum version of ciphertext allowed to be decrypted. Adjusting 258 this as part of a key rotation policy can prevent old copies of 259 ciphertext from being decrypted, should they fall into the wrong hands. 260 Defaults to 0. 261 </li> 262 <li> 263 <span class="param">deletion_allowed</span> 264 <span class="param-flags">optional</span> 265 When set, the key is allowed to be deleted. Defaults to false. 266 </li> 267 </ul> 268 </dd> 269 270 <dt>Returns</dt> 271 <dd> 272 A `204` response code. 273 </dd> 274</dl> 275 276### /transit/keys/rotate/ 277#### POST 278 279<dl class="api"> 280 <dt>Description</dt> 281 <dd> 282 Rotates the version of the named key. After rotation, new plaintext 283 requests will be encrypted with the new version of the key. To upgrade 284 ciphertext to be encrypted with the latest version of the key, use the 285 `rewrap` endpoint. 286 </dd> 287 288 <dt>Method</dt> 289 <dd>POST</dd> 290 291 <dt>URL</dt> 292 <dd>`/transit/keys/<name>/rotate`</dd> 293 294 <dt>Parameters</dt> 295 <dd> 296 None 297 </dd> 298 299 <dt>Returns</dt> 300 <dd> 301 A `204` response code. 302 </dd> 303</dl> 304 305### /transit/encrypt/ 306#### POST 307 308<dl class="api"> 309 <dt>Description</dt> 310 <dd> 311 Encrypts the provided plaintext using the named key. This path supports the 312 `create` and `update` policy capabilities as follows: if the user has the 313 `create` capability for this endpoint in their policies, and the key does 314 not exist, it will be upserted with default values (whether the key 315 requires derivation depends on whether the context parameter is empty or 316 not). If the user only has `update` capability and the key does not exist, 317 an error will be returned. 318 </dd> 319 320 <dt>Method</dt> 321 <dd>POST</dd> 322 323 <dt>URL</dt> 324 <dd>`/transit/encrypt/<name>`</dd> 325 326 <dt>Parameters</dt> 327 <dd> 328 <ul> 329 <li> 330 <span class="param">plaintext</span> 331 <span class="param-flags">required</span> 332 The plaintext to encrypt, provided as base64 encoded. 333 </li> 334 <li> 335 <span class="param">context</span> 336 <span class="param-flags">optional</span> 337 The key derivation context, provided as base64 encoded. 338 Must be provided if derivation is enabled. 339 </li> 340 </ul> 341 </dd> 342 343 <dt>Returns</dt> 344 <dd> 345 346 ```javascript 347 { 348 "data": { 349 "ciphertext": "vault:v1:abcdefgh" 350 } 351 } 352 ``` 353 354 </dd> 355</dl> 356 357### /transit/decrypt/ 358#### POST 359 360<dl class="api"> 361 <dt>Description</dt> 362 <dd> 363 Decrypts the provided ciphertext using the named key. 364 </dd> 365 366 <dt>Method</dt> 367 <dd>POST</dd> 368 369 <dt>URL</dt> 370 <dd>`/transit/decrypt/<name>`</dd> 371 372 <dt>Parameters</dt> 373 <dd> 374 <ul> 375 <li> 376 <span class="param">ciphertext</span> 377 <span class="param-flags">required</span> 378 The ciphertext to decrypt, provided as returned by encrypt. 379 </li> 380 <li> 381 <span class="param">context</span> 382 <span class="param-flags">optional</span> 383 The key derivation context, provided as base64 encoded. 384 Must be provided if derivation is enabled. 385 </li> 386 </ul> 387 </dd> 388 389 <dt>Returns</dt> 390 <dd> 391 392 ```javascript 393 { 394 "data": { 395 "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" 396 } 397 } 398 ``` 399 400 </dd> 401</dl> 402 403### /transit/rewrap/ 404#### POST 405 406<dl class="api"> 407 <dt>Description</dt> 408 <dd> 409 Rewrap the provided ciphertext using the latest version of the named key. 410 Because this never returns plaintext, it is possible to delegate this 411 functionality to untrusted users or scripts. 412 </dd> 413 414 <dt>Method</dt> 415 <dd>POST</dd> 416 417 <dt>URL</dt> 418 <dd>`/transit/rewrap/<name>`</dd> 419 420 <dt>Parameters</dt> 421 <dd> 422 <ul> 423 <li> 424 <span class="param">ciphertext</span> 425 <span class="param-flags">required</span> 426 The ciphertext to decrypt, provided as returned by encrypt. 427 </li> 428 <li> 429 <span class="param">context</span> 430 <span class="param-flags">optional</span> 431 The key derivation context, provided as base64 encoded. 432 Must be provided if derivation is enabled. 433 </li> 434 </ul> 435 </dd> 436 437 <dt>Returns</dt> 438 <dd> 439 440 ```javascript 441 { 442 "data": { 443 "ciphertext": "vault:v2:abcdefgh" 444 } 445 } 446 ``` 447 448 </dd> 449</dl> 450 451### /transit/datakey/ 452#### POST 453 454<dl class="api"> 455 <dt>Description</dt> 456 <dd> 457 Generate a new high-entropy key and the value encrypted with the named 458 key. Optionally return the plaintext of the key as well. Whether plaintext 459 is returned depends on the path; as a result, you can use Vault ACL 460 policies to control whether a user is allowed to retrieve the plaintext 461 value of a key. This is useful if you want an untrusted user or operation 462 to generate keys that are then made available to trusted users. 463 </dd> 464 465 <dt>Method</dt> 466 <dd>POST</dd> 467 468 <dt>URL</dt> 469 <dd>`/transit/datakey/<plaintext|wrapped>/<name>`</dd> 470 471 <dt>Parameters</dt> 472 <dd> 473 <ul> 474 <li> 475 <span class="param">plaintext|wrapped (path parameter)</span> 476 <span class="param-flags">required</span> 477 If `plaintext`, the plaintext key will be returned along with the 478 ciphertext. If `wrapped`, only the ciphertext value will be returned. 479 </li> 480 <li> 481 <span class="param">context</span> 482 <span class="param-flags">optional</span> 483 The key derivation context, provided as base64 encoded. 484 Must be provided if derivation is enabled. 485 </li> 486 <li> 487 <span class="param">bits</span> 488 <span class="param-flags">optional</span> 489 The number of bits in the desired key. Can be 128, 256, or 512; if not 490 given, defaults to 256. 491 </li> 492 </ul> 493 </dd> 494 495 <dt>Returns</dt> 496 <dd> 497 498 ```javascript 499 { 500 "data": { 501 "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", 502 "ciphertext": "vault:v1:abcdefgh" 503 } 504 } 505 ``` 506 507 </dd> 508</dl> 509