oyd
/
minio
6
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update KMS guide to work with latest KES changes (#9498)

Browse Source 
This commit updates the KMS guide to reflect the
latest changes in KES. Based on internal design
meetings we made some adjustments to the overall
KES configuration.
This commit ensures that the KMS guide contains
a working KES demo-setup with Vault.
master
Andreas Auernhammer 5 years ago committed by GitHub
parent 83ccae6c8b
commit d1c8e9f31b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 104 additions and 113 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 217
      docs/kms/README.md

217
docs/kms/README.md
Unescape View File

@ -11,49 +11,26 @@ managed by the KMS.
## Architecture and Concepts ## Architecture and Concepts
The KMS decouples MinIO as an application-facing storage system from the secure key storage and The KMS decouples MinIO as an application-facing storage system from the secure key storage and
may be managed by a dedicated security team. In general, the MinIO-KMS infrastructure looks like this: may be managed by a dedicated security team. MinIO supports commonly-used KMS implementations, like
[Hashicorp Vault](https://www.vaultproject.io/) via our [KES project](https://github.com/minio/kes).
KES makes it possible to scale your KMS horizontally with your storage infrastructure (MinIO clusters).
In general, the MinIO-KMS infrastructure looks like this:
``` ```
+-------+ +-----+ ┌─────────┐ ┌────────────┐ ┌─────────┐
| MinIO +-------+ KMS | │ MinIO ├─────────┤ KES Server ├─────────┤ KMS │
+-------+ +-----+ └─────────┘ └────────────┘ └─────────┘
``` ```
If you scale your storage infrastructure to multiple MinIO clusters your architecture should look like this: When you scale your storage infrastructure to multiple MinIO clusters your architecture should look like this:
``` ```
+-------+ +-------+ ┌────────────┐
| MinIO +----+ +----+ MinIO | │ ┌──────────┴─┬─────╮ ┌────────────┐
+-------+ | +-----+ | +-------+ └─┤ ┌──────────┴─┬───┴──────────┤ ┌──────────┴─┬─────────────────╮
+---+ KMS +---+ └─┤ ┌──────────┴─┬─────┬──────┴─┤ KES Server ├─────────────────┤
+-------+ | +-----+ | +-------+ └─┤ MinIO ├─────╯ └────────────┘ ┌────┴────┐
| MinIO +----+ +----+ MinIO | └────────────┘ │ KMS │
+-------+ +-------+ └─────────┘
``` ```
MinIO supports commonly-used KMS implementations, like [AWS-KMS](https://aws.amazon.com/kms/) or
[Hashicorp Vault](https://www.vaultproject.io/) via our [KES project](https://github.com/minio/kes/wiki).
KES makes it possible to scale your KMS horizontally with your storage infrastructure (MinIO clusters).
Therefore, it wraps around the KMS implementation like this:
```
+-------+ +-------+
| MinIO | | MinIO |
+---+---+ +---+---+
| |
+----+-------------------------+----+---- KMS
| | | |
| +--+--+ +--+--+ |
| | KES +--+ +--+ KES | |
| +-----+ | +-------+ | +-----+ |
| +--+ Vault +--+ |
| +-----+ | +-------+ | +-----+ |
| | KES +--+ +--+ KES | |
| +--+--+ +--+--+ |
| | | |
+----+-------------------------+----+---- KMS
| |
+---+---+ +---+---+
| MinIO | | MinIO |
+-------+ +-------+
```
Observe that all MinIO clusters only have a connection to "their own" KES instance and no direct access to Vault (as one possible KMS implementation). Observe that all MinIO clusters only have a connection to "their own" KES instance and no direct access to Vault (as one possible KMS implementation).
Each KES instance will handle all encrypton/decryption requests made by "its" MinIO cluster such that the central KMS implementation does not have to handle Each KES instance will handle all encrypton/decryption requests made by "its" MinIO cluster such that the central KMS implementation does not have to handle
a lot of traffic. Instead, each KES instance will use the central KMS implementation as secure key store and fetches the required master keys from it. a lot of traffic. Instead, each KES instance will use the central KMS implementation as secure key store and fetches the required master keys from it.
@ -77,7 +54,7 @@ This guide shows how to set up three different servers on the same machine:
### 1 Prerequisites ### 1 Prerequisites
Install MinIO, KES and Vault. For MinIO take a look at the [MinIO quickstart guide](https://docs.min.io/docs/minio-quickstart-guide). Install MinIO, KES and Vault. For MinIO take a look at the [MinIO quickstart guide](https://docs.min.io/docs/minio-quickstart-guide).
Then download the [latest KES binary](https://github.com/minio/kes/releases/latest/) and the [latest Vault binary](https://github.com/hashicorp/vault/releases/latest/) Then [install KES](https://github.com/minio/kes#install) and download the [latest Vault binary](https://www.vaultproject.io/downloads)
for your OS and platform. for your OS and platform.
### 2 Generate TLS certificates ### 2 Generate TLS certificates
@ -88,30 +65,44 @@ TLS connections between MinIO, KES and Vault. Therefore, we need to generate at
#### 2.1 Generate a TLS certificate for Vault #### 2.1 Generate a TLS certificate for Vault
To generate a new private key for Vault's certificate run the following openssl command: To generate a new private key for Vault's certificate run the following openssl command:
``` ```sh
openssl ecparam -genkey -name prime256v1 | openssl ec -out vault-tls.key openssl ecparam -genkey -name prime256v1 | openssl ec -out vault-tls.key
``` ```
Then generate a new TLS certificate for the private/public key pair via: Then generate a new TLS certificate for the private/public key pair via:
``` ```sh
openssl req -new -x509 -days 365 -key vault-tls.key -out vault-tls.crt -subj "/C=US/ST=state/L=location/O=organization/CN=localhost" openssl req -new -x509 -days 365 \
``` -key vault-tls.key \
> You may want to adjust the X.509 subject (`-subj` parameter). Note that this is a self-signed certificate. For production deployments -out vault-tls.crt \
> this certificate should be issued by a CA. -subj "/C=/ST=/L=/O=/CN=localhost" \
-addext "subjectAltName = IP:127.0.0.1"
```
> You can ignore output messages like: req: No value provided for Subject Attribute C, skipped.
> OpenSSL just tells you that you haven't specified a country, state, a.s.o for the certificate subject.
> You may want to adjust the X.509 subject (`-subj` parameter) and subject alternative name (SAN).
> Note that this is a self-signed certificate. For production deployments this certificate should be
> issued by a CA.
#### 2.2 Generate a TLS certificate for KES #### 2.2 Generate a TLS certificate for KES
To generate a new private key for KES's certificate run the following openssl command: To generate a new private key for KES's certificate run the following openssl command:
``` ```sh
openssl ecparam -genkey -name prime256v1 | openssl ec -out kes-tls.key openssl ecparam -genkey -name prime256v1 | openssl ec -out kes-tls.key
``` ```
Then generate a new TLS certificate for the private/public key pair via: Then generate a new TLS certificate for the private/public key pair via:
``` ```sh
openssl req -new -x509 -days 365 -key kes-tls.key -out kes-tls.crt -subj "/C=US/ST=state/L=location/O=organization/CN=localhost" openssl req -new -x509 -days 365 \
``` -key kes-tls.key \
> You may want to adjust the X.509 subject (`-subj` parameter). Note that this is a self-signed certificate. For production deployments -out kes-tls.crt \
> this certificate should be issued by a CA. -subj "/C=/ST=/L=/O=/CN=localhost" \
-addext "subjectAltName = IP:127.0.0.1"
```
> You can ignore output messages like: req: No value provided for Subject Attribute C, skipped.
> OpenSSL just tells you that you haven't specified a country, state, a.s.o for the certificate subject.
> You may want to adjust the X.509 subject (`-subj` parameter) and subject alternative name (SAN).
> Note that this is a self-signed certificate. For production deployments this certificate should be
> issued by a CA.
#### 2.3 Generate a TLS certificate for MinIO (Optional) #### 2.3 Generate a TLS certificate for MinIO (Optional)
@ -125,12 +116,12 @@ Checkout the [MinIO TLS guide](https://docs.min.io/docs/how-to-secure-access-to-
On unix-like systems, Vault uses the `mlock` syscall to prevent the OS from writing in-memory data On unix-like systems, Vault uses the `mlock` syscall to prevent the OS from writing in-memory data
to disk (swapping). Therefore, you should give the Vault executable the ability to use the `mlock` to disk (swapping). Therefore, you should give the Vault executable the ability to use the `mlock`
syscall without running the process as root. To do so run: syscall without running the process as root. To do so run:
``` ```sh
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
``` ```
Then create the Vault config file: Then create the Vault config file:
``` ```sh
cat > vault-config.json <<EOF cat > vault-config.json <<EOF
{ {
"api_addr": "https://127.0.0.1:8200", "api_addr": "https://127.0.0.1:8200",
@ -156,14 +147,14 @@ EOF
> backend - like [etcd](https://www.vaultproject.io/docs/configuration/storage/etcd/) or [consul](https://learn.hashicorp.com/vault/operations/ops-vault-ha-consul). > backend - like [etcd](https://www.vaultproject.io/docs/configuration/storage/etcd/) or [consul](https://learn.hashicorp.com/vault/operations/ops-vault-ha-consul).
Finally, start the Vault server via: Finally, start the Vault server via:
``` ```sh
vault server -config vault-config.json vault server -config vault-config.json
``` ```
#### 3.1 Initialize and unseal Vault #### 3.1 Initialize and unseal Vault
In a separate terminal window set the `VAULT_ADDR` env. variable to your Vault server: In a separate terminal window set the `VAULT_ADDR` env. variable to your Vault server:
``` ```sh
export VAULT_ADDR='https://127.0.0.1:8200' export VAULT_ADDR='https://127.0.0.1:8200'
``` ```
@ -172,7 +163,7 @@ certificate. When Vault serves a TLS certificate that has been issued by a CA th
by your machine - e.g. Let's Encrypt - then you don't need to run this command. by your machine - e.g. Let's Encrypt - then you don't need to run this command.
Then initialize Vault via: Then initialize Vault via:
``` ```sh
vault operator init vault operator init
``` ```
@ -203,12 +194,12 @@ existing unseal keys shares. See "vault operator rekey" for more information.
``` ```
Now, set the env. variable `VAULT_TOKEN` to the root token printed by the command before: Now, set the env. variable `VAULT_TOKEN` to the root token printed by the command before:
``` ```sh
export VAULT_TOKEN=s.zaU4Gbcu0Wh46uj2V3VuUde0 export VAULT_TOKEN=s.zaU4Gbcu0Wh46uj2V3VuUde0
``` ```
Then use any of the previously generated key shares to unseal Vault. Then use any of the previously generated key shares to unseal Vault.
``` ```sh
vault operator unseal eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT vault operator unseal eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT
vault operator unseal 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2 vault operator unseal 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2
vault operator unseal cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF vault operator unseal cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF
@ -221,7 +212,7 @@ and able to process requests.
The cryptographic master keys (but not the object encryption keys) will be stored The cryptographic master keys (but not the object encryption keys) will be stored
at Vault. Therefore, we need to enable Vault's K/V backend. To do so run: at Vault. Therefore, we need to enable Vault's K/V backend. To do so run:
``` ```sh
vault secrets enable kv vault secrets enable kv
``` ```
@ -229,7 +220,7 @@ vault secrets enable kv
Since we want connect one/multiple KES server to Vault later, we have to enable Since we want connect one/multiple KES server to Vault later, we have to enable
AppRole authentication. To do so run: AppRole authentication. To do so run:
``` ```sh
vault auth enable approle vault auth enable approle
``` ```
@ -237,7 +228,7 @@ vault auth enable approle
The following policy determines how an application (i.e. KES server) can interact The following policy determines how an application (i.e. KES server) can interact
with Vault. with Vault.
``` ```sh
cat > minio-kes-policy.hcl <<EOF cat > minio-kes-policy.hcl <<EOF
path "kv/minio/*" { path "kv/minio/*" {
capabilities = [ "create", "read", "delete" ] capabilities = [ "create", "read", "delete" ]
@ -251,7 +242,7 @@ EOF
> and security requirements. > and security requirements.
Then we upload the policy to Vault: Then we upload the policy to Vault:
``` ```sh
vault policy write minio-key-policy ./minio-kes-policy.hcl vault policy write minio-key-policy ./minio-kes-policy.hcl
``` ```
@ -262,23 +253,23 @@ The application (i.e. KES server) will authenticate to Vault via the AppRole rol
and secret ID and is only allowed to perform operations granted by the specific policy. and secret ID and is only allowed to perform operations granted by the specific policy.
So, we first create a new role for our KES server: So, we first create a new role for our KES server:
``` ```sh
vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m
``` ```
Then we bind a policy to the role: Then we bind a policy to the role:
``` ```sh
vault write auth/approle/role/kes-role policies=minio-key-policy vault write auth/approle/role/kes-role policies=minio-key-policy
``` ```
Finally, we request an AppRole role ID and secret ID from Vault. Finally, we request an AppRole role ID and secret ID from Vault.
First, the role ID: First, the role ID:
``` ```sh
vault read auth/approle/role/kes-role/role-id vault read auth/approle/role/kes-role/role-id
``` ```
Then the secret ID: Then the secret ID:
``` ```sh
vault write -f auth/approle/role/kes-role/secret-id vault write -f auth/approle/role/kes-role/secret-id
``` ```
> We are only interested in the `secret_id` - not in the `secret_id_accessor`. > We are only interested in the `secret_id` - not in the `secret_id_accessor`.
@ -288,7 +279,7 @@ vault write -f auth/approle/role/kes-role/secret-id
Similar to Vault, KES uses the `mlock` syscall on linux systems to prevent the OS from writing in-memory Similar to Vault, KES uses the `mlock` syscall on linux systems to prevent the OS from writing in-memory
data to disk (swapping). Therefore, you should give the KES executable the ability to use the `mlock` data to disk (swapping). Therefore, you should give the KES executable the ability to use the `mlock`
syscall without running the process as root. To do so run: syscall without running the process as root. To do so run:
``` ```sh
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes)) sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
``` ```
@ -299,7 +290,7 @@ The KES server will accept/reject the connection attempt and applies policies ba
Therefore, each MinIO cluster needs a X.509 TLS certificate for client authentication. You can create a Therefore, each MinIO cluster needs a X.509 TLS certificate for client authentication. You can create a
(self-signed) certificate by running: (self-signed) certificate by running:
``` ```sh
kes tool identity new MinIO --key=minio.key --cert=minio.cert --time=8760h kes tool identity new MinIO --key=minio.key --cert=minio.cert --time=8760h
``` ```
> Note that *MinIO* is the [subject name](https://en.wikipedia.org/wiki/X.509#Structure_of_a_certificate). > Note that *MinIO* is the [subject name](https://en.wikipedia.org/wiki/X.509#Structure_of_a_certificate).
@ -307,7 +298,7 @@ kes tool identity new MinIO --key=minio.key --cert=minio.cert --time=8760h
> recommend to get a TLS certificate for client authentication that has been issued by a CA. > recommend to get a TLS certificate for client authentication that has been issued by a CA.
To get the identity of a X.509 certificate run: To get the identity of a X.509 certificate run:
``` ```sh
kes tool identity of minio.cert kes tool identity of minio.cert
``` ```
> This command works with any (valid) X.509 certificate - regardless how it has been created - and > This command works with any (valid) X.509 certificate - regardless how it has been created - and
@ -319,56 +310,56 @@ kes tool identity of minio.cert
#### 4.2 Create the KES config file #### 4.2 Create the KES config file
Now, we can create the KES config file and start the KES server. Now, we can create the KES config file and start the KES server.
``` ```yaml
cat > kes-config.toml <<EOF # The TCP address (ip:port) for the KES server to listen on.
# The address:port of the kes server - i.e. on the local machine. address: 0.0.0.0:7373
address = "127.0.0.1:7373"
tls:
[tls] key: kes-tls.key
key = "./kes-tls.key" cert: kes-tls.crt
cert = "./kes-tls.crt"
policy:
[policy.minio] minio:
paths = [ paths:
"/v1/key/create/minio-*", - /v1/key/create/minio-*
"/v1/key/generate/minio-*", - /v1/key/generate/minio-*
"/v1/key/decrypt/minio-*" - /v1/key/decrypt/minio-*
] identities:
identities = [ "dd46485bedc9ad2909d2e8f9017216eec4413bc5c64b236d992f7ec19c843c5f" ] - dd46485bedc9ad2909d2e8f9017216eec4413bc5c64b236d992f7ec19c843c5f
[cache.expiry] cache:
all = "5m" expiry:
unused = "20s" any: 5m0s
unused: 20s
[keystore.vault]
address = "https://127.0.0.1:8200" # The Vault endpoint - i.e. https://127.0.0.1:8200 keys:
name = "minio" # The domain resp. prefix at Vault's K/V backend vault:
endpoint: https://127.0.0.1:8200 # The Vault endpoint - i.e. https://127.0.0.1:8200
[keystore.vault.approle] prefix: minio # The domain resp. prefix at Vault's K/V backend
id = "" # Your AppRole Role ID
secret = "" # Your AppRole Secret ID approle:
retry = "15s" # Duration until the server tries to re-authenticate after connection loss. id: "" # Your AppRole Role ID
secret: "" # Your AppRole Secret ID
[keystore.vault.tls] retry: 15s # Duration until the server tries to re-authenticate after connection loss.
ca = "./vault-tls.crt" # Since we use self-signed certificates
tls:
[keystore.vault.status] ca: vault-tls.crt # Since we use self-signed certificates
ping = "10s"
status:
EOF ping: 10s
``` ```
> Please change the value of `identities` under `policy.minio` to the identity of your `minio.cert`. > Please change the value of `identities` in the `policy` section to the identity of your `minio.cert`.
> Also, insert the AppRole role ID and secret ID that you have created previously during the Vault setup. > Also, insert the AppRole role ID and secret ID that you have created previously during the Vault setup.
> You can find a documented config file with all available parameters [here](https://github.com/minio/kes/blob/master/server-config.toml). > You can find a documented config file with all available parameters [here](https://github.com/minio/kes/blob/master/server-config.yaml).
Finally, start the KES server via: Finally, start the KES server via:
``` ```
kes server --config=kes-config.toml --mlock --root=disabled --mtls-auth=ignore kes server --config=kes-config.yaml --mlock --root=disabled --auth=off
``` ```
> Note that we effectively disable the special *root* identity since we don't need it. > Note that we effectively disable the special *root* identity since we don't need it.
> For more information about KES identities checkout: [KES Identities](https://github.com/minio/kes/wiki#identities) > For more information about the KES access control model and identities checkout:
> Further, note that we pass `--mtls-auth=ignore` since the client X.509 certificate > [KES Concepts](https://github.com/minio/kes/wiki/Concepts). Further, note that we
> is a self-signed certificate. > disable `--auth=off` since the client X.509 certificate is a self-signed certificate.
#### 4.3 Create a new master key #### 4.3 Create a new master key

Write Preview
Loading…
Cancel
Save