mirror of
https://github.com/minio/docs.git
synced 2025-08-06 14:42:56 +03:00
Docs Multiplatform Slice
This commit is contained in:
Ravind Kumar
@@ -0,0 +1,174 @@
|
||||
.. _minio-encryption-sse-c:
|
||||
|
||||
=======================================================
|
||||
Server-Side Encryption with Client-Managed Keys (SSE-C)
|
||||
=======================================================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
.. |EK| replace:: :abbr:`EK (External Key)`
|
||||
.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
|
||||
.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
|
||||
.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
|
||||
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
|
||||
.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
|
||||
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
|
||||
|
||||
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
|
||||
allowing clients to take advantage of server processing power to secure objects
|
||||
at the storage layer (encryption-at-rest). SSE also provides key functionality
|
||||
to regulatory and compliance requirements around secure locking and erasure.
|
||||
|
||||
The procedure on this page configures and enables Server-Side Encryption
|
||||
with Client-Managed Keys (SSE-C). MinIO SSE-C supports client-driven
|
||||
encryption of objects *before* writing the object to disk. Clients must
|
||||
specify the correct key to decrypt objects for read operations.
|
||||
|
||||
MinIO SSE-C is functionally compatible with Amazon
|
||||
:s3-docs:`Server-Side Encryption with Customer-Provided Keys
|
||||
<ServerSideEncryptionCustomerKeys.html>`.
|
||||
|
||||
.. _minio-encryption-sse-c-erasure-locking:
|
||||
|
||||
Secure Erasure and Locking
|
||||
--------------------------
|
||||
|
||||
SSE-C protects objects using an |EK| specified by the client as part
|
||||
of the write operation. Assuming the client-side key management
|
||||
supports disabling or deleting these keys:
|
||||
|
||||
- Disabling the |EK| temporarily locks any objects encrypted using that
|
||||
|EK| by rendering them unreadable. You can later enable the |EK| to
|
||||
resume normal read operations on those objects.
|
||||
|
||||
- Deleting the |EK| renders all objects encrypted by that |EK|
|
||||
*permanently* unreadable. If the client-side KMS does not support
|
||||
backups of the |EK|, this process is *irreversible*.
|
||||
|
||||
The scope of a single |EK| depends on the number of write operations
|
||||
which specified that |EK| when requesting SSE-C encryption.
|
||||
|
||||
Considerations
|
||||
--------------
|
||||
|
||||
SSE-C is Incompatible with Bucket Replication
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
SSE-C encrypted objects are not compatible with MinIO
|
||||
:ref:`bucket replication <minio-bucket-replication>`. Use
|
||||
:ref:`SSE-KMS <minio-encryption-sse-kms>` or
|
||||
:ref:`SSE-S3 <minio-encryption-sse-s3>` to ensure encrypted
|
||||
objects are compatible with bucket replication.
|
||||
|
||||
SSE-C Overrides SSE-S3 and SSE-KMS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Encrypting an object using SSE-C prevents MinIO from applying
|
||||
:ref:`SSE-KMS <minio-encryption-sse-kms>` or
|
||||
:ref:`SSE-S3 <minio-encryption-sse-s3>` encryption to that object.
|
||||
|
||||
Quickstart
|
||||
----------
|
||||
|
||||
MinIO SSE-C requires the client to perform all key creation and storage
|
||||
operations.
|
||||
|
||||
This procedure uses :mc:`mc` for performing operations on the source MinIO
|
||||
deployment. Install :mc:`mc` on a machine with network access to the source
|
||||
deployment. See the ``mc`` :ref:`Installation Quickstart <mc-install>` for
|
||||
instructions on downloading and installing ``mc``.
|
||||
|
||||
The SSE-C key *must* be a 256-bit base64-encoded string. The client
|
||||
application is responsible for generation and storage of the encryption key.
|
||||
MinIO does *not* store SSE-C encryption keys and cannot decrypt SSE-C
|
||||
encrypted objects without the client-managed key.
|
||||
|
||||
1) Generate the Encryption Key
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Generate the 256-bit base64-encoded string for use as the encryption key.
|
||||
|
||||
The following example generates a string that meets the encryption key
|
||||
requirements. The resulting string is appropriate for non-production
|
||||
environments:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
cat /dev/urandom | head -c 32 | base64 -
|
||||
|
||||
Defer to your organizations requirements for generating cryptographically
|
||||
secure encryption keys.
|
||||
|
||||
Copy the encryption key for use in the next step.
|
||||
|
||||
2) Encrypt an Object using SSE-C
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO supports the following AWS S3 headers for specifying SSE-C encryption:
|
||||
|
||||
- ``X-Amz-Server-Side-Encryption-Customer-Algorithm`` set to ``AES256``.
|
||||
|
||||
- ``X-Amz-Server-Side-Encryption-Customer-Key`` set to the encryption key value.
|
||||
|
||||
- ``X-Amz-Server-Side-Encryption-Customer-Key-MD5`` to the 128-bit MD5 digest of
|
||||
the encryption key.
|
||||
|
||||
The MinIO :mc:`mc` commandline tool S3-compatible SDKs include specific syntax
|
||||
for setting headers. Certain :mc:`mc` commands like :mc:`mc cp` include specific
|
||||
arguments for enabling SSE-S3 encryption:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc cp ~/data/mydata.json ALIAS/BUCKET/mydata.json \
|
||||
--encrypt-key "ALIAS/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo="
|
||||
|
||||
- Replace :mc-cmd:`ALIAS <mc encrypt set ALIAS>` with the
|
||||
:mc:`alias <mc alias>` of the MinIO deployment on which you want to write
|
||||
the SSE-C encrypted object.
|
||||
|
||||
- Replace :mc-cmd:`BUCKET <mc encrypt set ALIAS>` with the full path to the
|
||||
bucket or bucket prefix to which you want to write the SSE-C encrypted object.
|
||||
|
||||
3) Copy an SSE-C Encrypted Object
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MinIO supports the following AWS S3 headers for copying an SSE-C encrypted
|
||||
object to another S3-compatible service:
|
||||
|
||||
- ``X-Amz-Copy-Source-Server-Side-Encryption-Algorithm`` set to ``AES256``
|
||||
|
||||
- ``X-Amz-Copy-Source-Server-Side-Encryption-Key`` set to the encryption key
|
||||
value. The copy operation will fail if the specified key does not match
|
||||
the key used to SSE-C encrypt the object.
|
||||
|
||||
- ``X-Amz-Copy-Source-Server-Side-Encryption-Key-MD5`` set to the 128-bit MD5
|
||||
digest of the encryption key.
|
||||
|
||||
The MinIO :mc:`mc` commandline tool S3-compatible SDKs include specific syntax
|
||||
for setting headers. Certain :mc:`mc` commands like :mc:`mc cp` include specific
|
||||
arguments for enabling SSE-S3 encryption:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc cp SOURCE/BUCKET/mydata.json TARGET/BUCKET/mydata.json \
|
||||
--encrypt-key "SOURCE/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo=" \
|
||||
--encrypt-key "TARGET/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo="
|
||||
|
||||
- Replace :mc-cmd:`SOURCE/BUCKET <mc encrypt set ALIAS>` with the
|
||||
:mc:`alias <mc alias>` of the MinIO deployment from which you are reading the
|
||||
encrypted object and the full path to the
|
||||
bucket or bucket prefix from which you want to read the SSE-C encrypted
|
||||
object.
|
||||
|
||||
- Replace :mc-cmd:`TARGET/BUCKET <mc encrypt set ALIAS>` with the
|
||||
:mc:`alias <mc alias>` of the MinIO deployment from which you are writing the
|
||||
encrypted object and the full path to the
|
||||
bucket or bucket prefix to which you want to write the SSE-C encrypted
|
||||
object.
|
||||
@@ -0,0 +1,323 @@
|
||||
.. _minio-encryption-sse-kms:
|
||||
|
||||
=====================================================
|
||||
Server-Side Encryption with Per-Bucket Keys (SSE-KMS)
|
||||
=====================================================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
.. |EK| replace:: :abbr:`EK (External Key)`
|
||||
.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
|
||||
.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
|
||||
.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
|
||||
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
|
||||
.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
|
||||
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
|
||||
|
||||
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
|
||||
allowing clients to take advantage of server processing power to secure objects
|
||||
at the storage layer (encryption-at-rest). SSE also provides key functionality
|
||||
to regulatory and compliance requirements around secure locking and erasure.
|
||||
|
||||
MinIO SSE uses the :minio-git:`MinIO Key Encryption Service (KES) <kes>` and an
|
||||
external Key Management Service (KMS) for performing secured cryptographic
|
||||
operations at scale. MinIO also supports client-managed key management, where
|
||||
the application takes full responsibility for creating and managing encryption
|
||||
keys for use with MinIO SSE.
|
||||
|
||||
MinIO SSE-KMS en/decrypts objects using an External Key (EK) managed by a Key
|
||||
Management System (KMS). Each bucket and object can have a separate |EK|,
|
||||
supporting more granular cryptographic operations in the deployment. MinIO can
|
||||
only decrypt an object if it can access both the KMS *and* the |EK| used to
|
||||
encrypt that object.
|
||||
|
||||
You can enable bucket-default SSE-KMS encryption using the
|
||||
:mc-cmd:`mc encrypt set` command:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc encrypt set sse-kms EXTERNALKEY play/mybucket
|
||||
|
||||
- Replace ``EXTERNALKEY`` with the name of the |EK| to use for encrypting
|
||||
objects in the bucket.
|
||||
|
||||
- Replace ``play/mybucket`` with the :mc-cmd:`alias <mc alias>` and bucket
|
||||
on which you want to enable automatic SSE-KMS encryption.
|
||||
|
||||
MinIO SSE-KMS is functionally compatible with AWS S3
|
||||
:s3-docs:`Server-Side Encryption with KMS keys stored in AWS
|
||||
<UsingKMSEncryption.html>` while expanding support to include the
|
||||
following KMS providers:
|
||||
|
||||
- :ref:`AWS SecretsManager <minio-sse-aws>`
|
||||
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
|
||||
- :ref:`Azure Key Vault <minio-sse-azure>`
|
||||
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
|
||||
- Thales CipherTrust (formerly Gemalto KeySecure)
|
||||
|
||||
.. _minio-encryption-sse-kms-quickstart:
|
||||
|
||||
Quickstart
|
||||
----------
|
||||
|
||||
The following procedure uses the ``play`` MinIO |KES| sandbox for
|
||||
supporting |SSE| with SSE-KMS in evaluation and early development environments.
|
||||
|
||||
For extended development or production environments, use one of the following
|
||||
supported external Key Management Services (KMS):
|
||||
|
||||
- :ref:`AWS SecretsManager <minio-sse-aws>`
|
||||
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
|
||||
- :ref:`Azure Key Vault <minio-sse-azure>`
|
||||
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
|
||||
|
||||
.. include:: /includes/common-minio-kes.rst
|
||||
:start-after: start-kes-play-sandbox-warning
|
||||
:end-before: end-kes-play-sandbox-warning
|
||||
|
||||
This procedure requires the following components:
|
||||
|
||||
- Install :mc:`mc` on a machine with network access to the source
|
||||
deployment. See the ``mc`` :ref:`Installation Quickstart <mc-install>` for
|
||||
instructions on downloading and installing ``mc``.
|
||||
|
||||
|
||||
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
|
||||
with internet access. See the ``kes``
|
||||
:minio-git:`Getting Started <kes/wiki/Getting-Started>` guide for
|
||||
instructions on downloading, installing, and configuring KES.
|
||||
|
||||
1) Create an Encryption Key for SSE-KMS Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Use the :minio-git:`kes <kes>` commandline tool to create a new External Key
|
||||
(EK) for use with SSE-KMS Encryption.
|
||||
|
||||
Issue the following command to retrieve the root
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>` for the KES
|
||||
server:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
curl -sSL --tlsv1.2 \
|
||||
-O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
|
||||
-O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'
|
||||
|
||||
Set the following environment variables in the terminal or shell:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
export KES_CLIENT_KEY=root.key
|
||||
export KES_CLIENT_CERT=root.cert
|
||||
|
||||
.. list-table::
|
||||
:stub-columns: 1
|
||||
:widths: 40 60
|
||||
:width: 100%
|
||||
|
||||
* - ``KES_CLIENT_KEY``
|
||||
- The private key for an :minio-git:`identity
|
||||
<kes/wiki/Configuration#policy-configuration>` on the KES server.
|
||||
The identity must grant access to at minimum the ``/v1/create``,
|
||||
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
|
||||
<kes/wiki/Server-API#api-overview>`. This step uses the root
|
||||
identity for the MinIO ``play`` KES sandbox, which provides access
|
||||
to all operations on the KES server.
|
||||
|
||||
* - ``KES_CLIENT_CERT``
|
||||
- The corresponding certificate for the :minio-git:`identity
|
||||
<kes/wiki/Configuration#policy-configuration>` on the KES server.
|
||||
This step uses the root identity for the MinIO ``play`` KES
|
||||
sandbox, which provides access to all operations on the KES server.
|
||||
|
||||
Issue the following command to create a new |EK| through
|
||||
KES.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
kes key create my-minio-sse-kms-key
|
||||
|
||||
This tutorial uses the example ``my-minio-sse-kms-key`` name for ease of
|
||||
reference. Specify a unique key name to prevent collision
|
||||
with existing keys.
|
||||
|
||||
2) Configure MinIO for SSE-KMS Object Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Specify the following environment variables in the shell or terminal on each
|
||||
MinIO server host in the deployment:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373
|
||||
export MINIO_KMS_KES_KEY_FILE=root.key
|
||||
export MINIO_KMS_KES_CERT_FILE=root.cert
|
||||
export MINIO_KMS_KES_KEY_NAME=my-minio-sse-kms-key
|
||||
|
||||
.. list-table::
|
||||
:stub-columns: 1
|
||||
:widths: 30 80
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_ENDPOINT`
|
||||
- The endpoint for the MinIO ``Play`` KES service.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_KEY_FILE`
|
||||
- The private key file corresponding to an
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
|
||||
on the KES service. The identity must grant permission to
|
||||
create, generate, and decrypt keys. Specify the same
|
||||
identity key file as the ``KES_KEY_FILE`` environment variable
|
||||
in the previous step.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
|
||||
- The public certificate file corresponding to an
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
|
||||
on the KES service. The identity must grant permission to
|
||||
create, generate, and decrypt keys. Specify the same
|
||||
identity certificate as the ``KES_CERT_FILE`` environment
|
||||
variable in the previous step.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_KEY_NAME`
|
||||
- The name of the External Key (EK) to use for
|
||||
performing SSE encryption operations. KES retrieves the |EK| from
|
||||
the configured Key Management Service (KMS). Specify the name of the
|
||||
key created in the previous step.
|
||||
|
||||
|
||||
3) Restart the MinIO Deployment to Enable SSE-KMS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must restart the MinIO deployment to apply the configuration changes.
|
||||
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin service restart ALIAS
|
||||
|
||||
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
|
||||
restart.
|
||||
|
||||
4) Configure Automatic Bucket Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Use the :mc-cmd:`mc encrypt set` command to enable automatic SSE-KMS protection
|
||||
of all objects written to a specific bucket.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc encrypt set sse-kms my-minio-sse-kms-key ALIAS/BUCKET
|
||||
|
||||
- Replace :mc-cmd:`ALIAS <mc encrypt set ALIAS>` with the
|
||||
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-KMS.
|
||||
|
||||
- Replace :mc-cmd:`BUCKET <mc encrypt set ALIAS>` with the full path to the
|
||||
bucket or bucket prefix on which you want to enable automatic SSE-KMS.
|
||||
|
||||
Objects written to the specified bucket are automatically encrypted using
|
||||
the specified |EK|
|
||||
|
||||
Repeat this step for each bucket on which you want to enable automatic
|
||||
SSE-KMS encryption. You can generate additional keys per bucket or bucket
|
||||
prefix, such that the scope of each |EK| is limited to a subset of objects.
|
||||
|
||||
|
||||
.. _minio-encryption-sse-kms-erasure-locking:
|
||||
|
||||
Secure Erasure and Locking
|
||||
--------------------------
|
||||
|
||||
SSE-KMS protects objects using an |EK| specified either as part of the
|
||||
bucket automatic encryption settings *or* as part of the write operation.
|
||||
MinIO therefore *requires* access to that |EK| for decrypting that object.
|
||||
|
||||
- Disabling the |EK| temporarily locks objects encrypted with that |EK| by
|
||||
rendering them unreadable. You can later enable the |EK| to resume
|
||||
normal read operations on those objects.
|
||||
|
||||
- Deleting the |EK| renders all objects encrypted by that |EK|
|
||||
*permanently* unreadable. If the KMS does not have or support backups
|
||||
of the |EK|, this process is *irreversible*.
|
||||
|
||||
The scope of a single |EK| depends on:
|
||||
|
||||
- Which buckets specified that |EK| for automatic SSE-KMS encryption,
|
||||
*and*
|
||||
- Which write operations specified that |EK| when requesting SSE-KMS
|
||||
encryption.
|
||||
|
||||
For example, consider a MinIO deployment using one |EK| per bucket.
|
||||
Disabling a single |EK| renders all objects in the associated bucket
|
||||
unreadable without affecting other buckets. If the deployment instead used
|
||||
one |EK| for all objects and buckets, disabling that |EK| renders all
|
||||
objects in the deployment unreadable.
|
||||
|
||||
.. _minio-encryption-sse-kms-encryption-process:
|
||||
|
||||
Encryption Process
|
||||
------------------
|
||||
|
||||
.. note::
|
||||
|
||||
This section describes MinIO internal logic and functionality.
|
||||
This information is purely educational and is not a prerequisite for
|
||||
configuring or implementing any MinIO feature.
|
||||
|
||||
SSE-KMS uses an External Key (EK) managed by the configured Key Management
|
||||
System (KMS) for performing cryptographic operations and protecting objects.
|
||||
The table below describes each stage of the encryption process:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 30 70
|
||||
|
||||
* - Stage
|
||||
- Description
|
||||
|
||||
* - SSE-Enabled Write Operation
|
||||
- MinIO receives a write operation requesting SSE-KMS encryption.
|
||||
The write operation *must* have an associated External Key (EK) to use
|
||||
for encrypting the object.
|
||||
|
||||
- For write operations in buckets with automatic SSE-KMS enabled,
|
||||
MinIO uses the bucket |EK|. If the write operation includes an
|
||||
explicit EK, MinIO uses that *instead* of the bucket EK.
|
||||
|
||||
- For write operations in buckets *without* automatic SSE-KMS enabled,
|
||||
MinIO uses the |EK| specified to the write operation.
|
||||
|
||||
* - Generate the Data Encryption Key (DEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-dek
|
||||
:end-before: end-sse-dek
|
||||
|
||||
* - Generate the Key Encryption Key (KEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-kek
|
||||
:end-before: end-sse-kek
|
||||
|
||||
* - Generate the Object Encryption Key (OEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-oek
|
||||
:end-before: end-sse-oek
|
||||
|
||||
* - Encrypt the Object
|
||||
- MinIO uses the |OEK| to encrypt the object *prior* to storing the
|
||||
object to disk. MinIO then encrypts the |OEK| with the |KEK|.
|
||||
|
||||
MinIO stores the encrypted representation of the |OEK| and |DEK| as part
|
||||
of the metadata.
|
||||
|
||||
For read operations, MinIO decrypts the object by retrieving the |EK| to
|
||||
decrypt the |DEK|. MinIO then regenerates the |KEK|, decrypts the |OEK|, and
|
||||
decrypts the object.
|
||||
@@ -0,0 +1,296 @@
|
||||
.. _minio-encryption-sse-s3:
|
||||
|
||||
==================================================
|
||||
Server-Side Encryption Per-Deployment Key (SSE-S3)
|
||||
==================================================
|
||||
|
||||
.. default-domain:: minio
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
.. |EK| replace:: :abbr:`EK (External Key)`
|
||||
.. |DEK| replace:: :abbr:`DEK (Data Encryption Key)`
|
||||
.. |KEK| replace:: :abbr:`KEK (Key Encryption Key)`
|
||||
.. |OEK| replace:: :abbr:`OEK (Object Encryption Key)`
|
||||
.. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)`
|
||||
.. |KMS| replace:: :abbr:`KMS (Key Management Service)`
|
||||
.. |KES| replace:: :abbr:`KES (Key Encryption Service)`
|
||||
|
||||
MinIO Server-Side Encryption (SSE) protects objects as part of write operations,
|
||||
allowing clients to take advantage of server processing power to secure objects
|
||||
at the storage layer (encryption-at-rest). SSE also provides key functionality
|
||||
to regulatory and compliance requirements around secure locking and erasure.
|
||||
|
||||
MinIO SSE uses the :minio-git:`MinIO Key Encryption Service (KES) <kes>` and an
|
||||
external Key Management Service (KMS) for performing secured cryptographic
|
||||
operations at scale. MinIO also supports client-managed key management, where
|
||||
the application takes full responsibility for creating and managing encryption
|
||||
keys for use with MinIO SSE.
|
||||
|
||||
MinIO SSE-S3 en/decrypts objects using an External Key (EK) managed by a
|
||||
Key Management System (KMS). You must specify the |EK| using the
|
||||
:envvar:`MINIO_KMS_KES_KEY_NAME` environment variable when starting up the
|
||||
MinIO server. MinIO uses the same EK for *all* SSE-S3 cryptographic operations.
|
||||
|
||||
You can enable bucket-default SSE-S3 encryption using the
|
||||
:mc-cmd:`mc encrypt set` command:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc encrypt set sse-s3 play/mybucket
|
||||
|
||||
- Replace ``play/mybucket`` with the :mc-cmd:`alias <mc alias>` and bucket
|
||||
on which you want to enable automatic SSE-KMS encryption.
|
||||
|
||||
MinIO SSE-S3 is functionally compatible with AWS S3
|
||||
:s3-docs:`Server-Side Encryption with Amazon S3-Managed Keys
|
||||
<UsingServerSideEncryption.html>` while expanding support to include the
|
||||
following KMS providers:
|
||||
|
||||
- :ref:`AWS SecretsManager <minio-sse-aws>`
|
||||
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
|
||||
- :ref:`Azure Key Vault <minio-sse-azure>`
|
||||
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
|
||||
- Thales CipherTrust (formerly Gemalto KeySecure)
|
||||
|
||||
.. _minio-encryption-sse-s3-quickstart:
|
||||
|
||||
Quickstart
|
||||
----------
|
||||
|
||||
The following procedure uses the ``play`` MinIO |KES| sandbox for
|
||||
supporting |SSE| with SSE-S3 in evaluation and early development environments.
|
||||
|
||||
For extended development or production environments, use one of the following
|
||||
supported external Key Management Services (KMS):
|
||||
|
||||
- :ref:`AWS SecretsManager <minio-sse-aws>`
|
||||
- :ref:`Google Cloud SecretManager <minio-sse-gcp>`
|
||||
- :ref:`Azure Key Vault <minio-sse-azure>`
|
||||
- :ref:`Hashicorp KeyVault <minio-sse-vault>`
|
||||
- Thales CipherTrust (formerly Gemalto KeySecure)
|
||||
|
||||
.. include:: /includes/common-minio-kes.rst
|
||||
:start-after: start-kes-play-sandbox-warning
|
||||
:end-before: end-kes-play-sandbox-warning
|
||||
|
||||
This procedure requires the following components:
|
||||
|
||||
- Install :mc:`mc` on a machine with network access to the source
|
||||
deployment. See the ``mc`` :ref:`Installation Quickstart <mc-install>` for
|
||||
instructions on downloading and installing ``mc``.
|
||||
|
||||
|
||||
- Install :minio-git:`MinIO Key Encryption Service (KES) <kes>` on a machine
|
||||
with internet access. See the ``kes``
|
||||
:minio-git:`Getting Started <kes/wiki/Getting-Started>` guide for
|
||||
instructions on downloading, installing, and configuring KES.
|
||||
|
||||
|
||||
1) Create an Encryption Key for SSE-S3 Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Use the :minio-git:`kes <kes>` commandline tool to create a new External Key
|
||||
(EK) for use with SSE-S3 Encryption.
|
||||
|
||||
Issue the following command to retrieve the root
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>` for the KES
|
||||
server:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
curl -sSL --tlsv1.2 \
|
||||
-O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
|
||||
-O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'
|
||||
|
||||
Set the following environment variables in the terminal or shell:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
export KES_CLIENT_KEY=root.key
|
||||
export KES_CLIENT_CERT=root.cert
|
||||
|
||||
.. list-table::
|
||||
:stub-columns: 1
|
||||
:widths: 40 60
|
||||
:width: 100%
|
||||
|
||||
* - ``KES_CLIENT_KEY``
|
||||
- The private key for an :minio-git:`identity
|
||||
<kes/wiki/Configuration#policy-configuration>` on the KES server.
|
||||
The identity must grant access to at minimum the ``/v1/create``,
|
||||
``/v1/generate``, and ``/v1/list`` :minio-git:`API endpoints
|
||||
<kes/wiki/Server-API#api-overview>`. This step uses the root
|
||||
identity for the MinIO ``play`` KES sandbox, which provides access
|
||||
to all operations on the KES server.
|
||||
|
||||
* - ``KES_CLIENT_CERT``
|
||||
- The corresponding certificate for the :minio-git:`identity
|
||||
<kes/wiki/Configuration#policy-configuration>` on the KES server.
|
||||
This step uses the root identity for the MinIO ``play`` KES
|
||||
sandbox, which provides access to all operations on the KES server.
|
||||
|
||||
Issue the following command to create a new |EK| through
|
||||
KES:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
kes key create my-minio-sse-s3-key
|
||||
|
||||
This tutorial uses the example ``my-minio-sse-s3-key`` name for ease of
|
||||
reference. Specify a unique key name to prevent collision with existing keys.
|
||||
|
||||
2) Configure MinIO for SSE-S3 Object Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Specify the following environment variables in the shell or terminal on each
|
||||
MinIO server host in the deployment:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373
|
||||
export MINIO_KMS_KES_KEY_FILE=root.key
|
||||
export MINIO_KMS_KES_CERT_FILE=root.cert
|
||||
export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key
|
||||
|
||||
.. list-table::
|
||||
:stub-columns: 1
|
||||
:widths: 30 80
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_ENDPOINT`
|
||||
- The endpoint for the MinIO ``Play`` KES service.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_KEY_FILE`
|
||||
- The private key file corresponding to an
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
|
||||
on the KES service. The identity must grant permission to
|
||||
create, generate, and decrypt keys. Specify the same
|
||||
identity key file as the ``KES_KEY_FILE`` environment variable
|
||||
in the previous step.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_CERT_FILE`
|
||||
- The public certificate file corresponding to an
|
||||
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
|
||||
on the KES service. The identity must grant permission to
|
||||
create, generate, and decrypt keys. Specify the same
|
||||
identity certificate as the ``KES_CERT_FILE`` environment
|
||||
variable in the previous step.
|
||||
|
||||
* - :envvar:`MINIO_KMS_KES_KEY_NAME`
|
||||
- The name of the External Key (EK) to use for
|
||||
performing SSE encryption operations. KES retrieves the |EK| from
|
||||
the configured Key Management System (KMS). Specify the name of the
|
||||
key created in the previous step.
|
||||
|
||||
3) Restart the MinIO Deployment to Enable SSE-S3
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must restart the MinIO deployment to apply the configuration changes.
|
||||
Use the :mc-cmd:`mc admin service restart` command to restart the deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc admin service restart ALIAS
|
||||
|
||||
Replace ``ALIAS`` with the :ref:`alias <alias>` of the deployment to
|
||||
restart.
|
||||
|
||||
4) Configure Automatic Bucket Encryption
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
*Optional*
|
||||
|
||||
You can skip this step if you intend to use only client-driven SSE-S3.
|
||||
|
||||
Use the :mc-cmd:`mc encrypt set` command to enable automatic SSE-S3 protection
|
||||
of all objects written to a specific bucket.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc encrypt set sse-s3 ALIAS/BUCKET
|
||||
|
||||
- Replace :mc-cmd:`ALIAS <mc encrypt set ALIAS>` with the
|
||||
:mc:`alias <mc alias>` of the MinIO deployment on which you enabled SSE-S3.
|
||||
|
||||
- Replace :mc-cmd:`BUCKET <mc encrypt set ALIAS>` with the full path to the
|
||||
bucket or bucket prefix on which you want to enable automatic SSE-S3.
|
||||
|
||||
.. _minio-encryption-sse-s3-erasure-locking:
|
||||
|
||||
Secure Erasure and Locking
|
||||
--------------------------
|
||||
|
||||
SSE-S3 protects objects using an |EK| specified at server startup
|
||||
using the :envvar:`MINIO_KMS_KES_KEY_NAME` environment variable. MinIO
|
||||
therefore *requires* access to that |EK| for decrypting that object.
|
||||
|
||||
- Disabling the |EK| temporarily locks SSE-S3-encrypted objects in the
|
||||
deployment by rendering them unreadable. You can later enable the |EK|
|
||||
to resume normal read operations.
|
||||
|
||||
- Deleting the |EK| renders all SSE-S3-encrypted objects in the deployment
|
||||
*permanently* unreadable. If the KMS does not have or support backups
|
||||
of the |EK|, this process is *irreversible*.
|
||||
|
||||
The scope of the |EK| depends on:
|
||||
|
||||
- Which buckets specified automatic SSE-S3 encryption, *and*
|
||||
- Which write operations requested SSE-S3 encryption.
|
||||
|
||||
.. _minio-encryption-sse-s3-encryption-process:
|
||||
|
||||
Encryption Process
|
||||
------------------
|
||||
|
||||
.. note::
|
||||
|
||||
The following section describes MinIO internal logic and functionality.
|
||||
This information is purely educational and is not necessary for
|
||||
configuring or implementing any MinIO feature.
|
||||
|
||||
SSE-S3 uses an External Key (EK) managed by the configured Key Management
|
||||
System (KMS) for performing cryptographic operations and protecting objects.
|
||||
The table below describes each stage of the encryption process:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 30 70
|
||||
|
||||
* - Stage
|
||||
- Description
|
||||
|
||||
* - SSE-Enabled Write Operation
|
||||
- MinIO receives a write operation requesting SSE-S3 encryption.
|
||||
MinIO uses the key name specified to
|
||||
:envvar:`MINIO_KMS_KES_KEY_NAME` as the External Key (EK).
|
||||
|
||||
* - Generate the Data Encryption Key (DEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-dek
|
||||
:end-before: end-sse-dek
|
||||
|
||||
* - Generate the Key Encryption Key (KEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-kek
|
||||
:end-before: end-sse-kek
|
||||
|
||||
* - Generate the Object Encryption Key (OEK)
|
||||
- .. include:: /includes/common-minio-sse.rst
|
||||
:start-after: start-sse-oek
|
||||
:end-before: end-sse-oek
|
||||
|
||||
* - Encrypt the Object
|
||||
- MinIO uses the |OEK| to encrypt the object *prior* to storing the
|
||||
object to disk. MinIO then encrypts the |OEK| with the |KEK|.
|
||||
|
||||
MinIO stores the encrypted representation of the |OEK| and |DEK| as part
|
||||
of the metadata.
|
||||
Reference in New Issue
Block a user