Server-Side Object Encryption with Azure Key Vault Root KMS

Azure Key Vault

This procedure assumes familiarity with Azure Key Vault. The Key Vault Quickstart provides a sufficient foundation for the purposes of this procedure.

MinIO specifically requires the following Azure settings or configurations:

• Register an application for KES (e.g. minio-kes). Note the Application (client) ID, Directory (tenant) ID, and Client credentials. You may need to create the client credentials secret and copy the Secret Value for use in this procedure.

• Create an Access Policy for use by KES. The policy must have the following Secret Permissions:

  • Get

  • List

  • Set

  • Delete

  • Purge

  Set the Principal for the new policy to the KES Application ID.

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-11-10T10-44-28Z) 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-11-10T10-44-28Z/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-azure\certs

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

C:\kes.exe identity new \
  --key  C:\minio-kes-azure\certs\minio-kes.key \
  --cert C:\minio-kes-azure\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-azure\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-azure\certs\kes-server.key
     cert: C:\minio-kes-azure\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/*   # You can replace these wildcard '*' with a string prefix to restrict key names
       - /v1/key/generate/* # e.g. '/minio-'
       - /v1/key/decrypt/*
       - /v1/key/bulk/decrypt
       - /v1/key/list/*
       - /v1/status
       - /v1/metrics
       - /v1/log/audit
       - /v1/log/error
       identities:
       - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
   
   # Specify the connection information for the Key Vualt endpoint.
   # The endpoint should be resolvable from the host.
   # This example assumes that the specified Key Vault and Azure tenant/client
   # have the necessary permissions set.
   
   keystore:
     azure:
       keyvault:
         endpoint: "https://<keyvaultinstance>vault.azure.net" # The Azure Keyvault Instance Endpoint
         credentials:
           tenant_id: "${TENANTID}" # The directory/tenant UUID
           client_id: "${CLIENTID}" # The application/client UUID
           client_secret: "${CLIENTSECRET}" # The Active Directory secret for the application
   

   • 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-azure\certs/minio-kes.cert
     

   • Replace the endpoint with the URL for the Keyvault instance.

   • Set TENANTID, CLIENTID, and CLIENTSECRET to match the credentials for a project user with the required permissions.

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-azure\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-azure\certs\minio-kes.cert
   MINIO_KMS_KES_KEY_FILE=C:\minio-kes-azure\certs\minio-kes.key
   MINIO_KMS_KES_CAPATH=C:\minio-kes-azure\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-azure\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-azure\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-azure\certs\minio-kes.key
export KES_CLIENT_CERT=C:\minio-kes-azure\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