Addtl fixups

source/index.rst

@@ -68,10 +68,33 @@ such as versioning and replication.
 
       export MINIO_ROOT_USER_FILE=myminioaccesskey
       export MINIO_ROOT_PASSWORD_FILE=myminiosecretkey
-      export MINIO_KMS_SECRET_KEY=myminioencryptionkey
+      export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
 
       minio server /mnt/data
 
+   .. list-table::
+      :stub-columns: 1
+      :widths: 30 60
+      :width: 100%
+
+      * - :envvar:`MINIO_ROOT_USER_FILE`
+        - The :ref:`root user <minio-users-root>` access key. Replace the
+          sample value with a long, random, and unique string.
+
+      * - :envvar:`MINIO_ROOT_PASSWORD_FILE`
+        - The :ref:`root user <minio-users-root>` secret key. Replace the
+          sample value with a long, random, and unique string.
+
+      * - :envvar:`MINIO_KMS_SECRET_KEY`
+        - The encryption key for the MinIO IAM backend. Replace the
+          sample value with a 32-bit base-64 encoded value. For example,
+          use the following command to generate a random key:
+
+          .. code-block:: shell
+             :class: copyable
+
+             cat /dev/urandom`` | head -c 32 | base64 -
+
    MinIO by default listens on port ``9000``. Applications running on the
    same host can connect and perform S3 operations on the MinIO server
    using the ``http://localhost:9000`` url.
@@ -80,13 +103,6 @@ such as versioning and replication.
    MinIO server. Use :mc:`mc alias set` to update the ``myminio`` alias with
    the access key and secret key set on the MinIO server.
 
-   For complete documentation on the environment variables specified above, see
-   the corresponding reference documentation:
-
-   - :envvar:`MINIO_ROOT_USER_FILE`
-   - :envvar:`MINIO_ROOT_PASSWORD_FILE`
-   - :envvar:`MINIO_KMS_SECRET_KEY`
-
 3\) Configure Console User for MinIO
    Create a a :ref:`policy <minio-policy>` and :ref:`user <minio-users>` for
    supporting the :minio-git:`MinIO Console <console>`. The Console provides a

source/reference/minio-server/minio-server.rst

@@ -265,6 +265,22 @@ Key Management Service and Encryption
    See :minio-git:`KMS IAM/Config Encryption
    <minio/blob/master/docs/kms/IAM.md>` for more information.
 
+   Specify a 32-bit base-64 encrypted string in the following format:
+
+   ``<key-name>:<encryption-string>``
+
+   - Replace the ``<key-name>`` with any string. You must use this
+     key name if you later migrate to using a dedicated KMS for 
+     managing encryption keys.
+
+   - Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
+     For example:
+
+     .. code-block:: shell
+        :class: copyable
+
+        cat /dev/urandom | head -c 32 | base64 -
+
    Prior to :minio-release:`RELEASE.2021-04-22T15-44-28Z`, MinIO used the
    :ref:`root <minio-users-root>` user credentials for encrypting the backend. 
 
@@ -275,17 +291,18 @@ Key Management Service and Encryption
 
 .. envvar:: MINIO_KMS_KES_KEY_FILE
 
-   The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` 
+   The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` x.509
-   x.509 certificate to use when authenticating to the KES server. 
+   certificate to use when authenticating to the KES server. The KES server
-   The KES server requires clients to present their certificate for performing mutual TLS (mTLS).
+   requires clients to present their certificate for performing mutual TLS
+   (mTLS).
 
    See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>` 
    for more complete documentation on KES access control.
 
 .. envvar:: MINIO_KMS_KES_CERT_FILE
 
-   The x.509 certificate to present to the KES server. 
+   The x.509 certificate to present to the KES server. The KES server requires
-   The KES server requires clients to present their certificate and for performing mutual TLS (mTLS).
+   clients to present their certificate for performing mutual TLS (mTLS).
 
    The KES server computes an 
    :minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
@@ -299,10 +316,10 @@ Key Management Service and Encryption
 
 .. envvar:: MINIO_KMS_KES_KEY_NAME
 
-   The name of an external key at the Key Management System (KMS) to perform en/decryption operations
+   The name of an external key on the Key Management system (KMS) configured on
-   configured on the KES server. MinIO uses this key for supporting
+   the KES server and used for performing en/decryption operations. MinIO uses
-   server-side encryption of objects (SSE-S3) and MinIO backend encryption.
+   this key for supporting server-side encryption of objects (SSE-S3) and MinIO
-
+   backend encryption.
 
 Storage Class
 ~~~~~~~~~~~~~

source/security/IAM/iam-users.rst

@@ -86,19 +86,11 @@ MinIO deployments have a ``root`` user with access to all actions and resources
 on the deployment. When a :mc:`minio` server first starts, it sets the ``root``
 user credentials by checking the value of the following environment variables:
 
-- :envvar:`MINIO_ACCESS_KEY`
+- :envvar:`MINIO_ROOT_USER_FILE`
-- :envvar:`MINIO_SECRET_KEY`
+- :envvar:`MINIO_ROOT_PASSWORD_FILE`
 
-To rotate the ``root`` user credentials, set the following environment 
+Rotating the root user credentials requires updating either or both 
-variables and restart the :mc:`minio` server:
+variables for all MinIO servers in the deployment.
-
-- :envvar:`MINIO_ACCESS_KEY` to the new access key.
-- :envvar:`MINIO_SECRET_KEY` to the new secret key.
-- :envvar:`MINIO_ACCESS_KEY_OLD` to the old access key.
-- :envvar:`MINIO_SECRET_KEY_OLD` to the old secret key.
-
-After the :mc:`minio` server starts successfully, you can unset the
-:envvar:`MINIO_ACCESS_KEY_OLD` and :envvar:`MINIO_SECRET_KEY_OLD`. 
 
 When specifying the ``root`` access key and secret key, consider using *long,
 unique, and random* strings. Exercise all possible precautions in storing the
@@ -118,21 +110,58 @@ If these variables are unset, :mc:`minio` defaults to ``minioadmin`` and
 discourages* use of the default credentials regardless of deployment
 environment.
 
+MinIO :minio-release:`RELEASE.2021-04-22T15-44-28Z` and later deprecates the
+following variables used for setting or updating root user
+credentials:
+
+- :envvar:`MINIO_ACCESS_KEY` to the new access key.
+- :envvar:`MINIO_SECRET_KEY` to the new secret key.
+- :envvar:`MINIO_ACCESS_KEY_OLD` to the old access key.
+- :envvar:`MINIO_SECRET_KEY_OLD` to the old secret key.
+
 Create a User
 -------------
 
 Use the :mc-cmd:`mc admin user add` command to create a new user on the
 MinIO deployment:
 
+.. code-block:: shell
+   :class: copyable
+
+      mc admin user add ALIAS ACCESSKEY SECRETKEY
+
+- Replace :mc-cmd:`ALIAS <mc admin user add TARGET>` with the
+  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
+
+- Replace :mc-cmd:`ACCESSKEY <mc admin user add ACCESSKEY>` with the 
+  access key for the user. MinIO allows retrieving the access key after
+  user creation through the :mc-cmd:`mc admin user info` command.
+
+- Replace :mc-cmd:`SECRETKEY <mc admin user add SECRETKEY>` with the
+  secret key for the user. MinIO *does not* provide any method for retrieving
+  the secret key once set.
+
+Specify a unique, random, and long string for both the ``ACCESSKEY`` and 
+``SECRETKEY``. Your organization may have specific internal or regulatory
+requirements around generating values for use with access or secret keys. 
+
+After creating the user, use :mc-cmd:`mc admin policy set` to associate 
+a :ref:`minio-policy` to the new user. You can also use
+:mc-cmd:`mc admin group add` to add the user to a :ref:`minio-groups`.
+
 Delete a User
 -------------
 
 Use the :mc-cmd:`mc admin user remove` command to remove a user on a 
 MinIO deployment:
 
-Authenticate as a User
+.. code-block:: shell
-----------------------
+   :class: copyable
 
-ToDo: Examples of authenticating to a MinIO deployment with a created user. 
+   mc admin user remove ALIAS USERNAME
 
-Should have examples with `mc` and each of the SDKs. 
+- Replace :mc-cmd:`ALIAS <mc admin user remove TARGET>` with the
+  :mc-cmd:`alias <mc alias>` of the MinIO deployment.
+
+- Replace :mc-cmd:`USERNAME <mc admin user remove USERNAME>` with the name of
+  the user to remove.

source/tutorials/minio-installation.rst

@@ -58,21 +58,7 @@ procedure.
       products and services, and is not intended as a complete guide to the larger
       topic of TLS/SSL certificate creation and management.
 
-3\) Generate an Encryption Key for the MinIO Backend
+3\) Run the ``minio`` Server
-   Starting in the :minio-release:`RELEASE.2021-04-22T15-44-28Z` release, MinIO
-   requires a user-specified encryption key or Key Management System (KMS) for
-   encrypting the backend (users, groups, policies, and server configuration). 
-
-   Generate a 256-bit encryption key and encode it as a base64 string:
-
-   .. code-block:: shell
-      :class: copyable
-
-      cat /dev/urandom | head -c 32 | base64 -
-
-   Copy the value for use in the next step.
-
-4\) Run the ``minio`` Server
    Issue the following command on each host machine in the deployment. The
    following example assumes that:
 
@@ -87,7 +73,8 @@ procedure.
 
       export MINIO_ROOT_USER_FILE=minio-admin
       export MINIO_ROOT_PASSWORD_FILE=minio-secret-key-CHANGE-ME
-      export MINIO_KMS_SECRET_KEY=base64encoded256bitkey
+      export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
+
       minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data
 
    The example command breaks down as follows:
@@ -111,35 +98,51 @@ procedure.
         - The key to use for encrypting the MinIO backend (users, groups,
           policies, and server configuration).
 
-      * - ``https://minio{1...4}.example.com/``
+          Use the following format when specifying the encryption key:
+
+          ``<key-name>:<encryption-key>``
+   
+          - Replace the ``<key-name>`` with any string. You must use this
+            key name if you later migrate to using a dedicated KMS for 
+            managing encryption keys.
+
+          - Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
+            For example:
+
+            .. code-block:: shell
+               :class: copyable
+     
+               cat /dev/urandom | head -c 32 | base64 -
+
+      * - ``minio{1...4}.example.com/``
         - The DNS hostname of each server in the distributed deployment. 
 
+          The command uses MinIO expansion notation ``{x...y}`` to denote a
+          sequential series. Specifically, the hostname
+          ``https://minio{1...4}.example.com`` expands to:
+     
+          - ``https://minio1.example.com``
+          - ``https://minio2.example.com``
+          - ``https://minio3.example.com``
+          - ``https://minio4.example.com``
+
       * - ``/mnt/disk{1...4}/data``
         - The path to each disk on the host machine. 
 
           ``/data`` is an optional folder in which the ``minio`` server stores
           all information related to the deployment. 
 
+          The command uses MinIO expansion notation ``{x...y}`` to denote a sequential
+          series. Specifically,  ``/mnt/disk{1...4}/data`` expands to:
+         
+          - ``/mnt/disk1/data``
+          - ``/mnt/disk2/data``
+          - ``/mnt/disk3/data``
+          - ``/mnt/disk4/data``
+
           See :mc-cmd:`minio server DIRECTORIES` for more information on
           configuring the backing storage for the :mc:`minio server` process.
 
-   The command uses MinIO expansion notation ``{x...y}`` to denote a sequential
-   series. Specifically:
-
-   -  The hostname ``https://minio{1...4}.example.com`` expands to:
-
-      - ``https://minio1.example.com``
-      - ``https://minio2.example.com``
-      - ``https://minio3.example.com``
-      - ``https://minio4.example.com``
-
-   - ``/mnt/disk{1...4}/data`` expands to
-   
-      - ``/mnt/disk1/data``
-      - ``/mnt/disk2/data``
-      - ``/mnt/disk3/data``
-      - ``/mnt/disk4/data``
-
 4\) Connect to the Server
    Use the :mc-cmd:`mc alias set` command from a machine with connectivity to any
    hostname running the ``minio`` server. See :ref:`mc-install` for documentation
@@ -168,7 +171,7 @@ version of the ``minio`` server process:
    docker run -p 9000:9000 \
    -e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
    -e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-   -e "MINIO_KMS_SECRET_KEY=base64encoded256bitkey" \
+   -e "MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=" \
    -v /mnt/disk1:/disk1 \
    -v /mnt/disk2:/disk2 \
    -v /mnt/disk3:/disk3 \
@@ -196,12 +199,21 @@ The command uses the following options:
      - The key to use for encrypting the MinIO backend (S3 objects, users, groups,
        policies, and server configuration).
 
-       Replace this value with a 256-bit base64-encrypted string:
+       Use the following format when specifying the encryption key:
 
-       .. code-block:: shell
+       ``<key-name>:<encryption-key>``
-         :class: copyable
+
+       - Replace the ``<key-name>`` with any string. You must use this
+         key name if you later migrate to using a dedicated KMS for 
+         managing encryption keys.
+
+       - Replace ``<encryption-key>`` with a 32-bit base64 encoded value. 
+         For example:
+
+         .. code-block:: shell
+            :class: copyable
  
-         cat /dev/urandom | head -c 32 | base64 -
+            cat /dev/urandom | head -c 32 | base64 -
 
    * - ``-v /mnt/disk<int>:/disk<int>`` 
      - The path to each each disk the ``minio`` server uses. 
@@ -220,7 +232,7 @@ bleeding-edge version of the ``minio`` server process:
    docker run -p 9000:9000 \
    -e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
    -e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-   -e "MINIO_KMS_SECRET_KEY=base64encoded256bitkey" \
+   -e "MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=" \
    -v /mnt/disk1:/disk1 \
    -v /mnt/disk2:/disk2 \
    -v /mnt/disk3:/disk3 \
@@ -248,13 +260,29 @@ The command uses the following options:
      - The key to use for encrypting the MinIO backend (users, groups,
        policies, and server configuration).
 
-       Replace this value with a 256-bit base64-encrypted string:
+       Replace this value with a 32-bit base64-encrypted string:
 
        .. code-block:: shell
          :class: copyable
  
          cat /dev/urandom | head -c 32 | base64 -
 
+       Use the following format when specifying the encryption key:
+
+       ``<key-name>:<encryption-key>``
+
+       - Replace the ``<key-name>`` with any string. You must use this
+         key name if you later migrate to using a dedicated KMS for 
+         managing encryption keys.
+
+       - Replace ``<encryption-key>`` with a 32-bit base64 encoded value. 
+         For example:
+
+         .. code-block:: shell
+            :class: copyable
+
+            cat /dev/urandom | head -c 32 | base64 -
+
    * - ``-v /mnt/disk<int>:/disk<int>`` 
      - The path to each each disk the ``minio`` server uses. 
 
@@ -289,21 +317,7 @@ environments.
       products and services, and is not intended as a complete guide to the larger
       topic of TLS/SSL certificate creation and management.
 
-3\) Generate an Encryption Key for the MinIO Backend
+3\) Run the ``minio`` Server
-   Starting in the :minio-release:`RELEASE.2021-04-22T15-44-28Z` release, MinIO
-   requires a user-specified encryption key or Key Management System (KMS) for
-   encrypting the backend (users, groups, policies, and server configuration). 
-
-   Generate a 256-bit encryption key and encode it as a base64 string:
-
-   .. code-block:: shell
-      :class: copyable
-
-      cat /dev/urandom | head -c 32 | base64 -
-
-   Copy the value for use in the next step.
-
-4\) Run the ``minio`` Server
    Issue the following command to start the :program:`minio` server. The following
    example assumes the host machine has *at least* four disks, which is the minimum
    required number of disks to enable :ref:`erasure coding <minio-erasure-coding>`:
@@ -313,6 +327,8 @@ environments.
 
       export MINIO_ROOT_USER_FILE=minio-admin
       export MINIO_ROOT_PASSWORD_FILE=minio-secret-key-CHANGE-ME
+      export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
+
       minio server /mnt/disk{1...4}/data
 
    The example command breaks down as follows:
@@ -332,6 +348,26 @@ environments.
 
           Replace this value with a unique, random, and long string.
 
+      * - :envvar:`MINIO_KMS_SECRET_KEY`
+        - The key to use for encrypting the MinIO backend (users, groups,
+          policies, and server configuration).
+
+          Use the following format when specifying the encryption key:
+
+          ``<key-name>:<encryption-key>``
+   
+          - Replace the ``<key-name>`` with any string. You must use this
+            key name if you later migrate to using a dedicated KMS for 
+            managing encryption keys.
+
+          - Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
+            For example:
+
+            .. code-block:: shell
+               :class: copyable
+     
+               cat /dev/urandom | head -c 32 | base64 -
+
       * - ``/mnt/disk{1...4}/data``
         - The path to each disk on the host machine. 
 
@@ -341,13 +377,13 @@ environments.
           See :mc-cmd:`minio server DIRECTORIES` for more information on
           configuring the backing storage for the :mc:`minio server` process.
 
-   The command uses MinIO expansion notation ``{x...y}`` to denote a sequential
+          The command uses MinIO expansion notation ``{x...y}`` to denote a
-   series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
+          sequential series. Specifically, ``/mnt/disk{1...4}/data`` expands to:
-   
+            
-   - ``/mnt/disk1/data``
+          - ``/mnt/disk1/data``
-   - ``/mnt/disk2/data``
+          - ``/mnt/disk2/data``
-   - ``/mnt/disk3/data``
+          - ``/mnt/disk3/data``
-   - ``/mnt/disk4/data``
+          - ``/mnt/disk4/data``
 
 4\) Connect to the Server
    Use the :mc-cmd:`mc alias set` command from a machine with connectivity to