github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/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 haven't installed MinIO, yet, then follow the MinIO [install instructions](https://min.io/docs/minio/linux/index.html#quickstart-for-linux) first.
     8  
     9  ### 1. Fetch the root identity
    10  
    11  As the initial step, fetch the private key and certificate of the root identity:
    12  
    13  ```sh
    14  curl -sSL --tlsv1.2 \
    15       -O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
    16       -O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'
    17  ```
    18  
    19  ### 2. Set the MinIO-KES configuration
    20  
    21  ```sh
    22  export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373
    23  export MINIO_KMS_KES_KEY_FILE=root.key
    24  export MINIO_KMS_KES_CERT_FILE=root.cert
    25  export MINIO_KMS_KES_KEY_NAME=my-minio-key
    26  ```
    27  
    28  ### 3. Start the MinIO Server
    29  
    30  ```sh
    31  export MINIO_ROOT_USER=minio
    32  export MINIO_ROOT_PASSWORD=minio123
    33  minio server ~/export
    34  ```
    35  
    36  > The KES instance at `https://play.min.io:7373` is meant to experiment and provides a way to get started quickly.
    37  > Note that anyone can access or delete master keys at `https://play.min.io:7373`. You should run your own KES
    38  > instance in production.
    39  
    40  ## Configuration Guides
    41  
    42  A typical MinIO deployment that uses a KMS for SSE-S3 looks like this:
    43  
    44  ```
    45      ┌────────────┐
    46      │ ┌──────────┴─┬─────╮          ┌────────────┐
    47      └─┤ ┌──────────┴─┬───┴──────────┤ ┌──────────┴─┬─────────────────╮
    48        └─┤ ┌──────────┴─┬─────┬──────┴─┤ KES Server ├─────────────────┤
    49          └─┤   MinIO    ├─────╯        └────────────┘            ┌────┴────┐
    50            └────────────┘                                        │   KMS   │
    51                                                                  └─────────┘
    52  ```
    53  
    54  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.
    55  
    56  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:
    57  
    58  | KMS                                                                                          | Purpose                                                           |
    59  |:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------|
    60  | [Hashicorp Vault](https://github.com/minio/kes/wiki/Hashicorp-Vault-Keystore)                | Local KMS. MinIO and KMS on-prem (**Recommended**)                |
    61  | [AWS-KMS + SecretsManager](https://github.com/minio/kes/wiki/AWS-SecretsManager)             | Cloud KMS. MinIO in combination with a managed KMS installation   |
    62  | [Gemalto KeySecure /Thales CipherTrust](https://github.com/minio/kes/wiki/Gemalto-KeySecure) | Local KMS. MinIO and KMS On-Premises.                             |
    63  | [Google Cloud Platform SecretManager](https://github.com/minio/kes/wiki/GCP-SecretManager)   | Cloud KMS. MinIO in combination with a managed KMS installation   |
    64  | [FS](https://github.com/minio/kes/wiki/Filesystem-Keystore)                                  | Local testing or development (**Not recommended for production**) |
    65  
    66  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).
    67  
    68  ### Further references
    69  
    70  - [Run MinIO with TLS / HTTPS](https://min.io/docs/minio/linux/operations/network-encryption.html)
    71  - [Tweak the KES server configuration](https://github.com/minio/kes/wiki/Configuration)
    72  - [Run a load balancer infront of KES](https://github.com/minio/kes/wiki/TLS-Proxy)
    73  - [Understand the KES server concepts](https://github.com/minio/kes/wiki/Concepts)
    74  
    75  ## Auto Encryption
    76  
    77  Auto-Encryption is useful when MinIO administrator wants to ensure that all data stored on MinIO is encrypted at rest.
    78  
    79  ### Using `mc encrypt` (recommended)
    80  
    81  MinIO automatically encrypts all objects on buckets if KMS is successfully configured and bucket encryption configuration is enabled for each bucket as shown below:
    82  
    83  ```
    84  mc encrypt set sse-s3 myminio/bucket/
    85  ```
    86  
    87  Verify if MinIO has `sse-s3` enabled
    88  
    89  ```
    90  mc encrypt info myminio/bucket/
    91  Auto encryption 'sse-s3' is enabled
    92  ```
    93  
    94  ### Using environment (not-recommended)
    95  
    96  MinIO automatically encrypts all objects on buckets if KMS is successfully configured and following ENV is enabled:
    97  
    98  ```
    99  export MINIO_KMS_AUTO_ENCRYPTION=on
   100  ```
   101  
   102  ### Verify auto-encryption
   103  
   104  > Note that auto-encryption only affects requests without S3 encryption headers. So, if a S3 client sends
   105  > e.g. SSE-C headers, MinIO will encrypt the object with the key sent by the client and won't reach out to
   106  > the configured KMS.
   107  
   108  To verify auto-encryption, use the following `mc` command:
   109  
   110  ```
   111  mc cp test.file myminio/bucket/
   112  test.file:              5 B / 5 B  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100.00% 337 B/s 0s
   113  ```
   114  
   115  ```
   116  mc stat myminio/bucket/test.file
   117  Name      : test.file
   118  ...
   119  Encrypted :
   120    X-Amz-Server-Side-Encryption: AES256
   121  ```
   122  
   123  ## Encrypted Private Key
   124  
   125  MinIO supports encrypted KES client private keys. Therefore, you can use
   126  an password-protected private keys for `MINIO_KMS_KES_KEY_FILE`.
   127  
   128  When using password-protected private keys for accessing KES you need to
   129  provide the password via:
   130  
   131  ```
   132  export MINIO_KMS_KES_KEY_PASSWORD=<your-password>
   133  ```
   134  
   135  Note that MinIO only supports encrypted private keys - not encrypted certificates.
   136  Certificates are no secrets and sent in plaintext as part of the TLS handshake.
   137  
   138  ## Explore Further
   139  
   140  - [Use `mc` with MinIO Server](https://min.io/docs/minio/linux/reference/minio-mc.html)
   141  - [Use `aws-cli` with MinIO Server](https://min.io/docs/minio/linux/integrations/aws-cli-with-minio.html)
   142  - [Use `minio-go` SDK with MinIO Server](https://min.io/docs/minio/linux/developers/go/minio-go.html)
   143  - [The MinIO documentation website](https://min.io/docs/minio/linux/index.html)