storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/docs/kms/README.md (about)

     1  # KMS Guide [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
     2  
     3  MinIO uses a key-management-system (KMS) to support SSE-S3. If a client requests SSE-S3, or auto-encryption is enabled, the MinIO server encrypts each object with an unique object key which is protected by a master key managed by the KMS.
     4  
     5  ## Quick Start
     6  
     7  MinIO supports multiple KMS implementations via our [KES](https://github.com/minio/kes#kes) project. We run a KES instance at `https://play.min.io:7373` for you to experiment and quickly get started. To run MinIO with a KMS just fetch the root identity, set the following environment variables and then start your MinIO server. If you havn't installed MinIO, yet, then follow the MinIO [install instructions](https://docs.min.io/docs/minio-quickstart-guide) first.
     8  
     9  #### 1. Fetch the root identity
    10  As the initial step, fetch the private key and certificate of the root identity:
    11  
    12  ```sh
    13  curl -sSL --tlsv1.2 \
    14       -O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
    15       -O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'
    16  ```
    17  
    18  #### 2. Set the MinIO-KES configuration
    19  
    20  ```sh
    21  export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373
    22  export MINIO_KMS_KES_KEY_FILE=root.key
    23  export MINIO_KMS_KES_CERT_FILE=root.cert
    24  export MINIO_KMS_KES_KEY_NAME=my-minio-key
    25  ```
    26  
    27  #### 3. Start the MinIO Server
    28  
    29  ```sh
    30  export MINIO_ROOT_USER=minio
    31  export MINIO_ROOT_PASSWORD=minio123
    32  minio server ~/export
    33  ```
    34  
    35  > The KES instance at `https://play.min.io:7373` is meant to experiment and provides a way to get started quickly.
    36  > Note that anyone can access or delete master keys at `https://play.min.io:7373`. You should run your own KES
    37  > instance in production.
    38  
    39  ## Configuration Guides
    40  
    41  A typical MinIO deployment that uses a KMS for SSE-S3 looks like this:
    42  ```
    43      ┌────────────┐
    44      │ ┌──────────┴─┬─────╮          ┌────────────┐
    45      └─┤ ┌──────────┴─┬───┴──────────┤ ┌──────────┴─┬─────────────────╮
    46        └─┤ ┌──────────┴─┬─────┬──────┴─┤ KES Server ├─────────────────┤
    47          └─┤   MinIO    ├─────╯        └────────────┘            ┌────┴────┐
    48            └────────────┘                                        │   KMS   │
    49                                                                  └─────────┘
    50  ```
    51  
    52  In a given setup, there are `n` MinIO instances talking to `m` KES servers but only `1` central KMS. The most simple setup consists of `1` MinIO server or cluster talking to `1` KMS via `1` KES server.
    53  
    54  The main difference between various MinIO-KMS deployments is the KMS implementation. The following table helps you select the right option for your use case:
    55  
    56  | KMS                                                                                          | Purpose                                                           |
    57  |:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------|
    58  | [Hashicorp Vault](https://github.com/minio/kes/wiki/Hashicorp-Vault-Keystore)                | Local KMS. MinIO and KMS on-prem (**Recommended**)                |
    59  | [AWS-KMS + SecretsManager](https://github.com/minio/kes/wiki/AWS-SecretsManager)             | Cloud KMS. MinIO in combination with a managed KMS installation   |
    60  | [Gemalto KeySecure /Thales CipherTrust](https://github.com/minio/kes/wiki/Gemalto-KeySecure) | Local KMS. MinIO and KMS On-Premises.                             |
    61  | [Google Cloud Platform SecretManager](https://github.com/minio/kes/wiki/GCP-SecretManager)   | Cloud KMS. MinIO in combination with a managed KMS installation   |
    62  | [FS](https://github.com/minio/kes/wiki/Filesystem-Keystore)                                  | Local testing or development (**Not recommended for production**) |
    63  
    64  
    65  The MinIO-KES configuration is always the same - regardless of the underlying KMS implementation. Checkout the MinIO-KES [configuration example](https://github.com/minio/kes/wiki/MinIO-Object-Storage).
    66  
    67  ### Further references
    68  
    69  - [Run MinIO with TLS / HTTPS](https://docs.min.io/docs/how-to-secure-access-to-minio-server-with-tls.html)
    70  - [Tweak the KES server configuration](https://github.com/minio/kes/wiki/Configuration)
    71  - [Run a load balancer infront of KES](https://github.com/minio/kes/wiki/TLS-Proxy)
    72  - [Understand the KES server concepts](https://github.com/minio/kes/wiki/Concepts)
    73  
    74  ## Auto Encryption
    75  Auto-Encryption is useful when MinIO administrator wants to ensure that all data stored on MinIO is encrypted at rest.
    76  
    77  ### Using `mc encrypt` (recommended)
    78  MinIO automatically encrypts all objects on buckets if KMS is successfully configured and bucket encryption configuration is enabled for each bucket as shown below:
    79  ```
    80  mc encrypt set sse-s3 myminio/bucket/
    81  ```
    82  
    83  Verify if MinIO has `sse-s3` enabled
    84  ```
    85  mc encrypt info myminio/bucket/
    86  Auto encryption 'sse-s3' is enabled
    87  ```
    88  
    89  ### Using environment (deprecated)
    90  > NOTE: The following ENV might be removed in future, you are advised to move to the previously recommended approach using `mc encrypt`. S3 gateway supports encryption at gateway layer which may  be dropped in favor of simplicity at a later time. It is advised that S3 gateway users migrate to MinIO server mode or enable encryption at REST at the backend.
    91  
    92  MinIO automatically encrypts all objects on buckets if KMS is successfully configured and following ENV is enabled:
    93  ```
    94  export MINIO_KMS_AUTO_ENCRYPTION=on
    95  ```
    96  
    97  ### Verify auto-encryption
    98  > Note that auto-encryption only affects requests without S3 encryption headers. So, if a S3 client sends
    99  > e.g. SSE-C headers, MinIO will encrypt the object with the key sent by the client and won't reach out to
   100  > the configured KMS.
   101  
   102  To verify auto-encryption, use the following `mc` command:
   103  
   104  ```
   105  mc cp test.file myminio/bucket/
   106  test.file:              5 B / 5 B  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100.00% 337 B/s 0s
   107  ```
   108  
   109  ```
   110  mc stat myminio/bucket/test.file
   111  Name      : test.file
   112  ...
   113  Encrypted :
   114    X-Amz-Server-Side-Encryption: AES256
   115  ```
   116  
   117  ## Explore Further
   118  
   119  - [Use `mc` with MinIO Server](https://docs.min.io/docs/minio-client-quickstart-guide)
   120  - [Use `aws-cli` with MinIO Server](https://docs.min.io/docs/aws-cli-with-minio)
   121  - [Use `s3cmd` with MinIO Server](https://docs.min.io/docs/s3cmd-with-minio)
   122  - [Use `minio-go` SDK with MinIO Server](https://docs.min.io/docs/golang-client-quickstart-guide)
   123  - [The MinIO documentation website](https://docs.min.io)