Create new "previous-root" key purpose for root key migrations (#2639) (#2648)

* 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:
Johan Brandhorst-SatzkornandDan Heath authored and GitHub committed 2022-11-24 20:07:37 -05:00
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