* Update go-kms-wrapping dependency * Apply changes suggested by Jeff * Fix listener test * Add note about config fix to CHANGELOG * Review comments Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com>
This commit is contained in:
1 parent
58f86936e7
commit
df02501dcc
15 files changed
+271
-25
No files matched your search
@@ -31,10 +31,10 @@ Following best practices of using different encryption keys for different
|
||||
purposes, Boundary has a number of encryption keys generated within each scope.
|
||||
|
||||
The `root` KMS key acts as a KEK (Key Encrypting Key) for the scope-specific
|
||||
KEKs (also referred to as the scope's `root` key). The scope's `root` KEK and
|
||||
the various DEKs (Data Encryption Keys) are created when a scope is created. The
|
||||
DEKs are encrypted with the scope's `root` KEK, and this is in turn encrypted
|
||||
with the KMS key marked for `root` purpose.
|
||||
KEKs (also referred to as the scope's `root` key). The scope's `root` KEK
|
||||
and the various DEKs (Data Encryption Keys) are created when a scope is created.
|
||||
The DEKs are encrypted with the scope's `root` KEK, and this is in turn
|
||||
encrypted with the KMS key marked for the `root` purpose.
|
||||
|
||||
The current scoped DEKs and their purposes are detailed below:
|
||||
|
||||
@@ -55,6 +55,60 @@ provided in this section is purely for informational purposes.
|
||||
- `sessions`: This is used as a base key against which to derive
|
||||
session-specific encryption keys.
|
||||
|
||||
### Key version lifecycle Management
|
||||
|
||||
You can control the lifecycles of the per-scope KEK and DEKs via the CLI or
|
||||
API using the key endpoints under the scopes section. To rotate all the keys
|
||||
in a scope, use the `rotate-keys` endpoint:
|
||||
|
||||
```shell-session
|
||||
$ boundary scopes rotate-keys -scope-id p_A4jfDjZ9jf
|
||||
```
|
||||
|
||||
This endpoint creates new key versions for all keys in the scope
|
||||
`p_A4jfDjZ9jf`, and makes these key versions the active key versions for
|
||||
encrypting new data. The previous key version(s) will continue to be used for
|
||||
decrypting existing data. You can use the `-rewrap` flag to immediately rewrap
|
||||
all DEK versions with the new KEK version. Otherwise, the DEK versions remain
|
||||
encrypted by the prior KEK version from when they were created.
|
||||
|
||||
To list all keys in a scope and their versions, use the `list-keys` endpoint:
|
||||
|
||||
```shell-session
|
||||
$ boundary scopes list-keys -scope-id p_A4jfDjZ9jf
|
||||
```
|
||||
|
||||
To destroy a key version, use the `destroy-key-version` endpoint:
|
||||
|
||||
```shell-session
|
||||
$ boundary scopes destroy-key-version -scope-id p_A4jfDjZ9jf -key-version-id kdkv_tr6ZN8opYr
|
||||
```
|
||||
|
||||
The latest key version cannot be destroyed, so if you want to destroy the
|
||||
latest key version, you will need to call the `rotate-keys` endpoint first,
|
||||
to create a new set of key versions. The `oplog` purpose key versions also
|
||||
cannot be destroyed at this time.
|
||||
|
||||
Destroying a key version sometimes requires background work before it can be
|
||||
completed. This is because DEK versions that currently encrypt data
|
||||
necessitate re-encrypting that data with the latest DEK version for each
|
||||
purpose before they can be deleted. You can monitor the progress of this
|
||||
re-encryption job via the `list-key-destruction-jobs` endpoint:
|
||||
|
||||
```shell-session
|
||||
$ boundary scopes list-key-version-destruction-jobs -scope-id p_A4jfDjZ9jf
|
||||
```
|
||||
|
||||
Once the job disappears from this list, the associated key version will have
|
||||
been destroyed and any existing data will have been re-encrypted.
|
||||
|
||||
## The `previous-root` KMS key <sup>OSS Only</sup>
|
||||
|
||||
The `previous-root` KMS key is used when migrating to a new `root` key. Adding
|
||||
the `previous-root` KMS key to your configuration informs the Controller to use
|
||||
it for decrypting the existing information in the database, allowing you to
|
||||
rotate and rewrap the KEKs to complete the migration to the new root key.
|
||||
|
||||
## The `worker-auth` KMS Key <sup>OSS Only</sup>
|
||||
|
||||
The `worker-auth` KMS key is a key shared by the Controller and Worker in order
|
||||
|
||||
Reference in new issue
Block a user