Vaultproviderspec (#1)
* Initial version of Vault KMS Provider * Renamed image file to be consistent with spec name * Brought spec inline with EnvelopeTransformer interfaces in PR 49350 * Wrap at 80
This commit is contained in:
KK Sriramadhesikan
parent
f20eb8c175
commit
40fe163224
Binary file not shown.
|
After Width: | Height: | Size: 9.3 KiB |
|
|
@ -0,0 +1,302 @@
|
||||||
|
# Vault based KMS provider for envelope encryption of secrets in etcd3
|
||||||
|
|
||||||
|
## Abstract
|
||||||
|
|
||||||
|
Kubernetes, starting with the release 1.7, adds Alpha support ( via PRs
|
||||||
|
[41939](https://github.com/kubernetes/kubernetes/pull/41939) and
|
||||||
|
[46460](https://github.com/kubernetes/kubernetes/pull/46460)) to encrypt secrets
|
||||||
|
and resources in etcd3 via a configured Provider. This release supports three
|
||||||
|
providers viz. aesgcm, aescbc, secretbox. These providers store the encryption
|
||||||
|
key(s) locally in a server configuration file. The provider encrypts and
|
||||||
|
decrypts secrets in-process. Building upon these, a KMS provider framework with
|
||||||
|
an option to support different KMS providers like google cloud KMS is being
|
||||||
|
added via PRs [48574](https://github.com/kubernetes/kubernetes/pull/48575) and
|
||||||
|
[49350](https://github.com/kubernetes/kubernetes/pull/49350). The new KMS
|
||||||
|
provider framework uses an envelope encryption scheme.
|
||||||
|
|
||||||
|
|
||||||
|
This proposal adopts the KMS provider framework and adds a new KMS provider that
|
||||||
|
uses Hashicorp Vault with a transit backend, to encrypt and decrypt the DEK
|
||||||
|
stored in encrypted form in etcd3 along with encrypted secrets.
|
||||||
|
|
||||||
|
|
||||||
|
Vault is widely used for Data encryption and securely storing secrets.
|
||||||
|
Externalizing encryption/decryption of kubernetes secrets to vault provides
|
||||||
|
various benefits
|
||||||
|
|
||||||
|
* Choice of industry standard encryption algorithms and strengths without having
|
||||||
|
to implement specific providers for each (in K8S).
|
||||||
|
* Reduced risk of encryption key compromise.
|
||||||
|
* encryption key is stored and managed in Vault.
|
||||||
|
* encryption key does not need to leave the Vault.
|
||||||
|
* Vault provides ability to define access control suitable for a wide range of deployment scenarios and security needs.
|
||||||
|
* Vault provides In-built auditing of vault API calls.
|
||||||
|
* Ability for a customer already using Vault to leverage the instance to also
|
||||||
|
secure keys used to encrypt secrets managed within a Kubernetes cluster
|
||||||
|
* Separation of Kubernetes cluster management responsibilities from encryption key
|
||||||
|
management and administration allowing an organization to better leverage
|
||||||
|
competencies and skills within the DevOps teams.
|
||||||
|
|
||||||
|
Note, that the Vault Provider in this proposal
|
||||||
|
|
||||||
|
1. **requires** Vault transit backend.
|
||||||
|
2. supports a wide range of authentication backends supported by vault (see below
|
||||||
|
for exact list).
|
||||||
|
3. does not depend on specific storage backend or any other specific configuration.
|
||||||
|
|
||||||
|
This proposal assumes familiarity with Vault and the transit back-end.
|
||||||
|
|
||||||
|
## High level design
|
||||||
|
As with existing providers, the Vault based provider will implement the
|
||||||
|
interface ``envelope.Service``. Based on value of *name* in the KMS provider
|
||||||
|
configuration, the ``EnvelopeTransformer`` module will use an instance of the
|
||||||
|
Vault provider for decryption and encryption of DEK before storing and after
|
||||||
|
reading from the storage.
|
||||||
|
|
||||||
|
The KEK will be stored and managed in Vault backend. The Vault based provider
|
||||||
|
configured in KMS Transformer configuration will make REST requests to encrypt
|
||||||
|
and decrypt DEKs over a secure channel, if TLS is enabled. KMS Transformer will
|
||||||
|
store the DEKs in etcd in encrypted form along with encrypted secrets. As with
|
||||||
|
existing providers, encrypted DEKs will be stored with metadata used to identify
|
||||||
|
the provider and KEK to be used for decryption.
|
||||||
|
|
||||||
|
The provider will support following authentication back-ends
|
||||||
|
|
||||||
|
* Vault token based,
|
||||||
|
* TLS cert based,
|
||||||
|
* Vault AppRole based.
|
||||||
|
|
||||||
|
Deployers can choose an authentication mechanism best suited to their
|
||||||
|
requirements.
|
||||||
|
The provider will work with vault REST APIs and will not require Vault to be
|
||||||
|
configured or deployed in any specific way other than requiring a Transit
|
||||||
|
Backend.
|
||||||
|
|
||||||
|
### Diagram illustrating interfaces and implementations
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Pseudocode
|
||||||
|
#### Prefix Metadata
|
||||||
|
Every encrypted secret will have the following metadata prefixed.
|
||||||
|
``k8s:enc:kms:<api-version>:vault:len(<KEK-key-name>:<KEK-key-version>:<DEK
|
||||||
|
encrypted with KEK>):<KEK-key-name>:<KEK-key-version>:<DEK encrypted with KEK>``
|
||||||
|
|
||||||
|
* ``<api-version>`` represents api version in the providers configuration file.
|
||||||
|
* ``vault`` represents the KMS service *kind* value. It is a fixed value for Vault
|
||||||
|
based provider.
|
||||||
|
* ``KEK-key-name`` is determined from the vault service configuration in providers
|
||||||
|
configuration file
|
||||||
|
* ``KEK-key-version`` is an internal identifier used by vault to identify specific
|
||||||
|
key version used to encrypt and decrypt. Vault sends ``kek-key-version``
|
||||||
|
prefixed with encrypted data in the response to an encrypt request. The
|
||||||
|
``kek-key-version`` will be stored as part of prefix and returned back to Vault
|
||||||
|
during a decrypt request.
|
||||||
|
|
||||||
|
Of the above metadata,
|
||||||
|
|
||||||
|
* ``EnvelopeTransformer`` will add
|
||||||
|
``k8s:enc:kms:<api-version>:vault:len(<KEK-key-name>:<KEK-key-version>:<DEK
|
||||||
|
encrypted with KEK>)``
|
||||||
|
* while the ``vaultEnvelopeService`` will add
|
||||||
|
``<KEK-key-name>:<KEK-key-version>:<DEK encrypted with KEK>``.
|
||||||
|
|
||||||
|
|
||||||
|
#### For each write of DEK
|
||||||
|
``EnvelopeTransformer`` will write encrypted DEK along with encrypted secret in
|
||||||
|
etcd.
|
||||||
|
|
||||||
|
Here's the pseudocode for ``vaultEnvelopeService.encrypt()``, invoked on each
|
||||||
|
write of DEK.
|
||||||
|
|
||||||
|
KEY_NAME = <first key-name from vault provider config>
|
||||||
|
PLAIN_DEK = <value of DEK>
|
||||||
|
ENCRYPTED_DEK_WITH_KEY_VERSION = encrypt(base64(PLAIN_DEK), KEY_NAME)
|
||||||
|
|
||||||
|
// output from vault will have an extra prefix "vault" (other than key version) which will be stripped.
|
||||||
|
|
||||||
|
STORED_DEK = KEY_NAME:<ENCRYPTED_DEK_WITH_KEY_VERSION>
|
||||||
|
|
||||||
|
#### For each read of DEK
|
||||||
|
``EnvelopeTransformer`` will read encrypted DEK along with encrypted secret from
|
||||||
|
etcd
|
||||||
|
|
||||||
|
Here's the pseudocode ``vaultEnvelopeService.decrypt()`` invoked on each read of
|
||||||
|
DEK.
|
||||||
|
|
||||||
|
// parse the provider kind, key name and encrypted DEK prefixed with key version
|
||||||
|
KEY_NAME = //key-name from the prefix
|
||||||
|
ENCRYPTED_DEK_WITH_KEY_VERSION = //<key version>:<encrypted DEK> from the stored value
|
||||||
|
|
||||||
|
// add "vault" prefix to ENCRYPTED_DEK_WITH_KEY_VERSION as required by vault decrypt API
|
||||||
|
|
||||||
|
base64Encoded = decrypt(vault:ENCRYPTED_DEK_WITH_KEY_VERSION, KEY_NAME)
|
||||||
|
|
||||||
|
PLAIN_DEK = base64.Decode(base64Encoded)
|
||||||
|
|
||||||
|
#### Example
|
||||||
|
|
||||||
|
DEK = "the quick brown fox"
|
||||||
|
provider kind = "vault"
|
||||||
|
api version version = "v1"
|
||||||
|
Key name = "kube-secret-enc-key"
|
||||||
|
key version = v1
|
||||||
|
ciphertext returned from vault = vault:v1:aNOTZn0aUDMDbWAQL1E31tH/7zr7oslRjkSpRW0+BPdMfSJntyXZNCAwIbkTtn0=
|
||||||
|
prefixed DEK used to tag secrets = vault:kube-secret-enc-key:v1:aNOTZn0aUDMDbWAQL1E31tH/7zr7oslRjkSpRW0+BPdMfSJntyXZNCAwIbkTtn0=
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
No new configuration file or startup parameter will be introduced.
|
||||||
|
|
||||||
|
The vault provider will be specified in the existing configuration file used to
|
||||||
|
configure any of the encryption providers. The location of this configuration
|
||||||
|
file is identified by the existing startup parameter:
|
||||||
|
`--experimental-encryption-provider-config` .
|
||||||
|
|
||||||
|
Vault provider configuration will be identified by value "**vault**" for the
|
||||||
|
``name`` attribute in ``kms`` provider.
|
||||||
|
|
||||||
|
The actual configuration of the vault provider will be in a separate
|
||||||
|
configuration identified by the ``configfile`` attribute in the KMS provider.
|
||||||
|
|
||||||
|
Here is a sample configuration file with the vault provider configured:
|
||||||
|
|
||||||
|
kind: EncryptionConfig
|
||||||
|
apiVersion: v1
|
||||||
|
resources:
|
||||||
|
- resources:
|
||||||
|
- secrets
|
||||||
|
providers:
|
||||||
|
- kms:
|
||||||
|
name: vault
|
||||||
|
cachesize: 10
|
||||||
|
configfile: /home/myvault/vault-config.yaml
|
||||||
|
|
||||||
|
#### Minimal required Configuration
|
||||||
|
The Vault based Provider needs the following configuration elements, at a
|
||||||
|
minimum:
|
||||||
|
|
||||||
|
1. ``addr`` Vault service base endpoint eg. https://example.com:8200
|
||||||
|
2. ``key-names`` list of names of the keys in Vault to be used. eg: key-name:
|
||||||
|
kube-secret-enc-key.
|
||||||
|
|
||||||
|
Note : key name does not need to be changed if key is rotated in Vault, the
|
||||||
|
rotated key is identified by key version which is prefix to ciphertext.
|
||||||
|
|
||||||
|
A new key can be added in the list. Encryption will be done using the first key
|
||||||
|
in the list. Decryption can happen using any of the keys in the list based on
|
||||||
|
the prefix to the encrypted DEK stored in etcd
|
||||||
|
|
||||||
|
#### Authentication Configuration
|
||||||
|
##### Vault Server Authentication
|
||||||
|
|
||||||
|
For the Kubernetes cluster to authenticate the vault server, if TLS is enabled :
|
||||||
|
1. ``ca-cert`` location of x509 certificate to authenticate the vault server eg:
|
||||||
|
``/var/run/kubernetes/ssl/vault.crt``
|
||||||
|
|
||||||
|
##### Client Authentication Choices
|
||||||
|
|
||||||
|
For client authentication, one of following **must** be used: (provider will
|
||||||
|
reject the configuration if parameters for more than one authentication backends
|
||||||
|
are specified )
|
||||||
|
|
||||||
|
###### X509 based authentication
|
||||||
|
1. ``client-cert``: location of x509 certificate to authenticate kubernetes API
|
||||||
|
server to vault server eg. ``/var/run/kubernetes/ssl/valut-client-cert.pem``
|
||||||
|
2. ``client-key`` : location of x509 private key to authenticate kubernetes API
|
||||||
|
server to vault server eg. ``/var/run/kubernetes/ssl/vault-client-key.pem``
|
||||||
|
|
||||||
|
Here's a sample configuration file with ``client-cert``:
|
||||||
|
|
||||||
|
kind: EncryptionConfig
|
||||||
|
apiVersion: v1
|
||||||
|
resources:
|
||||||
|
- resources:
|
||||||
|
- secrets
|
||||||
|
providers:
|
||||||
|
- kms:
|
||||||
|
kind: vault
|
||||||
|
apiVersion: v1
|
||||||
|
cache-size: 100
|
||||||
|
config:
|
||||||
|
addr: https://localhost:8200
|
||||||
|
key-names:
|
||||||
|
- kube-secret-enc-key
|
||||||
|
ca-cert:/var/run/kubernetes/ssl/vault.crt
|
||||||
|
client-cert:/var/run/kubernetes/ssl/vault-client-cert.pem
|
||||||
|
client-key:/var/run/kubernetes/ssl/vault-client-key.pem
|
||||||
|
|
||||||
|
###### Vault token based authentication
|
||||||
|
1. ``token`` : limited access vault token required by kubernetes API sever to
|
||||||
|
authenticate itself while making requests to vault eg:
|
||||||
|
8dad1053-4a4e-f359-2eab-d57968eb277f
|
||||||
|
|
||||||
|
Here's a sample configuration file when using a Vault Token for authenticating
|
||||||
|
the Kubernetes cluster as a client to Vault:
|
||||||
|
|
||||||
|
kind: EncryptionConfig
|
||||||
|
apiVersion: v1
|
||||||
|
resources:
|
||||||
|
- resources:
|
||||||
|
- secrets
|
||||||
|
providers:
|
||||||
|
- kms:
|
||||||
|
kind: vault
|
||||||
|
apiVersion: v1
|
||||||
|
cache-size: 100
|
||||||
|
config:
|
||||||
|
addr: https://localhost:8200
|
||||||
|
key-names:
|
||||||
|
- kube-secret-enc-key
|
||||||
|
ca-cert:/var/run/kubernetes/ssl/vault.crt
|
||||||
|
token: 8dad1053-4a4e-f359-2eab-d57968eb277f
|
||||||
|
|
||||||
|
###### Vault AppRole based authentication
|
||||||
|
1. ``role-id`` : RoleID of the AppRole
|
||||||
|
2. ``secret-id`` : secret Id only if associated with the appRole.
|
||||||
|
|
||||||
|
Here's a sample configuration file with Vault AppRole
|
||||||
|
kind: EncryptionConfig
|
||||||
|
apiVersion: v1
|
||||||
|
resources:
|
||||||
|
- resources:
|
||||||
|
- secrets
|
||||||
|
providers:
|
||||||
|
- kms:
|
||||||
|
kind: vault
|
||||||
|
apiVersion: v1
|
||||||
|
cache-size: 100
|
||||||
|
config:
|
||||||
|
addr: https://localhost:8200
|
||||||
|
key-names:
|
||||||
|
- kube-secret-enc-key
|
||||||
|
ca-cert: /var/run/kubernetes/ssl/vault.crt
|
||||||
|
role-id: db02de05-fa39-4855-059b-67221c5c2f63
|
||||||
|
|
||||||
|
## Key Generation and rotation
|
||||||
|
The KEK is generated in Vault and rotated using direct API call or CLI to Vault
|
||||||
|
itself. The Key never leaves the vault.
|
||||||
|
|
||||||
|
Note that when a key is rotated, Vault does not allow to choose a different
|
||||||
|
encryption algorithm or key size. If a key for different encryption algorithm or
|
||||||
|
a different key size is desired, new key needs to be generated in Vault and the
|
||||||
|
corresponding key name be added in the configuration. Subsequent encryption will
|
||||||
|
be done using the first key in the list. Decryption can happen using any of the
|
||||||
|
keys in the list based on the prefix to the encrypted DEK.
|
||||||
|
|
||||||
|
## Backward compatibility
|
||||||
|
1. Unencrypted secrets and secrets encrypted using other non-KMS providers will
|
||||||
|
continue to be readable upon adding vault as a new KMS provider.
|
||||||
|
2. If a Vault KMS is added as first provider, the secrets created or modified
|
||||||
|
thereafter will be encrypted by vault provider.
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
1. KMS provider framework uses LRU cache to minimize the requests to KMS for
|
||||||
|
encryption and decryption of DEKs.
|
||||||
|
2. Note that there will be a request to KMS for every cache miss causing a
|
||||||
|
performance impact. Hence, depending on the cache size, there will be a
|
||||||
|
performance impact.
|
||||||
|
3. Response time.
|
||||||
|
4. will depend on choice of encryption algorithm and strength.
|
||||||
|
5. will depend on specific vault configurations like storage backend,
|
||||||
|
authentication mechanism, token polices etc.
|
||||||
Loading…
Reference in New Issue