docs/source/operations/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).

linux

This procedure provides guidance for deploying and configuring KES at scale for a supporting SSE (Server-Side Encryption) on a production MinIO deployment. You can also use this procedure for deploying to local environments for testing and evaluation.

As part of this procedure, you will:

1. Deploy one or more KES (Key Encryption Service) servers configured to use Hashicorp Vault as the root KMS (Key Management System). You may optionally deploy a load balancer for managing connections to those KES servers.
2. Create a new EK (External Key) on Vault for use with SSE (Server-Side Encryption).
3. Create or modify a MinIO deployment with support for SSE (Server-Side Encryption) using KES (Key Encryption Service). Defer to the Deploy Distributed MinIO <minio-mnmd> tutorial for guidance on production-ready MinIO deployments.
4. Configure automatic bucket-default SSE-KMS <minio-encryption-sse-kms>

For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with SSE (Server-Side Encryption) enabled and configured for use with Hashicorp Vault.

macos or windows

This procedure assumes a single local host machine running the MinIO and KES processes. As part of this procedure, you will:

1. Deploy a KES (Key Encryption Service) server configured to use Vault as the root KMS (Key Management System).
2. Create a new EK (External Key) on Vault for use with SSE (Server-Side Encryption).
3. Deploy a MinIO server in Single-Node Single-Drive mode <minio-snsd> configured to use the KES (Key Encryption Service) container for supporting SSE (Server-Side Encryption).
4. Configure automatic bucket-default SSE-KMS <minio-encryption-sse-kms>.

For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with SSE (Server-Side Encryption) enabled and configured for use with Hashicorp Vault.

For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.

container

This procedure assumes a single host machine running the MinIO and KES containers. As part of this procedure, you will:

1. Deploy a KES (Key Encryption Service) container configured to use Vault as the root KMS (Key Management System).
2. Create a new EK (External Key) on Vault for use with SSE (Server-Side Encryption).
3. Deploy a MinIO Server container in Single-Node Single-Drive mode <minio-snsd> configured to use the KES (Key Encryption Service) container for supporting SSE (Server-Side Encryption).
4. Configure automatic bucket-default SSE-KMS <minio-encryption-sse-kms>.

For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with SSE (Server-Side Encryption) enabled and configured for use with Hashicorp Vault.

For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.

k8s

This procedure assumes you have access to a Kubernetes cluster with an active MinIO Operator installation. As part of this procedure, you will:

1. Use the MinIO Operator Console to create or manage a MinIO Tenant.
2. Access the Encryption settings for that tenant and configure SSE (Server-Side Encryption) using Vault.
3. Create a new EK (External Key) on Vault for use with SSE (Server-Side Encryption).
4. Configure automatic bucket-default SSE-KMS <minio-encryption-sse-kms>.

For production baremetal environments, see the MinIO on Linux documentation for tutorials on configuring MinIO with KES and Hashicorp Vault.

Important

Prerequisites

k8s

MinIO Kubernetes Operator and Plugin

See deploy-operator-kubernetes for complete documentation on deploying the MinIO Operator.

Deploy or Ensure Access to a Hashicorp Vault Service

linux or macos or windows or container

k8s

MinIO KES (Key Encryption Service) supports either the V1 or V2 Vault K/V engines.

MinIO KES requires using AppRole authentication to the Vault server. You must create an AppRole, assign it a policy that the necessary permissions, and retrieve the AppRole ID and Secret for use in configuring KES.

You can use the following steps to enable AppRole authentication and create the necessary policies to support core KES functionality against Vault:

1. Enable AppRole Authentication

   vault auth enable approle

2. Create a Policy for KES

   Create a policy with necessary capabilities for KES to use when accessing Vault. Select the tab corresponding to the KV engine used for storing KES secrets:

   Vault Engine 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.

   Vault Engine 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

3. Create an AppRole for KES and assign it the created policy

   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

4. Retrieve the AppRole ID and Secret

   vault read     auth/approle/role/kes-role/role-id
   vault write -f auth/approle/role/kes-role/secret-id

linux or macos or windows

Deploy or Ensure Access to a MinIO Deployment

container

Install Podman or a Similar Container Management Interface

container

linux

macos

k8s

windows

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).

Important

Starting with RELEASE.2023-02-17T17-52-43Z, MinIO requires expanded KES permissions for functionality. The example configuration in this section contains all required permissions.

YAML Overview

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

Fields with ${<STRING>} use the environment variable matching the <STRING> value. You can use this functionality to set credentials without writing them to the configuration file.

The YAML assumes a minimal set of permissions for the MinIO deployment accessing KES. As an alternative, you can omit the policy.minio-server section and instead set the ${MINIO_IDENTITY} hash as the ${ROOT_IDENTITY}.

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/*
    - /v1/key/bulk/decrypt
    - /v1/key/list
    - /v1/status
    - /v1/metrics
    - /v1/log/audit
    - /v1/log/error
    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
    engine: "kv"
    version: "v1"
    namespace: "minio"
    prefix: "keys"
    approle:
      id: ${KES_APPROLE_ID}
      secret: ${KES_APPROLE_SECRET}
      retry: 15s
    status:
      ping: 10s
    tls:
      key: "kes-mtls.key"
      cert: "kes-mtls.cert"
      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. engine - The path to the K/V engine to use. Defaults to kv version - The version of the K/V engine to use. Specify either v1 or v2. Defaults to v1. namespace - The Vault namespace to use for secret storage. prefix - The prefix to use for secret storage. 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).