From b6f9b24b30a45b4acf52256597db95244dbfc0c7 Mon Sep 17 00:00:00 2001
From: Eco <41090896+eco-minio@users.noreply.github.com>
Date: Fri, 14 Dec 2018 16:21:41 -0800
Subject: [PATCH] Small corrections and example for auto-encryption (#6982)

---
 docs/kms/README.md | 48 ++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/docs/kms/README.md b/docs/kms/README.md
index ecb25b5e1..d0ff6b458 100644
--- a/docs/kms/README.md
+++ b/docs/kms/README.md
@@ -1,28 +1,29 @@
 # KMS Quickstart Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io)
 
-Minio uses a key-management-system (KMS) to support SSE-S3. If a client requests SSE-S3 or auto-encryption
-is enabled the Minio server encrypts each object with an unique object key which is protected by a master key
-managed by the KMS. Usually many/all object keys are protected by a single master key.
+Minio uses a key-management-system (KMS) to support SSE-S3. If a client requests SSE-S3, or auto-encryption
+is enabled, the Minio server encrypts each object with an unique object key which is protected by a master key
+managed by the KMS. Usually all object keys are protected by a single master key.
 
 Minio supports two different KMS concepts:
  - External KMS:
    Minio can be configured to use an external KMS i.e. [Hashicorp Vault](https://www.vaultproject.io/).
    An external KMS decouples Minio as storage system from key-management. An external KMS can
-   be managed by a dedicated security team and allows to grant/deny access to (certain) objects
-   by en/disabling the corresponding master keys on demand.
-   However, an external KMS causes configuration and management overhead. 
- - Direct KMS master keys:
-   Minio can also be configured to directly use a master key specified by the ENV. 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.  
+   be managed by a dedicated security team and allows you to grant/deny access to (certain) objects
+   by enabling or disabling the corresponding master keys on demand.
+
+- 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.  
+   
    Note: If the Minio server machine is ever compromised, then the master key must also be 
    treated as compromised.
 
 **Important:**  
-If multiple minio server 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 - than the KMS configuration **must** be equal for
-all gateways. Otherwise one gateway may not be able to decrypt objects created by another gateway. It's the operators 
-responsibility to ensure that.
+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' 
+responsibility to ensure consistency.
 
 ## Get started
 
@@ -44,6 +45,7 @@ Minio requires the following Vault setup:
 **2.1.1 Start Vault server in dev mode**
 
 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 server -dev
 ```
@@ -92,13 +94,13 @@ export MINIO_SSE_VAULT_AUTH_TYPE=approle
 minio server ~/export
 ```
 
-Optionally set `MINIO_SSE_VAULT_CAPATH` to a directory of PEM-encoded CA cert files to use mTLS for client-server authentication.
+Optionally, set `MINIO_SSE_VAULT_CAPATH` to a directory of PEM-encoded CA cert files to use mTLS for client-server authentication.
 
 ```
 export MINIO_SSE_VAULT_CAPATH=/home/user/custom-certs
 ```
 
-Optionally set `MINIO_SSE_VAULT_NAMESPACE` if AppRole and Transit Secrets engine have been scoped to Vault Namespace
+An additional option is to set `MINIO_SSE_VAULT_NAMESPACE` if AppRole and Transit Secrets engine have been scoped to Vault Namespace
 
 ```
 export MINIO_SSE_VAULT_NAMESPACE=ns1
@@ -130,12 +132,24 @@ KMS configuration.
 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 either set the ENV. variable: 
+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
+Name      : test.file
+...
+Encrypted :
+  X-Amz-Server-Side-Encryption: AES256
+```
+
 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.