mirror of https://github.com/hashicorp/boundary
Update security docs (#613)
Jeff Mitchell
6 years ago
committed by
GitHub
parent
b340a0f9ee
commit
6f36a1cab6
@ -0,0 +1,99 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Data Encryption
|
||||
sidebar_title: Data Encryption
|
||||
description: |-
|
||||
How Boundary secures data at rest
|
||||
---
|
||||
|
||||
# Data Security in Boundary
|
||||
|
||||
Boundary has multiple mechanisms to ensure secure end-to-end behavior of the
|
||||
system. A key part of this is [support for various Key Management
|
||||
Systems](/docs/configuration/kms) that protect the base encryption keys used for
|
||||
various functions. This page describes the various KMS key purposes that
|
||||
Boundary supports and how they are used within the system.
|
||||
|
||||
~> Boundary does not currently support rotation of its internal keys, but this
|
||||
will be supported in a future version. External keys can be rotated so long as
|
||||
the original keys remain available for decryption; full support for rotating
|
||||
these will come in a future version as well.
|
||||
|
||||
## The `root` KMS Key and Per-Scope KEK/DEKs
|
||||
|
||||
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.
|
||||
|
||||
The current scoped DEKs and their purposes are detailed below:
|
||||
|
||||
~> Management of these keys is handled entirely internally; the information
|
||||
provided in this section is purely for informational purposes.
|
||||
|
||||
* `database`: This is the general-purpose DEK used to encrypt sensitive or
|
||||
secret values within the database.
|
||||
|
||||
* `oplog`: This is used for encrypting oplog (operation log) values for the
|
||||
given scope.
|
||||
|
||||
* `tokens`: This is used for encrpyting tokens generated by auth methods within
|
||||
the given scope.
|
||||
|
||||
* `sessions`: This is used as a base key against which to derive
|
||||
session-specific encryption keys.
|
||||
|
||||
## The `worker-auth` KMS Key
|
||||
|
||||
The `worker-auth` KMS key is a key shared by the Controller and Worker in order
|
||||
to authenticate a Worker to the Controller. Specifics of this mechanism can be
|
||||
found on the [Connections/TLS page](/docs/concepts/security/connections-tls).
|
||||
|
||||
## The `recovery` KMS Key
|
||||
|
||||
The `recovery` KMS key is used for rescue/recovery operations that can be used
|
||||
by a client to authenticate almost any operation within Boundary. Its mechanism
|
||||
of operation is very similar to the `worker-auth` flow in terms of using a
|
||||
shared KMS between the client and the Controller for authentication. A nonce and
|
||||
creation time are included as an encrypted payload, formatted as a token and
|
||||
sent to the Controller. The time and nonce are used to ensure that a value
|
||||
cannot be replayed by an adversary, and also to ensure that each operation must
|
||||
be individually authenticated by a client so that revoking access to the KMS has
|
||||
an immediate result.
|
||||
|
||||
~> It is not required for this `kms` configuration block to exist in the
|
||||
Controller's configuration file. It's best practice to leave it out except when
|
||||
actually needed; then use change control capabilities to ensure that the
|
||||
configuration file modification is authorized. After it's no longer needed, the
|
||||
block should be removed.
|
||||
|
||||
On the client side, a user can use the `-recovery-config` flag with any
|
||||
operation on the CLI to specify a configuration file containing a suitable `kms`
|
||||
block. This functionality is also accessible via the Go SDK.
|
||||
|
||||
~> This mechanism cannot be used to authorize a session, as there is no user information attached to these requests. Requests authorized via this mechanism will show a user of `u_recovery`.
|
||||
|
||||
There are some other situations where this mechanism can be useful. For example,
|
||||
it is possible to use this mechanism, along with some defaults in the Terraform
|
||||
provider, to ensure that _everything_ in Boundary is created through Terraform,
|
||||
with the exception of resources that cannot themselves be deleted (that is, the
|
||||
built-in anonymous (`u_anon`), authenticated (`u_auth`), and recovery
|
||||
(`u_recovery`) users; and the `global` scope). By initializing Boundary with the
|
||||
options to skip creating default resources, Terraform can be used to create the
|
||||
specfici resources needed instead, with the `recovery` KMS used to authenticate
|
||||
setting up the initial authentication method(s).
|
||||
|
||||
## The `config` KMS Key
|
||||
|
||||
This key can be used to encrypt values within Boundary's configuration file. By
|
||||
sharing this block between Boundary and an operator, the operator can put
|
||||
sensitive or secret values (such as cloud API keys for KMSes) in Boundary's
|
||||
configuration file, run `boundary config encrypt` to encrypt the file, and then
|
||||
safely pass the file to a change control system. Only another operator or system
|
||||
with access to that KMS can decrypt the values. Boundary will check for a
|
||||
`config` KMS block on startup, and if it exists, it will decrypt any encrypted
|
||||
values found at startup time.
|
||||
Loading…
Reference in new issue