docs/source/security/server-side-encryption/configure-minio-kes-hashicorp.rst

Server-Side Object Encryption with Hashicorp Vault Root KMS

minio

Table of Contents

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 Key Encryption Service (KES) <kes> and an external root Key Management Service (KMS) for performing secured cryptographic operations at scale. The root KMS provides stateful and secured storage of External Keys (EK) while KES (Key Encryption Service) is stateless and derives additional cryptographic keys from the root-managed EK (External Key).

This procedure does the following:

• Configure KES (Key Encryption Service) to use Hashicorp Vault as the root KMS (Key Management System).
• Configure MinIO to use the KES (Key Encryption Service) instance for supporting SSE (Server-Side Encryption).
• Configure automatic bucket-default SSE-KMS <minio-encryption-sse-kms> and SSE-S3 <minio-encryption-sse-s3>.

Prerequisites

Hashicorp Vault

This procedure assumes familiarity with Hashicorp Vault. The Vault Quick Start provides a sufficient foundation for the purposes of this procedure.

MinIO specifically requires the following Vault settings or configurations:

• Enable the Vault K/V engine. KES version 0.15.0 and later support both the v1 and v2 engines. This procedure uses the v1 engine.

• For K/V v1, create an access policy kes-policy.hcl with a configuration similar to the following:

  path "kv/*" {
       capabilities = [ "create", "read", "delete" ]
  }

  Write the policy to Vault using vault policy write kes-policy kes-policy.hcl.

• For K/V v2, create an access policy kes-policy.hcl with a configuration similar to the following:

  path "kv/data/*" {
       capabilities = [ "create", "read"]
  
  path "kv/metadata/*" {
       capabilities = [ "list", "delete"]

  Write the policy to Vault using vault policy write kes-policy kes-policy.hcl

• Enable Vault AppRole authentication, create an AppRole ID, bind it to the necessary policy, and request both roleID and secret ID.

  vault write    auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m
  vault write    auth/approle/role/kes-role policies=kes-policy
  vault read     auth/approle/role/kes-role/role-id
  vault write -f auth/approle/role/kes-role/secret-id

The instructions on this page include configuring and starting Vault for supporting development/evaluation of MinIO SSE (Server-Side Encryption). DO NOT use these instructions for deploying Vault for any long-term development or production environments. Extended development and production environments should defer to the Vault Documentation for specific guidance on deployment and configuration.

Network Encryption (TLS)

Podman Container Manager

Enable MinIO Server-Side Encryption with Hashicorp Vault

The following steps deploy Key Encryption Service (KES) <kes> configured to use an existing Hashicorp Vault deployment as the root KMS for supporting SSE (Server-Side Encryption). These steps assume the Vault deployment meets the prerequisites <minio-sse-vault-prereq-vault>.

Prior to starting these steps, create the following folders:

mkdir -P ~/kes/certs ~/kes/config

1) Download the MinIO Key Encryption Service

2) Generate the TLS Private and Public Key for KES

3) Generate the TLS Private and Public Key for MinIO

4) Create the KES Configuration File

KES (Key Encryption Service) uses a YAML-formatted configuration file. The following example YAML specifies the minimum required fields for enabling SSE (Server-Side Encryption) using Hashicorp Vault:

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:  /data/certs/server.key
  cert: /data/certs/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 tool identity of minio-kes.cert'

# Specify the connection information for the Vault server.
# The endpoint should be resolvable from the host.
# This example assumes that Vault is configured with an AppRole ID and
# Secret for use with KES.
keystore:
  vault:
    endpoint: https://HOSTNAME:8200
    approle:
      id: "${VAULTAPPID}"     # Hashicorp Vault AppRole ID
      secret: "${VAULTAPPSECRET}" # Hashicorp Vault AppRole Secret ID
      retry: 15s
    status:
      ping: 10s
    # Required if Vault uses certificates signed by an unknown CA,
    # e.g. self-signed or internal (non-globally trusted).  
    tls:
      ca: vault-tls.cert 

Save the configuration file as ~/kes/config/kes-config.yaml. Any field with value ${VARIABLE} uses the environment variable with matching name as the value. You can use this functionality to set credentials without writing them to the configuration file.

• Set MINIO_IDENTITY_HASH to the output of kes tool identity of minio-kes.cert.
• Replace the vault.endpoint with the hostname of the Vault server(s).
• Replace the VAULTAPPID and VAULTAPPSECRET with the appropriate Vault AppRole credentials <minio-sse-vault-prereq-vault>.

5) Start KES

6) Generate a Cryptographic Key

You can check the newly created key on the Vault server by running the vault kv list kv/ command, where kv/ is the path to the vault storing KES (Key Encryption Service)-generated keys.

7) Configure MinIO to connect to KES

8) Enable Automatic Server-Side Encryption

SSE-KMS

The following command enables SSE-KMS on all objects written to the specified bucket:

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

Replace ALIAS with the alias <mc alias> of the MinIO deployment configured in the previous step.

Write a file to the bucket using mc cp or any S3-compatible SDK with a PutObject function. You can then run mc stat on the file to confirm the associated encryption metadata.

SSE-S3

The following command enables SSE-S3 on all objects written to the specified bucket. MinIO uses the MINIO_KMS_KES_KEY_NAME key for performing SSE (Server-Side Encryption).

mc mb ALIAS/encryptedbucket
mc encrypt set SSE-S3 ALIAS/encryptedbucket

Replace ALIAS with the alias <mc alias> of the MinIO deployment configured in the previous step.

Write a file to the bucket using mc cp or any S3-compatible SDK with a PutObject function. You can then run mc stat on the file to confirm the associated encryption metadata.

Configuration Reference for Hashicorp Vault

The following section describes each of the Key Encryption Service (KES) <kes> configuration settings for using Hashicorp Vault as the root Key Management Service (KMS) for SSE (Server-Side Encryption):

YAML Overview

The following YAML describes the minimum required fields for configuring Hashicorp Vault as an external KMS for supporting SSE (Server-Side Encryption).

Any field with value ${VARIABLE} uses the environment variable with matching name as the value. You can use this functionality to set credentials without writing them to the configuration file.

address: 0.0.0.0:7373
root: ${ROOT_IDENTITY}

tls:
  key: kes-server.key
  cert: kes-server.cert

policy:
  minio-server:
    allow:
      - /v1/key/create/*
      - /v1/key/generate/*
      - /v1/key/decrypt/*
    identities:
    - ${MINIO_IDENTITY}

keys:
  - name: "minio-encryption-key-alpha"
  - name: "minio-encryption-key-baker"
  - name: "minio-encryption-key-charlie"

keystore:
  vault:
    endpoint: https://vault.example.net:8200
    approle:
      id: ${KES_APPROLE_ID}
      secret: ${KES_APPROLE_SECRET}
      retry: 15s
    status:
      ping: 10s
    tls:
      ca: vault-tls.cert

Reference

Key	Description
address
root
tls
policy
keys
keystore.vault	The configuration for the Hashicorp Vault keystore. The following fields are required: endpoint - The hostname for the vault server(s). The hostname must be resolvable by the KES server host. approle - The AppRole used by KES for performing authenticated operations against Vault. The specified AppRole must have the appropriate permissions <minio-sse-vault-prereq-vault> tls.ca - The Certificate Authority used to sign the Vault TLS certificates. Typically required if the Vault server uses self-signed certificates or is signed by an unknown CA (internal or non-global).