From 3eb38d19ba8a9b005f91fed7b32d0fe45de21929 Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Mon, 21 Sep 2015 12:24:17 -0400 Subject: [PATCH] Update transit backend documentation, and also return the min decryption value in a read operation on the key. --- builtin/logical/transit/path_datakey.go | 4 +- builtin/logical/transit/path_keys.go | 9 +- .../source/docs/secrets/transit/index.html.md | 252 ++++++++++++++++-- 3 files changed, 240 insertions(+), 25 deletions(-) diff --git a/builtin/logical/transit/path_datakey.go b/builtin/logical/transit/path_datakey.go index 43652733a..b4499d45e 100644 --- a/builtin/logical/transit/path_datakey.go +++ b/builtin/logical/transit/path_datakey.go @@ -32,8 +32,8 @@ ciphertext; "wrapped" will return the ciphertext only.`, "bits": &framework.FieldSchema{ Type: framework.TypeInt, - Description: `Number of bits for the key; currently 128 and -256 are supported. Defaults to 256.`, + Description: `Number of bits for the key; currently 128, 256, +and 512 bits are supported. Defaults to 256.`, Default: 256, }, }, diff --git a/builtin/logical/transit/path_keys.go b/builtin/logical/transit/path_keys.go index 7c6d1d157..44d3f18ab 100644 --- a/builtin/logical/transit/path_keys.go +++ b/builtin/logical/transit/path_keys.go @@ -68,10 +68,11 @@ func pathPolicyRead( // Return the response resp := &logical.Response{ Data: map[string]interface{}{ - "name": p.Name, - "cipher_mode": p.CipherMode, - "derived": p.Derived, - "deletion_allowed": p.DeletionAllowed, + "name": p.Name, + "cipher_mode": p.CipherMode, + "derived": p.Derived, + "deletion_allowed": p.DeletionAllowed, + "min_decryption_version": p.MinDecryptionVersion, }, } if p.Derived { diff --git a/website/source/docs/secrets/transit/index.html.md b/website/source/docs/secrets/transit/index.html.md index b002a7667..567a3182c 100644 --- a/website/source/docs/secrets/transit/index.html.md +++ b/website/source/docs/secrets/transit/index.html.md @@ -21,14 +21,44 @@ application developers and pushes the burden onto the operators of Vault. Operators of Vault generally include the security team at an organization, which means they can ensure that data is encrypted/decrypted properly. -As of Vault 0.2, the transit backend also supports doing key derivation. This -allows data to be encrypted within a context such that the same context must be -used for decryption. This can be used to enable per transaction unique keys which -further increase the security of data at rest. - Additionally, since encrypt/decrypt operations must enter the audit log, any decryption event is recorded. +Due to Vault's flexible ACLs, other interesting use-cases are possible. For +instance, one set of Internet-facing servers can be given permission to encrypt +with a named key but not decrypt with it; a separate set of servers not +directly connected to the Internet can then perform decryption, reducing the +data's attack surface. + +As of Vault 0.2, the transit backend supports doing key derivation. This +allows data to be encrypted within a context such that the same context must be +used for decryption. This can be used to enable per-transaction unique keys which +further increase the security of data at rest. + +As of Vault 0.3, the transit backend gained two new key features: key rotation +and datakey generation. + +Key rotation allows a new version of the named key to be generated. All data +encrypted with the key will use the newest version of the key; previously +encrypted data can be decrypted using old versions of the key. Administrators +can control which previous versions of a key are available for decryption, to +prevent an attacker gaining an old copy of ciphertext to be able to successfully +decrypt it. At any time, a legitimate user can "rewrap" the data, providing an +old version of the ciphertext and receiving a new version encrypted with the +latest key. Because rewrapping does not expose the plaintext, using Vault's ACL +system, this can even be safely performed by unprivileged users or cron jobs. + +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. + +N.B.: As part of adding rotation support, the initial version of a named key +now produces ciphertext starting with version 1, i.e. containing `:v1:`. +Existing keys, when rotated, will jump to version 2 despite their previous +ciphertext output containing `:v0:`. Decryption, however, treats version 0 and +version 1 the same, so old ciphertext will still work. + This page will show a quick start for this backend. For detailed documentation on every path, use `vault path-help` after mounting the backend. @@ -68,7 +98,7 @@ endpoint using our named key: ``` $ echo -n "the quick brown fox" | base64 | vault write transit/encrypt/foo plaintext=- Key Value -ciphertext vault:v0:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv +ciphertext vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv ``` The encryption endpoint expects the plaintext to be provided as a base64 encoded @@ -79,7 +109,7 @@ is free to store the ciphertext in a database or file at rest. To decrypt, we simply use the decrypt endpoint using the same named key: ``` -$ vault write transit/decrypt/foo ciphertext=vault:v0:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv +$ vault write transit/decrypt/foo ciphertext=vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv Key Value plaintext dGhlIHF1aWNrIGJyb3duIGZveAo= @@ -133,8 +163,9 @@ only encrypt or decrypt using the named keys they need access to.
Description
- Returns information about a named encryption key. - This is a root protected endpoint. + Returns information about a named encryption key. The `keys` object shows + the creation time of each key version; the values are not the keys + themselves. This is a root protected endpoint.
Method
@@ -152,13 +183,16 @@ only encrypt or decrypt using the named keys they need access to.
```javascript + "data": { + "cipher_mode": "aes-gcm", + "deletion_allowed": false, + "derived": false, + "keys": { + "1": 1442851412 + }, { - "data": { - "name": "foo", - "cipher_mode": "aes-gcm", - "derived": "true", - "kdf_mode": "hmac-sha256-counter", - } + "min_decryption_version": 0, + "name": "foo" } ``` @@ -171,7 +205,9 @@ only encrypt or decrypt using the named keys they need access to.
Description
Deletes a named encryption key. This is a root protected endpoint. - All data encrypted with the named key will no longer be decryptable. + It will no longer be possible to decrypt any data encrypted with the + named key. Because this is a potentially catastrophic operation, the + `deletion_allowed` tunable must be set in the key's `/config` endpoint.
Method
@@ -191,6 +227,77 @@ only encrypt or decrypt using the named keys they need access to.
+### /transit/keys/config +#### POST + +
+
Description
+
+ Allows tuning configuration values for a given key. (These values are + returned during a read operation on the named key.) This is a + root-protected endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/transit/keys//config`
+ +
Parameters
+
+
    +
  • + min_decryption_version + optional + The minimum version of ciphertext allowed to be decrypted. Adjusting + this as part of a key rotation policy can prevent old copies of + ciphertext from being decrypted, should they fall into the wrong hands. + Defaults to 0. +
    • +
  • + deletion_allowed + optional + When set, the key is allowed to be deleted. Defaults to false. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /transit/keys/rotate/ +#### POST + +
+
Description
+
+ Rotates the version of the named key. After rotation, new plaintext + requests will be encrypted with the new version of the key. To upgrade + ciphertext to be encrypted with the latest version of the key, use the + `rewrap` endpoint. This is a root-protected endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/transit/keys//rotate`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ A `204` response code. +
+
+ ### /transit/encrypt/ #### POST @@ -220,7 +327,7 @@ only encrypt or decrypt using the named keys they need access to. context optional The key derivation context, provided as base64 encoded. - Must be provided if the derivation enabled. + Must be provided if derivation is enabled. @@ -231,7 +338,7 @@ only encrypt or decrypt using the named keys they need access to. ```javascript { "data": { - "ciphertext": "vault:v0:abcdefgh" + "ciphertext": "vault:v1:abcdefgh" } } ``` @@ -266,7 +373,7 @@ only encrypt or decrypt using the named keys they need access to. context optional The key derivation context, provided as base64 encoded. - Must be provided if the derivation enabled. + Must be provided if derivation is enabled. @@ -284,3 +391,110 @@ only encrypt or decrypt using the named keys they need access to. + +### /transit/rewrap/ +#### POST + +
+
Description
+
+ Rewrap the provided ciphertext using the latest version of the named key. + Because this never returns plaintext, it is possible to delegate this + functionality to untrusted users or scripts. +
+ +
Method
+
POST
+ +
URL
+
`/transit/rewrap/`
+ +
Parameters
+
+
    +
  • + ciphertext + required + The ciphertext to decrypt, provided as returned by encrypt. +
    • +
  • + context + optional + The key derivation context, provided as base64 encoded. + Must be provided if derivation is enabled. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "data": { + "ciphertext": "vault:v2:abcdefgh" + } + } + ``` + +
+
+ +### /transit/datakey/ +#### POST + +
+
Description
+
+ Generate a new high-entropy key and the valued encrypted with the named + key. Optionally return the plaintext of the key as well. Whether plaintext + is returned depends on the path; as a result, you can use Vault ACL + policies to control whether a user is allowed to retrieve the plaintext + value of a key. This is useful if you want an untrusted user or operation + to generate keys that are then made available to trusted users. +
+ +
Method
+
POST
+ +
URL
+
`/transit/datakey//`
+ +
Parameters
+
+
    +
  • + plaintext|wrapped (path parameter) + required + If `plaintext`, the plaintext key will be returned along with the + ciphertext. If `wrapped`, only the ciphertext value will be returned. +
    • +
  • + context + optional + The key derivation context, provided as base64 encoded. + Must be provided if derivation is enabled. +
    • +
  • + bits + optional + The number of bits in the desired key. Can be 128, 256, or 512; if not + given, defaults to 256. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "data": { + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", + "ciphertext": "vault:v1:abcdefgh" + } + } + ``` + +
+