diff --git a/source/index.rst b/source/index.rst index 71680e7e..a18b5d5c 100644 --- a/source/index.rst +++ b/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 ` access key. Replace the + sample value with a long, random, and unique string. + + * - :envvar:`MINIO_ROOT_PASSWORD_FILE` + - The :ref:`root user ` 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 ` and :ref:`user ` for supporting the :minio-git:`MinIO Console `. The Console provides a diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index e5956415..d5565dca 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -265,6 +265,22 @@ Key Management Service and Encryption See :minio-git:`KMS IAM/Config Encryption ` for more information. + Specify a 32-bit base-64 encrypted string in the following format: + + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` 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 ` 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` - x.509 certificate to use when authenticating to the KES server. - The KES server requires clients to present their certificate for performing mutual TLS (mTLS). + The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` x.509 + certificate to use when authenticating to the KES server. The KES server + requires clients to present their certificate for performing mutual TLS + (mTLS). See the :minio-git:`KES wiki ` 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 KES server requires clients to present their certificate and for performing mutual TLS (mTLS). + The x.509 certificate to present to the KES server. The KES server requires + clients to present their certificate for performing mutual TLS (mTLS). The KES server computes an :minio-git:`identity ` @@ -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 - configured on the KES server. MinIO uses this key for supporting - server-side encryption of objects (SSE-S3) and MinIO backend encryption. - + The name of an external key on the Key Management system (KMS) configured on + the KES server and used for performing en/decryption operations. MinIO uses + this key for supporting server-side encryption of objects (SSE-S3) and MinIO + backend encryption. Storage Class ~~~~~~~~~~~~~ diff --git a/source/security/IAM/iam-users.rst b/source/security/IAM/iam-users.rst index 50677cf7..0ec7491c 100644 --- a/source/security/IAM/iam-users.rst +++ b/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_SECRET_KEY` +- :envvar:`MINIO_ROOT_USER_FILE` +- :envvar:`MINIO_ROOT_PASSWORD_FILE` -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`. +Rotating the root user credentials requires updating either or both +variables for all MinIO servers in the deployment. 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 ` with the + :mc-cmd:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`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 ` 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 ` with the + :mc-cmd:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user to remove. diff --git a/source/tutorials/minio-installation.rst b/source/tutorials/minio-installation.rst index 69a54b91..aa7584ef 100644 --- a/source/tutorials/minio-installation.rst +++ b/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 - 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 +3\) 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: + + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` 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 - :class: copyable + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` 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:/disk`` - 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: + + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` with a 32-bit base64 encoded value. + For example: + + .. code-block:: shell + :class: copyable + + cat /dev/urandom | head -c 32 | base64 - + * - ``-v /mnt/disk:/disk`` - 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 - 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 +3\) 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 `: @@ -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: + + ``:`` + + - Replace the ```` with any string. You must use this + key name if you later migrate to using a dedicated KMS for + managing encryption keys. + + - Replace ```` 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 - series. Specifically, ``/mnt/disk{1...4}/data`` expands to: - - - ``/mnt/disk1/data`` - - ``/mnt/disk2/data`` - - ``/mnt/disk3/data`` - - ``/mnt/disk4/data`` + 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`` 4\) Connect to the Server Use the :mc-cmd:`mc alias set` command from a machine with connectivity to