Server-Side Object Encryption with AWS Secrets Manager Root KMS

Ensure Access to the AWS Secrets Manager and Key Management Service

This procedure assumes access to and familiarity with AWS Secrets Manager and |rootkms-short|.

MinIO specifically requires the following AWS settings or configurations:

• A new AWS Programmatic Access user with corresponding access key and secret key.

• A policy that grants the created user access to AWS Secrets Manager and AWS Secrets Manager. The following policy grants the minimum necessary permissions:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "minioSecretsManagerAccess",
        "Action": [
          "secretsmanager:CreateSecret",
          "secretsmanager:DeleteSecret",
          "secretsmanager:GetSecretValue",
          "secretsmanager:ListSecrets"
        ],
        "Effect": "Allow",
        "Resource": "*"
      },
      {
        "Sid": "minioKmsAccess",
        "Action": [
          "kms:Decrypt",
          "kms:DescribeKey",
          "kms:Encrypt"
        ],
        "Effect": "Allow",
        "Resource": "*"
      }
    ]
  }
  

  AWS provides the SecretsManagerReadWrite and AWSKeyManagementServicePowerUser canned roles that meet and exceed the minimum required permissions.

Deploy or Ensure Access to a MinIO Deployment

This procedure provides instructions for modifying the startup environment variables of a MinIO deployment to enable SSE via KES and the root KMS.

For instructions on new production deployments, see the Multi-Node Multi-Drive (Distributed) tutorial. For instructions on new local or evaluation deployments, see the Single-Node Single-Drive tutorial.

When creating the environment file for the deployment, pause and switch back to this tutorial to include the necessary environment variables to support SSE.

For existing MinIO Deployments, you can modify the existing environment file and restart the deployment as instructed during this procedure.

1) Download KES for Windows

Download the latest stable release (2023-02-15T14-54-37Z) of KES from github.com/minio/kes. The following PowerShell command downloads the latest Windows-compatible binary and moves it to the system PATH:

Invoke-WebRequest -Uri "https://github.com/minio/kes/releases/download/2023-02-15T14-54-37Z/kes-linux-windows-amd64.exe" -OutFile "C:\kes.exe"

C:\kes.exe --version

2) Generate TLS Certificates for KES and MinIO

The following commands creates two TLS certificates that expire within 30 days of creation:

• A TLS certificate for KES to secure communications between it and the Vault deployment

• A TLS certificate for MinIO to perform mTLS authentication to KES.

# These commands output the certificates to C:\minio-kes-aws\certs

C:\kes.exe identity new \
  --key  C:\minio-kes-aws\certs\kes-server.key \
  --cert C:\minio-kes-aws\certs\kes-server.cert \
  --ip   "127.0.0.1" \
  --dns  localhost

C:\kes.exe identity new \
  --key  C:\minio-kes-aws\certs\minio-kes.key \
  --cert C:\minio-kes-aws\certs\minio-kes.cert \
  --ip   "127.0.0.1" \
  --dns  localhost

The --ip and --dns parameters set the IP and DNS SubjectAlternativeName for the certificate. The above example assumes that all components (Vault, MinIO, and KES) deploy on the same local host machine accessible via localhost or 127.0.0.1. You can specify additional IP or Hostnames based on the network configuration of your local host.

Depending on your Vault configuration, you may need to pass the kes-server.cert as a trusted Certificate Authority. See the Hashicorp Server Configuration Documentation for more information. Defer to the client documentation for instructions on trusting a third-party CA.

3) Create the KES and MinIO Configurations

1. Create the KES Configuration File

   Create the configuration file using your preferred text editor. The following example uses the Windows Notepad program:

   notepad C:\minio-kes-aws\config\kes-config.yaml
   

   KES uses a YAML-formatted configuration file. The following example YAML specifies the minimum required fields for enabling SSE using AWS Secrets Manager:

   address: 0.0.0.0:7373
   
   # Disable the root identity, as we do not need that level of access for
   # supporting SSE operations.
   root: disabled
   
   # Specify the TLS keys generated in the previous step here
   # For production environments, use keys signed by a known and trusted
   # Certificate Authority (CA).
   tls:
     key:  C:\minio-kes-aws\certs\kes-server.key
     cert: C:\minio-kes-aws\certs\kes-server.cert
   
   # Create a policy named 'minio' that grants access to the
   # /create, /generate, and /decrypt KES APIs for any key name
   # KES uses mTLS to grant access to this policy, where only the client
   # whose TLS certificate hash matches one of the "identities" can
   # use this policy. Specify the hash of the MinIO server TLS certificate
   # hash here.
   policy:
     minio:
       allow:
       - /v1/key/create/*
       - /v1/key/generate/*
       - /v1/key/decrypt/*
       identities:
       - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
   
                                # In production environments, each client connecting to KES must
                                # Have their TLS hash listed under at least one `policy`.
   
   # Specify the connection information for the KMS and Secrets Manager endpoint.
   # The endpoint should be resolvable from the host.
   # This example assumes that the associated AWS account has the necessary
   # access key and secret key
   keystore:
     aws:
       secretsmanager:
         endpoint: secretsmanager.REGION.amazonaws.com # use the Secrets Manager endpoint for your region
         region: REGION # e.g. us-east-1
         kmskey: "" # Optional. The root AWS KMS key to use for cryptographic operations. Formerly described as the "Customer Master Key".
         credentials:
           accesskey: "AWSACCESSKEY" # AWS Access Key
           secretkey: "AWSSECRETKEY" # AWS Secret Key
   

   • Set MINIO_IDENTITY_HASH to the identity hash of the MinIO mTLS certificate.

     The following command computes the necessary hash:

     kes.exe tool identity of C:\minio-kes-aws\certs/minio-kes.cert
     

   • Replace the REGION with the appropriate region for AWS Secrets Manager. The value must match for both endpoint and region.

   • Set AWSACCESSKEY and AWSSECRETKEY to the appropriate AWS Credentials.

2. Create the MinIO Environment File

   Create the environment file using your preferred text editor. The following example uses the Windows Notepad program:

   notepad C:\minio-kes-aws\config\minio
   

   Add the following lines to the MinIO Environment file on the Windows host. See the tutorials for Deploy MinIO: Single-Node Single-Drive for more detailed descriptions of a base MinIO environment file.

   This command assumes the minio-kes.cert, minio-kes.key, and kes-server.cert certificates are accessible at the specified location:

   # Add these environment variables to the existing environment file
   
   MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
   MINIO_KMS_KES_CERT_FILE=C:\minio-kes-aws\certs\minio-kes.cert
   MINIO_KMS_KES_KEY_FILE=C:\minio-kes-aws\certs\minio-kes.key
   MINIO_KMS_KES_CAPATH=C:\minio-kes-aws\certs\kes-server.cert
   MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
   MINIO_KMS_KES_ENCLAVE=<name>
   

   MinIO uses the MINIO_KMS_KES_KEY_NAME key for the following cryptographic operations:

   • Encrypting the MinIO backend (IAM, configuration, etc.)

   • Encrypting objects using SSE-KMS if the request does not include a specific EK.

   • Encrypting objects using SSE-S3.

   MinIO uses the MINIO_KMS_KES_ENCLAVE key to define the name of the KES enclave to use for stateful KES servers.

   • Replace <name> with the name of the enclave to use.

   • If not defined, MinIO does not send any enclave information. This may result in using the default enclave for stateful KES servers.

     A KES enclave provides an isolated space for its associated keys separate from other enclaves on a stateful KES server.

   The minio-kes certificates enable mTLS between the MinIO deployment and the KES server only. They do not otherwise enable TLS for other client connections to MinIO.

4) Start KES and MinIO

You must start KES before starting MinIO. The MinIO deployment requires access to KES as part of its startup.

1. Start the KES Server

   Run the following command in a terminal or shell to start the KES server as a foreground process.

   C:\kes.exe server --auth --config=C:\minio-kes-aws\config\config\kes-config.yaml
   

   Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background.

2. Start the MinIO Server

   Run the following command in a terminal or shell to start the MinIO server as a foreground process.

   export MINIO_CONFIG_ENV_FILE=C:\minio-kes-aws\config\config\minio
   C:\minio.exe server --console-address :9090
   

5) Generate a New Encryption Key

MinIO requires that the EK exist on the root KMS before performing SSE operations using that key. Use kes key create or mc admin kms key create to create a new EK for use with SSE.

The following command uses the kes key create command to create a new External Key (EK) stored on the root KMS server for use with encrypting the MinIO backend.

export KES_SERVER=https://127.0.0.1:7373
export KES_CLIENT_KEY=C:\minio-kes-aws\certs\minio-kes.key
export KES_CLIENT_CERT=C:\minio-kes-aws\certs\minio-kes.cert

C:\kes.exe key create -k encrypted-bucket-key

6) Enable SSE-KMS for a Bucket

You can use either the MinIO Console or the MinIO mc CLI to enable bucket-default SSE-KMS with the generated key:

mc alias set local http://127.0.0.1:9000 ROOTUSER ROOTPASSWORD

mc mb local/encryptedbucket
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket