Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise “Encrypting Secret Data at Rest” #18810

Merged
merged 4 commits into from
Feb 6, 2020
Merged

Revise “Encrypting Secret Data at Rest” #18810

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
056c986
Drop reference to old Kubernetes versions
sftim Jan 22, 2020
6fc7d11
Tidy whitespace
sftim Jan 22, 2020
2533c1a
Add table caption
sftim Jan 22, 2020
1e6a404
Set metadata for required Kubernetes version
sftim Jan 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 9 additions & 18 deletions content/en/docs/tasks/administer-cluster/encrypt-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ reviewers:
- smarterclayton
title: Encrypting Secret Data at Rest
content_template: templates/task
min-kubernetes-server-version: 1.13
---

{{% capture overview %}}
Expand All @@ -13,9 +14,7 @@ This page shows how to enable and configure encryption of secret data at rest.

* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}

* Kubernetes version 1.13.0 or later is required

* etcd v3 or later is required
* etcd v3.0 or later is required

{{% /capture %}}

Expand All @@ -27,9 +26,6 @@ The `kube-apiserver` process accepts an argument `--encryption-provider-config`
that controls how API data is encrypted in etcd. An example configuration
is provided below.

Note:
The alpha version of the encryption feature prior to 1.13 used the `--experimental-encryption-provider-config` flag.

## Understanding the encryption at rest configuration.

```yaml
Expand Down Expand Up @@ -69,10 +65,6 @@ resources from storage each provider that matches the stored data attempts to de
order. If no provider can read the stored data due to a mismatch in format or secret key, an error
is returned which prevents clients from accessing that resource.

Note:
The alpha version of the encryption feature prior to 1.13 required to be configured with
`kind: EncryptionConfig` and `apiVersion: v1`.

{{< caution >}}
**IMPORTANT:** If any resource is not readable via the encryption config (because keys were changed),
the only recourse is to delete that key from the underlying etcd directly. Calls that attempt to
Expand All @@ -81,11 +73,12 @@ read that resource will fail until it is deleted or a valid decryption key is pr

### Providers:

{{< table caption="Providers for Kubernetes encryption at rest" >}}
Name | Encryption | Strength | Speed | Key Length | Other Considerations
-----|------------|----------|-------|------------|---------------------
`identity` | None | N/A | N/A | N/A | Resources written as-is without encryption. When set as the first provider, the resource will be decrypted as new values are written.
`aescbc` | AES-CBC with PKCS#7 padding | Strongest | Fast | 32-byte | The recommended choice for encryption at rest but may be slightly slower than `secretbox`.
`secretbox` | XSalsa20 and Poly1305 | Strong | Faster | 32-byte | A newer standard and may not be considered acceptable in environments that require high levels of review.
`secretbox` | XSalsa20 and Poly1305 | Strong | Faster | 32-byte | A newer standard and may not be considered acceptable in environments that require high levels of review.
`aesgcm` | AES-GCM with random nonce | Must be rotated every 200k writes | Fastest | 16, 24, or 32-byte | Is not recommended for use except when an automated key rotation scheme is implemented.
`kms` | Uses envelope encryption scheme: Data is encrypted by data encryption keys (DEKs) using AES-CBC with PKCS#7 padding, DEKs are encrypted by key encryption keys (KEKs) according to configuration in Key Management Service (KMS) | Strongest | Fast | 32-bytes | The recommended choice for using a third party tool for key management. Simplifies key rotation, with a new DEK generated for each encryption, and KEK rotation controlled by the user. [Configure the KMS provider](/docs/tasks/administer-cluster/kms-provider/)

Expand All @@ -95,12 +88,12 @@ is the first provider, the first key is used for encryption.
__Storing the raw encryption key in the EncryptionConfig only moderately improves your security posture, compared to no encryption.
Please use `kms` provider for additional security.__ By default, the `identity` provider is used to protect secrets in etcd, which
provides no encryption. `EncryptionConfiguration` was introduced to encrypt secrets locally, with a locally managed key.

Encrypting secrets with a locally managed key protects against an etcd compromise, but it fails to protect against a host compromise.
Since the encryption keys are stored on the host in the EncryptionConfig YAML file, a skilled attacker can access that file and
extract the encryption keys. This was a stepping stone in development to the `kms` provider, introduced in 1.10, and beta since 1.12. Envelope encryption
creates dependence on a separate key, not stored in Kubernetes. In this case, an attacker would need to compromise etcd, the
kubeapi-server, and the third-party KMS provider to retrieve the plaintext values, providing a higher level of security than
locally-stored encryption keys.
extract the encryption keys.

Envelope encryption creates dependence on a separate key, not stored in Kubernetes. In this case, an attacker would need to compromise etcd, the kubeapi-server, and the third-party KMS provider to retrieve the plaintext values, providing a higher level of security than locally-stored encryption keys.

## Encrypting your data

Expand Down Expand Up @@ -137,7 +130,7 @@ Your config file contains keys that can decrypt content in etcd, so you must pro
{{< /caution >}}


## Verifying that data is encrypted
## Verifying that data is encrypted

Data is encrypted when written to etcd. After restarting your `kube-apiserver`, any newly created or
updated secret should be encrypted when stored. To check, you can use the `etcdctl` command line
Expand Down Expand Up @@ -217,5 +210,3 @@ and restart all `kube-apiserver` processes. Then run the command `kubectl get se
to force all secrets to be decrypted.

{{% /capture %}}