Update transit backend documentation, and also return the min decryption
value in a read operation on the key.
This commit is contained in:
Jeff Mitchell
parent
ca33cd8423
commit
3eb38d19ba
|
|
@ -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,
|
||||
},
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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.
|
|||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
|
|
@ -152,13 +183,16 @@ only encrypt or decrypt using the named keys they need access to.
|
|||
<dd>
|
||||
|
||||
```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.
|
|||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
|
|
@ -191,6 +227,77 @@ only encrypt or decrypt using the named keys they need access to.
|
|||
</dd>
|
||||
</dl>
|
||||
|
||||
### /transit/keys/config
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/transit/keys/<name>/config`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">min_decryption_version</span>
|
||||
<span class="param-flags">optional</span>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">deletion_allowed</span>
|
||||
<span class="param-flags">optional</span>
|
||||
When set, the key is allowed to be deleted. Defaults to false.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /transit/keys/rotate/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/transit/keys/<name>/rotate`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
A `204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /transit/encrypt/
|
||||
#### POST
|
||||
|
||||
|
|
@ -220,7 +327,7 @@ only encrypt or decrypt using the named keys they need access to.
|
|||
<span class="param">context</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The key derivation context, provided as base64 encoded.
|
||||
Must be provided if the derivation enabled.
|
||||
Must be provided if derivation is enabled.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
|
@ -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.
|
|||
<span class="param">context</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The key derivation context, provided as base64 encoded.
|
||||
Must be provided if the derivation enabled.
|
||||
Must be provided if derivation is enabled.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
|
@ -284,3 +391,110 @@ only encrypt or decrypt using the named keys they need access to.
|
|||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /transit/rewrap/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/transit/rewrap/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">ciphertext</span>
|
||||
<span class="param-flags">required</span>
|
||||
The ciphertext to decrypt, provided as returned by encrypt.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">context</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The key derivation context, provided as base64 encoded.
|
||||
Must be provided if derivation is enabled.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"data": {
|
||||
"ciphertext": "vault:v2:abcdefgh"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /transit/datakey/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
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.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/transit/datakey/<plaintext|wrapped>/<name>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">plaintext|wrapped (path parameter)</span>
|
||||
<span class="param-flags">required</span>
|
||||
If `plaintext`, the plaintext key will be returned along with the
|
||||
ciphertext. If `wrapped`, only the ciphertext value will be returned.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">context</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The key derivation context, provided as base64 encoded.
|
||||
Must be provided if derivation is enabled.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">bits</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The number of bits in the desired key. Can be 128, 256, or 512; if not
|
||||
given, defaults to 256.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"data": {
|
||||
"plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=",
|
||||
"ciphertext": "vault:v1:abcdefgh"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
|
|
|||
Loading…
Reference in New Issue