Document vault in prod mode instead of dev mode (#7928)

docs/kms/README.md

@@ -14,15 +14,15 @@ MinIO supports two different KMS concepts:
 - Direct KMS master keys:
    MinIO can also be configured to directly use a master key specified by the environment variable `MINIO_SSE_MASTER_KEY`.
    Direct master keys are useful if the storage backend is not on the same machine as the MinIO server, e.g.,
-   if network drives or MinIO gateway is used and an external KMS would cause too much management overhead.  
+   if network drives or MinIO gateway is used and an external KMS would cause too much management overhead.
-   
+
    Note: KMS master keys are mainly for testing purposes. It's not recommended to use them for production deployments.
    Further if the MinIO server machine is ever compromised, then the master key must also be treated as compromised.
 
-**Important:**  
+**Important:**
 If multiple MinIO servers are configured as [gateways](https://github.com/minio/minio/blob/master/docs/gateway/README.md)
 pointing to the *same* backend - for example the same NAS storage - then the KMS configuration **must** be the same for
-all gateways. Otherwise one gateway may not be able to decrypt objects created by another gateway. It is the operators' 
+all gateways. Otherwise one gateway may not be able to decrypt objects created by another gateway. It is the operators'
 responsibility to ensure consistency.
 
 ## Get started
@@ -36,47 +36,135 @@ Either use Hashicorp Vault as external KMS or specify a master key directly depe
 
 #### 2.1 Setup Hashicorp Vault
 
-Here is a sample quick start for configuring vault with a transit backend and Approle with correct policy 
+Here is a sample quick start for configuring vault with a transit backend and Approle with correct policy
 
 MinIO requires the following Vault setup:
 - The [transit backend](https://www.vaultproject.io/api/secret/transit/index.html) configured with a named encryption key-ring
 - [AppRole](https://www.vaultproject.io/docs/auth/approle.html) based authentication with read/update policy for transit backend. In particular, read and update policy are required for the [Generate Data Key](https://www.vaultproject.io/api/secret/transit/index.html#generate-data-key) endpoint and [Decrypt Data](https://www.vaultproject.io/api/secret/transit/index.html#decrypt-data) endpoint.
 
-**2.1.1 Start Vault server in dev mode**
+**2.1.1 Start Vault server**
 
-In dev mode, Vault server runs in-memory and starts unsealed. Note that running Vault in dev mode is insecure and any data stored in the Vault is lost upon restart.
+Vault requires access to `mlock` syscall by default. Use `setcap` to give the Vault executable the ability to use the `mlock` syscall without running the process as root.  To do so run:
+```
+sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
+```
 
+Create `vault-config.json` to use file backend and start the server.
 ```
-vault server -dev
+cat > vault-config.json <<EOF
+{
+  "api_addr": "http://127.0.0.1:8200",
+  "backend": {
+    "file": {
+      "path": "vault/file"
+    }
+  },
+  "default_lease_ttl": "168h",
+  "max_lease_ttl": "720h",
+  "listener": {
+    "tcp": {
+      "address": "0.0.0.0:8200",
+      "tls_disable": true
+    }
+  },
+  "ui": true
+}
+EOF
+
+vault server -config vault-config.json
 ```
 
-**2.1.2 Set up vault transit backend and create an app role**
+> NOTE: In this example we use `"tls_disable": true` for demonstration purposes only,
+> in production setup you should generate proper TLS certificates by specifying
+> - [`tls_cert_file`](https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_cert_file)
+> - [`tls_key_file`](https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_key_file)
+
+
+**2.1.2 Initialize vault and unseal it**
 
 ```
+export VAULT_ADDR='http://127.0.0.1:8200'
+vault operator init
+Unseal Key 1: eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT
+Unseal Key 2: 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2
+Unseal Key 3: cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF
+Unseal Key 4: /fTPpec5fWpGqWHK+uhnnTNMQyAbl5alUi4iq2yNgyqj
+Unseal Key 5: UPdDVPto+H6ko+20NKmagK40MOskqOBw4y/S51WpgVy/
+
+Initial Root Token: s.zaU4Gbcu0Wh46uj2V3VuUde0
+
+Vault is initialized with 5 key shares and a key threshold of 3. Please securely
+distribute the key shares printed above. When the Vault is re-sealed,
+restarted, or stopped, you must supply at least 3 of these keys to unseal it
+before it can start servicing requests.
+
+Vault does not store the generated master key. Without at least 3 key to
+reconstruct the master key, Vault will remain permanently sealed!
+
+It is possible to generate new unseal keys, provided you have a quorum of
+existing unseal keys shares. See "vault operator rekey" for more information.
+```
+
+Use any of the previously generated keys to unseal the vault
+```
+vault operator unseal eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT
+vault operator unseal 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2
+vault operator unseal cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF
+Key             Value
+---             -----
+Seal Type       shamir
+Initialized     true
+Sealed          false  ---> NOTE: vault is unsealed
+Total Shares    5
+Threshold       3
+Version         1.1.3
+Cluster Name    vault-cluster-3f084948
+Cluster ID      8c92e999-7062-4da6-4434-0fc05f34824d
+HA Enabled      false
+```
+
+Obtain root token from the `vault operator init` output above. It is displayed as `Initial Root Token: s.zaU4Gbcu0Wh46uj2V3VuUde0`
+
+**2.1.3 Set up vault transit backend and create an app role**
+```
+export VAULT_TOKEN=s.zaU4Gbcu0Wh46uj2V3VuUde0
+
+vault auth enable approle    # enable approle style auth
+vault secrets enable transit  # enable transit secrets engine
+# define an encryption key-ring for the transit path
+vault write -f  transit/keys/my-minio-key
+
 cat > vaultpolicy.hcl <<EOF
-path "transit/datakey/plaintext/my-minio-key" { 
+path "transit/datakey/plaintext/my-minio-key" {
   capabilities = [ "read", "update"]
 }
-path "transit/decrypt/my-minio-key" { 
+path "transit/decrypt/my-minio-key" {
   capabilities = [ "read", "update"]
 }
-path "transit/encrypt/my-minio-key" { 
+path "transit/encrypt/my-minio-key" {
   capabilities = [ "read", "update"]
 }
 
 EOF
 
-export VAULT_ADDR='http://127.0.0.1:8200'
+# define a policy for AppRole to access transit path
-vault auth enable approle    # enable approle style auth
+vault policy write minio-policy ./vaultpolicy.hcl
-vault secrets enable transit  # enable transit secrets engine
+
-vault write -f  transit/keys/my-minio-key  #define a encryption key-ring for the transit path
+# period indicates it is renewable if token is renewed before the period is over
-vault policy write minio-policy ./vaultpolicy.hcl  #define a policy for AppRole to access transit path
+vault write auth/approle/role/my-role token_num_uses=0  secret_id_num_uses=0  period=5m
-vault write auth/approle/role/my-role token_num_uses=0  secret_id_num_uses=0  period=5m # period indicates it is renewable if token is renewed before the period is over
+
 # define an AppRole
 vault write auth/approle/role/my-role policies=minio-policy # apply policy to role
 vault read auth/approle/role/my-role/role-id  # get Approle ID
-vault write -f auth/approle/role/my-role/secret-id
+Key        Value
+---        -----
+role_id    8c03926c-6c51-7a1d-cf7d-62e48ab8d6d7
 
+vault write -f auth/approle/role/my-role/secret-id
+Key                   Value
+---                   -----
+secret_id             edd8738c-6efe-c226-74f9-ef5b66e119d7
+secret_id_accessor    57d1db64-6350-c321-4a3e-fc6aeb7d00b6
 ```
 
 The AppRole ID, AppRole Secret Id, Vault endpoint and Vault key name can now be used to start minio server with Vault as KMS.
@@ -85,10 +173,10 @@ The AppRole ID, AppRole Secret Id, Vault endpoint and Vault key name can now be
 
 You'll need the Vault endpoint, AppRole ID, AppRole SecretID and encryption key-ring name defined in step 2.1.2
 
-```sh
+```
-export MINIO_SSE_VAULT_APPROLE_ID=9b56cc08-8258-45d5-24a3-679876769126
+export MINIO_SSE_VAULT_APPROLE_ID=8c03926c-6c51-7a1d-cf7d-62e48ab8d6d7
-export MINIO_SSE_VAULT_APPROLE_SECRET=4e30c52f-13e4-a6f5-0763-d50e8cb4321f
+export MINIO_SSE_VAULT_APPROLE_SECRET=edd8738c-6efe-c226-74f9-ef5b66e119d7
-export MINIO_SSE_VAULT_ENDPOINT=https://vault-endpoint-ip:8200
+export MINIO_SSE_VAULT_ENDPOINT=http://vault-endpoint-ip:8200
 export MINIO_SSE_VAULT_KEY_NAME=my-minio-key
 export MINIO_SSE_VAULT_AUTH_TYPE=approle
 minio server ~/export
@@ -130,13 +218,13 @@ minio gateway s3
 A KMS master key consists of a master-key ID (CMK) and the 256 bit master key encoded as HEX value separated by a `:`.
 A KMS master key can be specified directly using:
 
-```sh
+```
 export MINIO_SSE_MASTER_KEY=my-minio-key:6368616e676520746869732070617373776f726420746f206120736563726574
 ```
 
 Please use your own master key. A random master key can be generated using e.g. this command on Linux/Mac/BSD* systems:
 
-```sh
+```
 head -c 32 /dev/urandom | xxd -c 32 -ps
 ```
 
@@ -149,18 +237,18 @@ MinIO can also enable auto-encryption **if** a valid KMS configuration is specif
 encrypted objects. Auto-Encryption, if enabled, ensures that all uploaded objects are encrypted using the specified
 KMS configuration.
 
-Auto-Encryption is useful especially if the MinIO operator wants to ensure that objects are **never** stored in 
+Auto-Encryption is useful especially if the MinIO operator wants to ensure that objects are **never** stored in
 plaintext - for example if sensitive data is stored on public cloud storage.
 
 To enable auto-encryption set the environment variable to `on`:
 
-```sh
+```
 export MINIO_SSE_AUTO_ENCRYPTION=on
 ```
 
 To verify auto-encryption, use the `mc` command:
 
-```sh
+```
 mc cp test.file myminio/crypt/
 test.file:              5 B / 5 B  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100.00% 337 B/s 0s
 mc stat myminio/crypt/test.file
@@ -171,8 +259,7 @@ Encrypted :
 ```
 
 Note: Auto-Encryption only affects non-SSE-C requests since objects uploaded using SSE-C are already encrypted
-and S3 only allows either SSE-S3 or SSE-C but not both for the same object.   
+and S3 only allows either SSE-S3 or SSE-C but not both for the same object.
-
 
 # Explore Further
 

docs/kms/vault-config.json

@@ -0,0 +1,17 @@
+{
+  "api_addr": "http://127.0.0.1:8200",
+  "backend": {
+    "file": {
+      "path": "vault/file"
+    }
+  },
+  "default_lease_ttl": "168h",
+  "max_lease_ttl": "720h",
+  "listener": {
+    "tcp": {
+      "address": "0.0.0.0:8200",
+      "tls_disable": true
+    }
+  },
+  "ui": true
+}