Restructure Security Docs

Further refinement

Andreas fixups

source/_static/css-style.css

@@ -116,6 +116,10 @@ body div.left li.toctree-l2 {
    margin: 10px 0 10px 0;
 }
 
+body div.left li.toctree-l3 {
+   margin: 10px 0 10px 0;
+}
+
 body div.left div.searchformwrapper {
    margin-top: 25px;
 }

source/bare-metal/minio-baremetal-overview.rst

@@ -70,13 +70,13 @@ The example command breaks down as follows:
    :width: 100%
 
    * - :envvar:`MINIO_ACCESS_KEY`
-     - The access key for the :ref:`root <minio-auth-authz-root>` user.
+     - The access key for the :ref:`root <minio-users-root>` user.
 
        Replace this value with a unique, random, and long string. 
 
    * - :envvar:`MINIO_SECRET_KEY`
      - The corresponding secret key to use for the 
-       :ref:`root <minio-auth-authz-root>` user.
+       :ref:`root <minio-users-root>` user.
 
        Replace this value with a unique, random, and long string.
 
@@ -189,13 +189,13 @@ The example command breaks down as follows:
    :width: 100%
 
    * - :envvar:`MINIO_ACCESS_KEY`
-     - The access key for the :ref:`root <minio-auth-authz-root>` user.
+     - The access key for the :ref:`root <minio-users-root>` user.
 
        Replace this value with a unique, random, and long string. 
 
    * - :envvar:`MINIO_SECRET_KEY`
      - The corresponding secret key to use for the 
-       :ref:`root <minio-auth-authz-root>` user.
+       :ref:`root <minio-users-root>` user.
 
        Replace this value with a unique, random, and long string.
 
@@ -267,7 +267,7 @@ version of the ``minio`` server process:
 The command uses the following options:
 
 - ``-e MINIO_ACCESS_KEY`` and ``-e MINIO_SECRET_KEY`` for configuring the
-   :ref:`root <minio-auth-authz-root>` user credentials.
+   :ref:`root <minio-users-root>` user credentials.
 
 - ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio``
    server uses.
@@ -295,7 +295,7 @@ bleeding-edge version of the ``minio`` server process:
 The command uses the following options:
 
 - ``MINIO_ACCESS_KEY`` and ``MINIO_SECRET_KEY`` for configuring the
-   :ref:`root <minio-auth-authz-root>` user credentials.
+   :ref:`root <minio-users-root>` user credentials.
 
 - ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio`` 
    server uses. 

source/index.rst

@@ -22,7 +22,7 @@ Users deploying onto a Kubernetes cluster should start with our
    /minio-features/overview
    /bare-metal/minio-baremetal-overview
    /kubernetes/minio-kubernetes-overview
-   /security/minio-security
+   /security/security-overview
    /minio-cli/minio-mc
    /minio-cli/minio-mc-admin
    /minio-server/minio-server

source/minio-cli/minio-mc-admin/mc-admin-groups.rst

@@ -19,9 +19,9 @@ The :mc-cmd:`mc admin group` command manages groups on a MinIO deployment.
 
 .. end-mc-admin-groups-desc
 
-A :ref:`group <minio-auth-authz-groups>` is a collection of :ref:`users
+A :ref:`group <minio-groups>` is a collection of :ref:`users
-<minio-auth-authz-users>`. Each group can have one or more assigned
+<minio-users>`. Each group can have one or more assigned
-:ref:`policies <minio-auth-authz-pbac-policies>` that explicitly list the
+:ref:`policies <minio-policy>` that explicitly list the
 actions and resources to which group members are allowed or denied access.
 Groups provide a simplified method for managing shared permissions among users
 with common access patterns and workloads. 
@@ -40,7 +40,7 @@ MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
 users who have successfully *authenticated* to the deployment. Each policy
 includes rules that dictate the allowed or denied actions/resources on the
 deployment. You can assign one or more :ref:`policies
-<minio-auth-authz-pbac-policies>` to a group. Users with membership in the
+<minio-policy>` to a group. Users with membership in the
 group inherit the group's assigned policies. A user's total set of permissions
 includes their explicitly assigned policies *and* any policies inherited
 via group membership.
@@ -49,8 +49,8 @@ Newly created groups have *no* policies by default. To configure a group's
 assigned policies, use the :mc-cmd:`mc admin policy set` command.
 
 For more information on MinIO users and groups, see
-:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For 
+:ref:`minio-users` and :ref:`minio-groups`. For 
-more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
+more information on MinIO policies, see :ref:`minio-policy`.
 
 .. admonition:: ``Deny`` overrides ``Allow``
    :class: note
@@ -84,25 +84,16 @@ Quick Reference
 
 :mc-cmd:`mc admin group enable TARGET GROUPNAME <mc admin group enable>`
    Enables a group on the MinIO deployment. Users can only inherit
-   :ref:`policies <minio-auth-authz-pbac-policies>` assigned to an enabled group.
+   :ref:`policies <minio-policy>` assigned to an enabled group.
 
 :mc-cmd:`mc admin group disable TARGET GROUPNAME <mc admin group disable>`
    Disables a group on the MinIO deployment. Users cannot inherit :ref:`policies
-   <minio-auth-authz-pbac-policies>` assigned to a disabled group.
+   <minio-policy>` assigned to a disabled group.
 
 Syntax
 ------
 
-:mc-cmd:`mc admin group` has the following syntax:
+.. mc-cmd:: add
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin group [SUBCOMMAND] [ARGUMENTS]
-
-:mc-cmd:`mc admin group` supports the following subcommands:
-
-.. mc-cmd:: mc admin group add
    :fullpath:
 
    Adds an existing user to the group. The command creates the group if it
@@ -134,12 +125,12 @@ Syntax
       deployment. Use :mc-cmd:`mc admin user list` to review the available
       users on the deployment. 
 
-.. mc-cmd:: mc admin group info
+.. mc-cmd:: info
    :fullpath:
 
    Returns details for the group on the target deployment, such as all
-   :ref:`users <minio-auth-authz-users>` with membership in the group and the
+   :ref:`users <minio-users>` with membership in the group and the
-   assigned :ref:`policies <minio-auth-authz-pbac-policies>`. The command has
+   assigned :ref:`policies <minio-policy>`. The command has
    the following syntax:
 
    .. code-block:: shell
@@ -158,7 +149,7 @@ Syntax
 
       The name of the group.
 
-.. mc-cmd:: mc admin group list
+.. mc-cmd:: list
    :fullpath:
 
    List all groups on the target MinIO deployment. The command has the
@@ -176,12 +167,12 @@ Syntax
       The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
       which to retrieve groups.
 
-.. mc-cmd:: mc admin group remove
+.. mc-cmd:: remove
    :fullpath:
 
    Removes a group on the target MinIO deployment. Removing a group does *not*
-   remove any users with membership in the group. Use :mc-cmd:`mc admin user
+   remove any users with membership in the group. Use 
-   remove` to remove users from a group. 
+   :mc-cmd:`mc admin user remove` to remove users from a group. 
    
    The command has the following syntax:
 
@@ -205,7 +196,7 @@ Syntax
    :fullpath:
 
    Enables the group on the target MinIO deployment. Users can only inherit
-   :ref:`policies <minio-auth-authz-pbac-policies>` from an enabled group.
+   :ref:`policies <minio-policy>` from an enabled group.
    Groups are enabled on creation by default. The command has the following
    syntax:
 
@@ -229,7 +220,7 @@ Syntax
    :fullpath:
 
    Disables the group on the target MinIO deployment. Users cannot inherit
-   :ref:`policies <minio-auth-authz-pbac-policies>` from a disabled group. The
+   :ref:`policies <minio-policy>` from a disabled group. The
    command has the following syntax:
 
    .. code-block:: shell

source/minio-cli/minio-mc-admin/mc-admin-policy.rst

@@ -23,52 +23,7 @@ documents to define rules for accessing resources on a MinIO server.
 
 For complete documentation on MinIO PBAC, including policy document JSON
 structure and syntax, see
-:doc:`/security/minio-authentication-authorization`.
+:ref:`minio-auth-authz-overview`.
-
-Quick Reference
----------------
-
-:mc-cmd:`mc admin policy add TARGET POLICYNAME POLICYFILE <mc admin policy add>`
-   Creates a new policy on the target MinIO deployment. 
-
-   .. code-block:: shell
-      :class: copyable
-
-      mc admin policy add play myNewPolicy /path/to/policy.json
-
-:mc-cmd:`mc admin policy list TARGET <mc admin policy list>`
-   Lists the available policies on the target MinIO deployment.
-
-   .. code-block:: shell
-      :class: copyable
-      
-      mc admin policy list play
-
-:mc-cmd:`mc admin policy info TARGET POLICYNAME <mc admin policy info>`
-   Returns the policy in JSON format from the target MinIO deployment.
-
-   .. code-block:: shell
-      :class: copyable
-
-      mc admin policy info play myNewPolicy
-
-:mc-cmd:`mc admin policy set TARGET POLICYNAME user=|group= <mc admin policy set>`
-   Associates a policy to a user or group on the target MinIO deployment.
-
-   .. code-block:: shell
-      :class: copyable
-
-      mc admin policy set play myNewPolicy user=myMinioUser
-
-      mc admin policy set play myNewGroupPolicy group=myMinioGroup
-
-:mc-cmd:`mc admin policy remove TARGET POLICYNAME <mc admin policy remove>`
-   Removes a policy from the target MinIO deployment.
-
-   .. code-block:: shell
-      :class: copyable
-
-      mc admin policy remove play myNewPolicy
 
 Examples
 --------
@@ -320,7 +275,7 @@ Syntax
       as a comma-separated list.
 
       MinIO deployments include the following :ref:`built-in policies
-      <minio-auth-authz-pbac-built-in>` policies by default:
+      <minio-policy-built-in>` policies by default:
 
       - :userpolicy:`readonly` 
       - :userpolicy:`readwrite`

source/minio-cli/minio-mc-admin/mc-admin-user.rst

@@ -36,7 +36,7 @@ MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
 users who have successfully *authenticated* to the deployment. Each policy
 includes rules that dictate the allowed or denied actions/resources on the
 deployment. You can assign one or more :ref:`policies
-<minio-auth-authz-pbac-policies>` to a User. Users *also* inherit the policies
+<minio-policy>` to a User. Users *also* inherit the policies
 of any groups of which they are members. A user's total set of permissions
 includes their explicitly assigned policies *and* any policies inherited via
 group membership.
@@ -55,8 +55,8 @@ Each user's total set of permissions consists of their explicitly assigned
 permission *and* the inherited permissions from each of their assigned groups.
 
 For more information on MinIO users and groups, see
-:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For 
+:ref:`minio-users` and :ref:`minio-groups`. For 
-more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
+more information on MinIO policies, see :ref:`minio-policy`.
 
 .. admonition:: ``Deny`` overrides ``Allow``
    :class: note

source/minio-cli/minio-mc.rst

@@ -114,7 +114,7 @@ unsuccessful, check each of the following:
   S3 service. The user must have permission to perform actions on the
   service. 
   
-  For MinIO deployments, see :doc:`/security/minio-authentication-authorization`
+  For MinIO deployments, see :ref:`minio-auth-authz-overview`
   for more information on user access permissions. For other S3-compatible
   services, defer to the documentation for that service.
 

source/minio-cli/minio-mc/mc-encrypt.rst

@@ -20,7 +20,7 @@ bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts
 objects using the specified SSE mode.
 
 For more information on configuring SSE, see
-:doc:`/security/minio-security-server-side-encryption`.
+:ref:`minio-sse`
 
 .. end-mc-encrypt-desc
 

source/minio-server/minio-server.rst

@@ -262,7 +262,7 @@ Root Credentials
 
 .. envvar:: MINIO_ACCESS_KEY
 
-   The access key for the :ref:`root <minio-auth-authz-root>` user. 
+   The access key for the :ref:`root <minio-users-root>` user. 
 
    .. warning::
 
@@ -275,7 +275,7 @@ Root Credentials
 
 .. envvar:: MINIO_SECRET_KEY
 
-   The secret key for the :ref:`root <minio-auth-authz-root>` user.
+   The secret key for the :ref:`root <minio-users-root>` user.
 
    .. warning::
 
@@ -288,7 +288,7 @@ Root Credentials
 
 .. envvar:: MINIO_ACCESS_KEY_OLD
 
-   Used for rotating the :ref:`root <minio-auth-authz-root>` user access
+   Used for rotating the :ref:`root <minio-users-root>` user access
    key.
 
    Restart the :mc:`minio server` process with *all* of the following
@@ -306,7 +306,7 @@ Root Credentials
 
 .. envvar:: MINIO_SECRET_KEY_OLD
 
-   Used for rotating the :ref:`root <minio-auth-authz-root>` user secret
+   Used for rotating the :ref:`root <minio-users-root>` user secret
    key.
 
    Restart the :mc:`minio server` process with *all* of the following

source/security/IAM/iam-groups.rst

@@ -0,0 +1,80 @@
+.. _minio-groups:
+
+======
+Groups
+======
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+A *group* is a collection of :ref:`users <minio-users>`. Each group
+can have one or more assigned :ref:`policies <minio-policy>`
+that explicitly list the actions and resources to which group members are
+allowed or denied access.
+
+For example, consider the following groups. Each group is assigned a
+:ref:`built-in policy <minio-policy-built-in>` or supported
+:ref:`policy action <minio-policy-actions>`. Each group also has one or
+more assigned users. Each user's total set of permissions consists of their
+explicitly assigned permission *and* the inherited permissions from each of
+their assigned groups. MinIO by default *denies* access to any resource or
+operation not explicitly allowed by a user's assigned or inherited policies.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+   :width: 100%
+
+   * - Group
+     - Policy
+     - Members
+
+   * - ``Operations``
+     - | :userpolicy:`readwrite` on ``finance`` bucket
+       | :userpolicy:`readonly` on ``audit`` bucket
+     
+     - ``john.doe``, ``jane.doe``
+
+   * - ``Auditing``
+     - | :userpolicy:`readonly` on ``audit`` bucket
+     - ``jen.doe``, ``joe.doe``
+
+   * - ``Admin``
+     - :policy-action:`admin:*`
+     - ``greg.doe``, ``jen.doe``
+
+Groups provide a simplified method for managing shared permissions among
+users with common access patterns and workloads. Client's *cannot* authenticate
+to a MinIO deployment using a group as an identity.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
+   on the same action or resource. For example, if a user has an explicitly
+   assigned policy with an ``Allow`` rule for an action/resource while one of
+   its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+Create a Group
+--------------
+
+Use the :mc-cmd:`mc admin group add` command to add a user to a group. 
+MinIO implicitly creates the group if it does not already exist. You cannot
+create empty groups:
+
+Delete a Group
+--------------
+
+Use the :mc-cmd:`mc admin group remove` command to remove a group:

source/security/IAM/iam-policies.rst

@@ -1,8 +1,8 @@
-.. _minio-auth-authz-overview:
+.. _minio-policy:
 
-================================
+========
-Authentication and Authorization
+Policies
-================================
+========
 
 .. default-domain:: minio
 
@@ -13,205 +13,33 @@ Authentication and Authorization
 Overview
 --------
 
-*Authentication* is the process of verifying the identity of a connecting
+A *policy* is a document that describes the resources and operations to which
-client. MinIO authentication requires providing user credentials in the form of
+a MinIO :ref:`user <minio-users>` or the members of a :ref:`group 
-an access key (username) and corresponding secret key (password). The MinIO
+<minio-groups>` have access. 
-deployment only grants access *if*:
 
-- The access key corresponds to a user on the deployment, *and*
+MinIO uses Policy-Based Access Control (PBAC) to define the *authorized*
-- The secret key corresponds to the specified access key.
+resources and operations to which a :ref:`user <minio-users>` or members of a
+:ref:`group <minio-groups>` have access. 
 
-*Authorization* is the process of restricting the actions and resources the
+MinIO by default *denies* access to any
-authenticated client can perform on the deployment. MinIO uses Policy-Based
+resource or operation not explicitly allowed by a user's assigned or inherited
-Access Control (PBAC), where each policy describes one or more rules that
+policies.
-outline the permissions of a user or group of users. MinIO supports a subset of
-:iam-docs:`IAM actions and conditions
-<reference_policies_actions-resources-contextkeys.html>` when creating policies.
-By default, MinIO *denies* access to actions or resources not explicitly
-referenced in a user's assigned or inherited policies.
 
-- For more information on MinIO user management, see 
+MinIO PBAC uses AWS IAM-compatible JSON
-  :ref:`minio-auth-authz-users`.
+syntax for defining policies. For example, MinIO can use IAM policies designed
+for use with AWS S3 or S3-compatible services.
 
-- For more information on MinIO group management, see
+The MinIO documentation makes a best-effort to cover IAM-specific behavior and
-  :ref:`minio-auth-authz-groups`.
+functionality. Consider deferring to the :iam-docs:`IAM documentation <>` for
+more complete documentation on IAM, IAM policies, or IAM JSON syntax.
 
-- For more information on MinIO policy creation, see
+.. _minio-policy-built-in:
-  :ref:`minio-auth-authz-pbac-policies`.
-
-.. _minio-auth-authz-users:
-
-Users
------
-
-A *user* is an identity with associated privileges on a MinIO deployment. Each
-user consists of a unique access key (username) and corresponding secret key
-(password).  The access key and secret key support *authentication* on the MinIO
-deployment, similar to a username and password. Clients must specify both a
-valid access key (username) and the corresponding secret key (password) to
-access the MinIO deployment. 
-
-Each user can have one or more assigned :ref:`policies
-<minio-auth-authz-pbac-policies>` that explicitly list the actions and resources
-to which the user is allowed or denied access. Policies support *authorization*
-of operations on the MinIO deployment, such that clients can only perform
-an operation if the user's assigned policies allow access to both the operation
-*action* and the target *resources*.
-
-For example, consider the following table of users. Each user is assigned
-a :ref:`built-in policy <minio-auth-authz-pbac-built-in>` or
-a supported :ref:`action <minio-auth-authz-pbac-actions>`. The table
-describes a subset of operations a client could perform if authenticated
-as that user:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 20 40 40
-   :width: 100%
-
-   * - User
-     - Policy
-     - Operations
-
-   * - ``Operations``
-     - | :userpolicy:`readwrite` on ``finance`` bucket
-       | :userpolicy:`readonly` on ``audit`` bucket
-     
-     - | ``PUT`` and ``GET`` on ``finance`` bucket.
-       | ``PUT`` on ``audit`` bucket
-
-   * - ``Auditing``
-     - | :userpolicy:`readonly` on ``audit`` bucket
-     - ``GET`` on ``audit`` bucket
-
-   * - ``Admin``
-     - :policy-action:`admin:*`
-     - All :mc-cmd:`mc admin` commands.
-
-Users also inherit permissions from their assigned :ref:`groups
-<minio-auth-authz-groups>`. A user's total set of permissions consists of their
-explicitly assigned permissions *and* the inherited permissions from each of
-their assigned groups.
-
-.. admonition:: ``Deny`` overrides ``Allow``
-   :class: note
-
-   MinIO follows the IAM policy evaluation rules where a ``Deny`` rule overrides
-   ``Allow`` rule on the same action/resource. For example, if a user has an
-   explicitly assigned policy with an ``Allow`` rule for an action/resource
-   while one of its groups has an assigned policy with a ``Deny`` rule for that
-   action/resource, MinIO would apply only the ``Deny`` rule. 
-
-   For more information on IAM policy evaluation logic, see the IAM
-   documentation on 
-   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
-   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
-
-.. _minio-auth-authz-root:
-
-``root`` User
-~~~~~~~~~~~~~
-
-By default, MinIO deployments provide ``root`` user with access to all actions
-and resources on the deployment. The ``root`` user credentials are set when
-starting the ``minio`` server. When specifying the ``root`` access key and
-secret key, consider using *long, unique, and random* strings. Exercise all
-possible precautions in storing the access key and secret key, such that only
-known and trusted individuals who *require* superuser access to the deployment
-can retrieve the ``root`` credentials.
-
-- MinIO *strongly discourages* using the ``root`` user for regular client access
-  regardless of the environment (development, staging, or production).
-
-- MinIO *strongly recommends* creating users such that each client has access to
-  the minimal set of actions and resources required to perform their assigned
-  workloads. 
-
-.. _minio-auth-authz-groups:
-
-Groups
-------
-
-A *group* is a collection of :ref:`users <minio-auth-authz-users>`. Each group
-can have one or more assigned :ref:`policies <minio-auth-authz-pbac-policies>`
-that explicitly list the actions and resources to which group members are
-allowed or denied access.
-
-For example, consider the following groups. Each group is assigned a
-:ref:`built-in policy <minio-auth-authz-pbac-built-in>` or supported
-:ref:`policy action <minio-auth-authz-pbac-actions>`. Each group also has one or
-more assigned users. Each user's total set of permissions consists of their
-explicitly assigned permission *and* the inherited permissions from each of
-their assigned groups.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 20 40 40
-   :width: 100%
-
-   * - Group
-     - Policy
-     - Members
-
-   * - ``Operations``
-     - | :userpolicy:`readwrite` on ``finance`` bucket
-       | :userpolicy:`readonly` on ``audit`` bucket
-     
-     - ``john.doe``, ``jane.doe``
-
-   * - ``Auditing``
-     - | :userpolicy:`readonly` on ``audit`` bucket
-     - ``jen.doe``, ``joe.doe``
-
-   * - ``Admin``
-     - :policy-action:`admin:*`
-     - ``greg.doe``, ``jen.doe``
-
-Groups provide a simplified method for managing shared permissions among
-users with common access patterns and workloads. Client's *cannot* authenticate
-to a MinIO deployment using a group as an identity.
-
-.. admonition:: ``Deny`` overrides ``Allow``
-   :class: note
-
-   MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
-   on the same action or resource. For example, if a user has an explicitly
-   assigned policy with an ``Allow`` rule for an action/resource while one of
-   its groups has an assigned policy with a ``Deny`` rule for that
-   action/resource, MinIO would apply only the ``Deny`` rule. 
-
-   For more information on IAM policy evaluation logic, see the IAM
-   documentation on 
-   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
-   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
-
-.. _minio-auth-authz-pbac-policies:
-
-Policies
---------
-
-MinIO uses Policy-Based Access Control (PBAC) for supporting *authorization* of
-users who have successfully *authenticated* to the deployment. Each policy
-describes one or more rules that outline the permissions of a user or group of
-users. MinIO PBAC follows the guidelines and standards set by AWS Identity and
-Access Management (IAM). MinIO supports a subset of :iam-docs:`IAM actions and
-conditions <reference_policies_actions-resources-contextkeys.html>` when
-creating policies. By default, MinIO *denies* access to actions or resources not
-explicitly referenced in a user's assigned or inherited policies.
-
-This section focuses on MinIO's implementation and extensions of IAM policies
-and access management. A complete description of IAM or IAM policies is out
-of scope of this documentation. Consider deferring to the
-:iam-docs:`IAM documentation <>` for more complete documentation on the
-IAM service.
-
-.. _minio-auth-authz-pbac-built-in:
 
 Built-In Policies
-~~~~~~~~~~~~~~~~~
+-----------------
 
-MinIO provides the following built-in policies for assigning to users
+MinIO provides the following built-in policies for assigning to 
-and groups:
+:ref:`users <minio-users>` or :ref:`groups <minio-groups>`:
 
 .. userpolicy:: readonly
 
@@ -231,15 +59,18 @@ and groups:
    Grants write-only permissions for all buckets and objects on the MinIO 
    server.
 
-.. _minio-auth-authz-pbac-document:
+Use :mc-cmd:`mc admin policy set` to associate a policy to a 
+user or group on a MinIO deployment.
+
+.. _minio-policy-document:
 
 Policy Document Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 MinIO policy documents use the same schema as 
 :aws-docs:`AWS IAM Policy <IAM/latest/UserGuide/access.html>` documents.
 
-The following sample document provides a general schema for creating custom
+The following sample document provides a template for creating custom
 policies for use with a MinIO deployment. For more complete documentation on IAM
 policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
 <IAM/latest/UserGuide/reference_policies_elements.html>`. 
@@ -266,7 +97,7 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
    }
 
 - For the ``Statement.Action`` array, specify one or more 
-  :ref:`supported S3 actions <minio-auth-authz-pbac-actions>`. MinIO deployments
+  :ref:`supported S3 actions <minio-policy-actions>`. MinIO deployments
   supports a subset of AWS S3 actions.
 
 - For the ``Statement.Resource`` key, you can replace the ``*`` with 
@@ -274,13 +105,13 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
   Using ``*`` applies the statement to all resources on the MinIO deployment.
 
 - For the ``Statement.Condition`` key, you can specify one or more 
-  :ref:`supported Conditions <minio-auth-authz-pbac-conditions>`. MinIO
+  :ref:`supported Conditions <minio-policy-conditions>`. MinIO
   deployments supports a subset of AWS S3 conditions.
 
-.. _minio-auth-authz-pbac-actions:
+.. _minio-policy-actions:
 
-Supported Policy Actions
+Supported S3 Policy Actions
-~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 MinIO policy documents support a subset of IAM 
 :iam-docs:`S3 Action keys <list_amazons3.html#amazons3-actions-as-permissions>`. 
@@ -558,7 +389,7 @@ The following table lists the MinIO-supported policy action keys.
    <API_GetObjectVersionForReplication.html>` IAM action.
 
 
-.. _minio-auth-authz-pbac-mc-admin-actions:
+.. _minio-policy-mc-admin-actions:
 
 ``mc admin`` Policy Action Keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -716,10 +547,10 @@ services:
 
    Allows getting bucket targets
 
-.. _minio-auth-authz-pbac-conditions:
+.. _minio-policy-conditions:
 
-Supported Policy Condition Keys
+Supported S3 Policy Condition Keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 MinIO policy documents support IAM 
 :iam-docs:`conditional statements <reference_policies_elements_condition.html>`. 
@@ -732,7 +563,7 @@ information on any listed condition key, see the
 <reference_policies_elements_condition.html>`
 
 MinIO supports the following condition keys for all supported 
-:ref:`actions <minio-auth-authz-pbac-actions>`:
+:ref:`actions <minio-policy-actions>`:
 
 - ``aws:Referer``
 - ``aws:SourceIp``
@@ -802,10 +633,10 @@ actions:
      - ``s3:versionid``
 
 ``mc admin`` Policy Condition Keys
-``````````````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MinIO supports the following conditions for use with defining policies for
-:mc-cmd:`mc admin` :ref:`actions <minio-auth-authz-pbac-mc-admin-actions>`.
+:mc-cmd:`mc admin` :ref:`actions <minio-policy-mc-admin-actions>`.
 
 - ``aws:Referer``
 - ``aws:SourceIp``
@@ -818,19 +649,18 @@ For complete information on any listed condition key, see the :iam-docs:`IAM
 Condition Element Documentation <reference_policies_elements_condition.html>`
 
 Creating Custom Policies
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
-Use the ``mc admin policy`` command to add a policy to the MinIO
+Use the :mc-cmd:`mc admin policy add` command to add a policy to the MinIO
 server. The policy *must* be a valid JSON document formatted according to
 IAM policy specifications. For example:
 
 .. code-block:: shell
 
-   mc config host add myminio http://myminio1.example.net:9000 <access_key> <secret_key>
-
    mc admin policy add myminio/ new_policy new_policy.json
 
-To add this policy to a user or group, use the ``mc admin policy set`` command:
+Use the :mc-cmd:`mc admin policy set` command to associate a policy to a
+:ref:`user <minio-users>` or :ref:`group <minio-groups>`.
 
 .. code-block:: shell
 
@@ -838,3 +668,8 @@ To add this policy to a user or group, use the ``mc admin policy set`` command:
 
    mc admin policy set myminio/ new_policy group=group_name
 
+.. note::
+
+   ``myminio`` refers to the :mc-cmd:`alias <mc alias>` of an S3-compatible
+   host configured for use with :program:`mc`. See :mc-cmd:`mc alias` for
+   more information on aliases.

source/security/IAM/iam-providers.rst

@@ -0,0 +1,11 @@
+=========
+Providers
+=========
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 1
+
+Stub - might duplicate STS page?

source/security/IAM/iam-security-token-service.rst

@@ -1,14 +1,14 @@
-.. _minio-sts-overview:
+.. _minio-sts:
 
-============================
+======================
-MinIO Security Token Service
+Security Token Service
-============================
+======================
 
 .. default-domain:: minio
 
 .. contents:: Table of Contents
    :local:
-   :depth: 1
+   :depth: 2
 
 Overview
 --------

source/security/IAM/iam-users.rst

@@ -0,0 +1,138 @@
+.. _minio-users:
+
+=====
+Users
+=====
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+A *user* is an identity with associated privileges on a MinIO deployment. Each
+user consists of a unique access key (username) and corresponding secret key
+(password).  The access key and secret key support *authentication* on the MinIO
+deployment, similar to a username and password. Clients must specify both a
+valid access key (username) and the corresponding secret key (password) to
+access the MinIO deployment. 
+
+Each user can have one or more assigned :ref:`policies <minio-policy>` that
+explicitly list the actions and resources to which the user is allowed or denied
+access. A user can also have membership in a :ref:`group <minio-groups>`, where
+the user inherits any policies assigned to the group. Policies support
+*authorization* on the MinIO deployment, such that clients can only access a
+resource or operation if the user's assigned and inherited policies explicitly
+grant. MinIO by default *denies* access to any resource or operation not
+explicitly allowed by a user's assigned or inherited policies.
+
+For example, consider the following table of users. Each user is assigned
+a :ref:`built-in policy <minio-policy-built-in>` or
+a supported :ref:`action <minio-policy-actions>`. The table
+describes a subset of operations a client could perform if authenticated
+as that user:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+   :width: 100%
+
+   * - User
+     - Policy
+     - Operations
+
+   * - ``Operations``
+     - | :userpolicy:`readwrite` on ``finance`` bucket
+       | :userpolicy:`readonly` on ``audit`` bucket
+     
+     - | ``PUT`` and ``GET`` on ``finance`` bucket.
+       | ``PUT`` on ``audit`` bucket
+
+   * - ``Auditing``
+     - | :userpolicy:`readonly` on ``audit`` bucket
+     - ``GET`` on ``audit`` bucket
+
+   * - ``Admin``
+     - :policy-action:`admin:*`
+     - All :mc-cmd:`mc admin` commands.
+
+Each user can access only those resources and operations which are *explicitly*
+granted by the built-in role. MinIO denies access to any other resource or
+action by default.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM policy evaluation rules where a ``Deny`` rule overrides
+   ``Allow`` rule on the same action/resource. For example, if a user has an
+   explicitly assigned policy with an ``Allow`` rule for an action/resource
+   while one of its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+.. _minio-users-root:
+
+``root`` User
+~~~~~~~~~~~~~
+
+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 envrionment variables:
+
+- :envvar:`MINIO_ACCESS_KEY`
+- :envvar:`MINIO_SECRET_KEY`
+
+To rotate the ``root`` user credentials, set the following environment 
+variables and restart the :mc:`minio` server:
+
+- :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
+access key and secret key, such that only known and trusted individuals who
+*require* superuser access to the deployment can retrieve the ``root``
+credentials.
+
+- MinIO *strongly discourages* using the ``root`` user for regular client access
+  regardless of the environment (development, staging, or production).
+
+- MinIO *strongly recommends* creating users such that each client has access to
+  the minimal set of actions and resources required to perform their assigned
+  workloads. 
+
+If these variables are unset, :mc:`minio` defaults to ``minioadmin`` and
+``minioadmin`` as the access key and secret key respectively. MinIO *strongly
+discourages* use of the default credentials regardless of deployment
+environment.
+
+Create a User
+-------------
+
+Use the :mc-cmd:`mc admin user add` command to create a new user on the
+MinIO deployment:
+
+Delete a User
+-------------
+
+Use the :mc-cmd:`mc admin user remove` command to remove a user on a 
+MinIO deployment:
+
+Authenticate as a User
+----------------------
+
+ToDo: Examples of authenticating to a MinIO deployment with a created user. 
+
+Should have examples with `mc` and each of the SDKs. 

source/security/IAM/identity-access-management.rst

@@ -0,0 +1,96 @@
+.. _minio-auth-authz-overview:
+
+==============================
+Identity and Access Management
+==============================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+*Authentication* is the process of verifying the identity of a connecting
+client. MinIO authentication requires providing user credentials in the form of
+an access key (username) and corresponding secret key (password). The MinIO
+deployment only grants access *if*:
+
+- The access key corresponds to a user on the deployment, *and*
+- The secret key corresponds to the specified access key.
+
+*Authorization* is the process of restricting the actions and resources the
+authenticated client can perform on the deployment. MinIO uses Policy-Based
+Access Control (PBAC), where each policy describes one or more rules that
+outline the permissions of a user or group of users. MinIO supports a subset of
+:iam-docs:`IAM actions and conditions
+<reference_policies_actions-resources-contextkeys.html>` when creating policies.
+By default, MinIO *denies* access to actions or resources not explicitly
+referenced in a user's assigned or inherited policies.
+
+- For more information on MinIO user management, see 
+  :ref:`minio-users`.
+
+- For more information on MinIO group management, see
+  :ref:`minio-groups`.
+
+- For more information on MinIO policy creation, see
+  :ref:`minio-policy`.
+
+Users and Groups
+----------------
+
+MinIO requires that client's *authenticate* using an access key and secret key
+that correspond to a :ref:`user <minio-users>`. A user can have membership in
+one or more :ref:`groups <minio-groups>`, where the user inherits any privileges
+associated to each group. MinIO *authorizes* the client to access only those
+resources and operations which the user's assigned or inherited :ref:`privileges
+<minio-policy>` explicitly allow. 
+
+MinIO supports creating an arbitrary number of users and groups on the 
+deployment for supporting client authentication. 
+
+- Use :mc-cmd:`mc admin user add` to create a new user.
+
+- Use :mc-cmd:`mc admin group add` to add users to a group. The command
+  implicitly creates the group if it does not exist.
+
+For complete documentation on creating MinIO users and groups, see
+:ref:`minio-users` and :ref:`minio-groups`.
+
+MinIO *also* supports federating identity management to supported third-party
+services through the :ref:`Secure Token Service <minio-sts>`. Supported
+identity providers include Okta, Facebook, Google, and Active Directory/LDAP.
+For more complete documentation on MinIO STS configuration, see
+:ref:`minio-sts`.
+
+Policies
+--------
+
+MinIO uses :ref:`Policy-Based Access Control <minio-policy>` (PBAC) to specify
+the *authorized* resources and operations to which a :ref:`user <minio-users>`
+or :ref:`groups <minio-groups>` has access. MinIO PBAC uses AWS IAM-compatible
+JSON syntax for defining policies. For example, MinIO can use IAM policies
+designed for use with AWS S3 or S3-compatible services.
+
+MinIO provides a set of built-in policies that provide a baseline for 
+seperation of least privilege, such that a user has access to the minimum set 
+of privileges required to perform their assigned actions. MinIO also supports
+customized policies, including those imported from AWS IAM or IAM-compatible
+policy building tools. For more complete documentation on MinIO policies, see
+:ref:`minio-policy`.
+
+To assign policies to users or groups, use the :mc-cmd:`mc admin policy set` 
+command from the :program:`mc` command line tool.
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   /security/IAM/iam-users
+   /security/IAM/iam-groups
+   /security/IAM/iam-policies
+   /security/IAM/iam-providers
+   /security/IAM/iam-security-token-service

source/security/encryption/encryption-key-management.rst

@@ -0,0 +1,49 @@
+=============================
+Encryption and Key Management
+=============================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 1
+
+MinIO supports key security features around object-level and network-level
+encryption:
+
+Server-Side Object Encryption
+-----------------------------
+
+MinIO supports :ref:`Server-Side Object Encryption (SSE) <minio-sse>` of
+objects, where MinIO uses a secret key to encrypt and store objects on disk.
+Only clients with access to the correct secret key can decrypt and read the
+object.
+
+<Diagram to follow>
+
+See :ref:`Server-Side Object Encryption (SSE) <minio-sse>` for more complete
+instructions on configuring MinIO for object encryption.
+
+Transport Layer Security (TLS)
+------------------------------
+
+MinIO supports :ref:`Transport Layer Security (TLS) <minio-TLS>` encryption of
+incoming and outgoing traffic. 
+
+<Diagram to Follow>
+
+TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully
+`deprecated <https://tools.ietf.org/html/rfc7568>`__ as of June 30th, 2018. 
+MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).
+
+See :ref:`Transport Layer Security (TLS) <minio-TLS>`
+for more complete instructions on configuring MinIO for TLS.
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /security/encryption/server-side-encryption
+   /security/encryption/transport-layer-security
+   /security/encryption/minio-kes
+   /security/encryption/sse-s3-thales

source/security/encryption/minio-kes.rst

@@ -0,0 +1,84 @@
+.. _minio-kes:
+
+============================
+MinIO Key Encryption Service
+============================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+The MinIO Key Encryption Service (KES) is a stateless and distributed
+key-management system for high-performance applications. KES provides
+a bridge between applications running in bare-metal or orchestrated
+environments to centralised KMS solutions. 
+
+<DIAGRAM>
+
+KES is designed for simplicity, scalability, and security. It requires 
+minimal configuration to enable full functionality and requires only
+basic familiarity with cryptography or key-management concepts.
+
+MinIO servers require KES for performing Server-Side Encryption (SSE) of objects
+using Key Management Services (KMS). 
+
+KES Server Process
+------------------
+
+.. mc:: kes server
+
+:mc:`kes server` command starts the KES server. The :mc:`kes server` process
+handles requests for creating and retrieving cryptography keys from a supported
+Key Management System (KMS). 
+
+The command has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   kes server --cert CERTIFICATE --key PRIVATEKEY --root ROOT_IDENTITY [OPTIONAL_FLAGS]
+
+:mc:`kes server` supports the following arguments:
+
+.. mc-cmd:: cert
+   :option:
+
+   The location of the public certificate ``.crt`` to use for
+   enabling :abbr:`TLS (Transport Layer Encryption)`.
+
+.. mc-cmd:: config
+   :option:
+
+   The path to the KES configuration file. See :ref:`minio-kes-config` for
+   more information on the configuration file format and contents.
+
+.. mc-cmd:: key
+   :option:
+
+   The location of the private key ``.key`` to use for enabling
+   :abbr:`TLS (Transport Layer Encryption`). 
+
+.. mc-cmd:: root
+   :option:
+
+   ToDo: Description
+
+.. mc-cmd:: port
+   :option:
+
+   The port on which the :mc:`kes server` listens.
+
+   Defaults to ``7373``. 
+
+.. _minio-kes-config:
+
+KES Configuration File
+----------------------
+
+ToDo: Import https://github.com/minio/kes/wiki/Configuration , need to
+include instructions on how to set the config file (directory, cli option etc.)

source/security/encryption/server-side-encryption.rst

@@ -1,3 +1,5 @@
+.. _minio-sse:
+
 =============================
 Server-Side Object Encryption
 =============================
@@ -24,8 +26,8 @@ SSE-C
 
 SSE-S3
    The server uses a secret key managed by a Key Management System (KMS)
-   to perform encryption and decryption. SSE-S3 requires a compatible KMS
+   to perform encryption and decryption. SSE-S3 requires using 
-   provider accessible by the MinIO server.
+   :ref:`MinIO KES <minio-kes>` and a supported KMS.
 
 Encryption Process Overview
 ---------------------------
@@ -56,11 +58,9 @@ object:
        object. MinIO encrypts the OEK using the KEK and stores the encrypted
        OEK as metadata with the object.
 
-SSE Encryption Types
---------------------
 
-SSE with Client Provided Keys (SSE-C)
+SSE using S3-Client Keys (SSE-C)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 SSE-C allows S3 clients to specify an Encryption Key (EK) for encrypting or
 decrypting an object stored on the MinIO server. The S3 client sends the secret
@@ -77,7 +77,7 @@ compromise of that EK *also* results in the loss or compromise of all data
 encrypted with that EK.
 
 Key Rotation
-````````````
+~~~~~~~~~~~~
 
 S3 clients can rotate the client EK of an existing object using an S3 ``COPY``
 operation. The ``COPY`` source and destination *must* be the same, while the
@@ -93,8 +93,8 @@ object:
 
 Such a special COPY request is also known as S3 SSE-C key rotation.
 
-SSE with KMS Provided Keys (SSE-S3)
+SSE using a Key Management Service (SSE-S3)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 SSE-S3 allows S3 clinets to encrypt or decrypt an object at the MinIO server
 using an external Key Management Service (KMS). The MinIO server requires
@@ -108,14 +108,19 @@ the KMS provide the following services:
   along with an encrypted data key. The KMS uses the master key to decrypt
   the data key and return the plain data key.
 
-The MinIO server requests a new data key from the KMS for each uploaded 
+Enabling SSE-S3 requires deploying one or more 
-object and uses that data key as the Encryption Key (EK). MinIO stores
+:ref:`MinIO Key Encryption Servers (KES) <minio-kes>` and configuring the
-the encrypted EK and the master key ID as part of the object metadata.
+:mc:`minio` server for access to KES. The KES handles processing
-While the MinIO server never stores the plain EK to disk, the EK resides
+cryptographic key requests to the KMS service.
-in system RAM during the encryption or decryption process.
+
+With SSE-S3, the MinIO server requests a new data key for each uploaded object
+and uses that data key as the Encryption Key (EK). MinIO stores the encrypted EK
+and the master key ID as part of the object metadata. While the MinIO server
+never stores the plain EK to disk, the EK resides in system RAM during the
+encryption or decryption process.
 
 Key Rotation
-````````````
+~~~~~~~~~~~~
 
 The MinIO server supports key rotation for SSE-S3 encrypted objects. The MinIO
 server decrypts the Object Encryption Key (OEK) using the current encrypted data
@@ -130,7 +135,7 @@ Only the root MinIO user can perform an SSE-S3 key rotation using the Admin-API
 the ``mc`` client. Refer to the ``mc admin guide`` <todo>
 
 Secure Erasure and Locking
-``````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The MinIO server requires an available KMS to en/decrypt SSE-S3 encrypted
 objects. Therefore it is possible to erase or lock some or all encrypted

source/security/encryption/sse-s3-thales.rst

@@ -0,0 +1,57 @@
+==============================================
+Server-Side Encryption with Thales CipherTrust
+==============================================
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+Paragraph summarizing SSE-S3 and Thales CipherTrust as a KMS.
+
+Note that Gemalto KeySecure is now Thales CipherTrust. 
+
+Prerequisites
+-------------
+
+Thales CipherTrust Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+High-Level description of CipherTrust requirements:
+
+- What access will the user need?
+- What versions do we support?
+
+MinIO Key Encryption Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+High-level description of KES requirements:
+
+- A host for deploying at least one KES server
+- For Kubernetes, at least one node with enough resources to run the server
+
+MinIO Server
+~~~~~~~~~~~~
+
+High-level description of MinIO server requirements:
+
+- ?
+
+Procedure
+---------
+
+1) Configure CipherTrust Manager for MinIO Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Substeps:
+
+1. Foo
+
+2. Bar
+
+2) Configure KES...
+~~~~~~~~~~~~~~~~~~~

source/security/minio-security.rst

@@ -1,47 +0,0 @@
-==============
-MinIO Security
-==============
-
-.. default-domain:: minio
-
-MinIO provides support for the following security features:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 30 70
-
-   * - Feature
-     - Description
-
-   * - Server-Side Object Encryption
-     - Encrypt objects using a secret key provided by the S3 client
-       or a supported Key Management System (KMS). Only clients with access
-       to the secret key can decrypt the object. 
-   
-   * - Transport Layer Security (TLS) Encryption
-     - Enable TLS encryption of all network traffic. Several MinIO 
-       security features, such as Server-Side Object Encryption, require
-       TLS encryption to ensure end-to-end security of data.
-
-   * - Policy Based Access Control (RBAC)
-     - MinIO uses :aws-docs:`IAM-compatible policy documents 
-       <IAM/latest/UserGuide/access_policies>` for controlling user privileges.
-       You can also assign privileges to a group, where all members of the
-       group inherit the group privileges. MinIO provides built-in
-       policies for the most common access patterns.
-   
-   * - Security Token Service (STS)
-     - MinIO Security Token Service (STS) is an endpoint service that allows
-       clients to request temporary credentials for accessing MinIO resources.
-       MinIO STS supports multiple forms of identity federation, including
-       OpenID identity providers and Active Directory/LDAP services.
-
-
-.. toctree::
-   :titlesonly:
-   :hidden:
-
-   /security/minio-authentication-authorization
-   /security/minio-security-TLS-encryption
-   /security/minio-security-server-side-encryption
-   /security/minio-security-security-token-service 

source/security/security-overview.rst

@@ -0,0 +1,22 @@
+==============
+MinIO Security
+==============
+
+.. default-domain:: minio
+
+:doc:`/security/IAM/identity-access-management`
+   Identity and Access Management (IAM) governs secured access to a MinIO
+   deployment, where administrators have granular controls over the
+   resources and operations which a client can perform.
+
+:doc:`/security/encryption/encryption-key-management`
+   Encryption and Key Management (EKM) governs the encryption of objects
+   stored on MinIO, including on-disk encryption *and* over-the-wire (network)
+   encryption.
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /security/IAM/identity-access-management
+   /security/encryption/encryption-key-management

sphinxext/minio.py

@@ -258,7 +258,7 @@ class MinioObject(ObjectDescription):
 
     #: If ``allow_nesting`` is ``True``, the object prefixes will be accumulated
     #: based on directive nesting
-    allow_nesting = False
+    allow_nesting = True
 
     option_spec = {
         'noindex': directives.flag,
@@ -273,73 +273,24 @@ class MinioObject(ObjectDescription):
         directives.
         """
         sig = sig.strip()
-        if '(' in sig and sig[-1:] == ')':
+
-            member, arglist = sig.split('(', 1)
+        member = sig
-            member = member.strip()
-            arglist = arglist[:-1].strip()
-        elif ',' in sig:
-           # Bit ugly. For subcommands w/ aliases
-           member, alias = sig.split(',', 1)
-           member = member.strip()
-           alias = alias.strip()
-        else:
-            member = sig
-            arglist = None
-            alias = None
         # If construct is nested, prefix the current prefix
         prefix = self.env.ref_context.get('minio:object', None)
-        mod_name = self.env.ref_context.get('minio:command')
-        name = member
-        try:
-            member_prefix, member_name = member.rsplit('.', 1)
-        except ValueError:
-            member_name = name
-            member_prefix = ''
-        finally:
-            name = member_name
-            if prefix and member_prefix:
-                prefix = '.'.join([prefix, member_prefix])
-            elif prefix is None and member_prefix:
-                prefix = member_prefix
-        fullname = name
-        if prefix and self.allow_nesting==False:
-            fullname = '.'.join([prefix, name])
-        elif prefix and self.allow_nesting==True:
-            fullname = ' '.join([prefix, name])
 
-        signode['module'] = mod_name
+        fullname = member
+
+        if prefix:
+          fullname = '.'.join([prefix, member])
+
         signode['object'] = prefix
         signode['fullname'] = fullname
 
-        if self.display_prefix:
+        if prefix:  
-            signode += addnodes.desc_annotation(self.display_prefix,
+          signode += addnodes.desc_addname(prefix + '.', prefix + '.')
-                                                self.display_prefix)
         
-        # In our current usage, we only nest for command/subcommand. So we 
+        signode += addnodes.desc_name(member, member)
-        # need to split some of the logic here from nesting of YAML or JSON
-        # So if allow_nesting is true, we should use " " instead of "." for
-        # the prefix description.
-        # We also have an exit for the 'subcommand' type so that we don't end 
-        # up building long name strings for subcommands
-        # Finally for subcommands w/ aliases, need to append the alias name
 
-
-        if prefix and self.allow_nesting == False:
-            signode += addnodes.desc_addname(prefix + '.', prefix + '.')
-        elif prefix and self.allow_nesting == True and self.objtype != 'subcommand':
-            signode += addnodes.desc_addname(prefix + ' ', prefix + ' ')
-            signode += addnodes.desc_addname(alias + ' ', alias + ' ')
-        elif mod_name:
-            signode += addnodes.desc_addname(mod_name + '.', mod_name + '.')
-        if (alias != None):
-           signode += addnodes.desc_name(name + ", " + alias, name + ", " + alias)
-        else:
-           signode += addnodes.desc_name(name, name)
-        if self.has_arguments:
-            if not arglist:
-                signode += addnodes.desc_parameterlist()
-            else:
-                _pseudo_parse_arglist(signode, arglist)
         return fullname, prefix
 
     def add_target_and_index(self, name_obj: Tuple[str, str], sig: str,
@@ -533,7 +484,7 @@ class MinIODomain(Domain):
         'mc-cmd':         ObjType(_('mc-cmd'),        'mc-cmd'),
         'mc-cmd-option':  ObjType(_('mc-cmd-option'), 'mc-cmd-option'),
         'policy-action':  ObjType(_('policy-action'), 'policy-action'),
-        'envvar':        ObjType(_('envvar'),       'envvar')
+        'envvar':         ObjType(_('envvar'),       'envvar')
     }
     directives = {
         'data':            MinioObject,