MinIO Key Encryption Service
This site provides information about MinIO’s Key Encryption Service (KES) project.
The documentation includes:
- architecture and configuration guides
- best practices
- general documentation
KES is a stateless and distributed key-management system for high-performance applications. KES serves as the bridge between modern applications that run as containers on Kubernetes and centralized Key Management Services (KMS). By default, we designed KES to be simple, scalable, and secure. With simplified configuration options compared to other services, KES does not require a deep understanding of secure key-management or cryptography principles.
If you’re new to KES you may want to start in one of the following pages:
- Jump right in with the Getting Started guide
- Review set up options with the configuration guide
- Learn how KES works at our Concepts page.
KES Access Control
KES uses mutual TLS authentication (mTLS) for performing both authentication and authorization of clients making requests to the KES server.
Both the client and server present their x.509 certificate and corresponding private key to their peer. The server only accepts the connection if the client certificate is valid and authentic:
A “valid” certificate is well-formed and current (i.e. not expired).
Authentication with mTLS also requires the following Extended Key Usage extensions for the client and server.
- Client Authentication (
extendedKeyUsage = clientAuth)
- Server Authentication (
extendedKeyUsage = serverAuth)
- Client Authentication (
An “authentic” certificate is issued by a trusted Certificate Authority (CA). Both client and server must include the peer certificate CA in their local system trust store.
You can start the KES server with the
kes server --auth option to perform mTLS with untrusted or self-signed certificates during testing or early development.
MinIO strongly recommends only allowing trusted certificates in production environments.
KES uses Policy-Based Access Control (PBAC) to determine what operations a given client has permission to perform. Each policy consists of one or more identities, where each identity corresponds to the SHA-256 hash of an x.509 certificate. The server only allows the client to perform the requested operation if the following are true:
- A policy on the KES server contains the client identity.
- The policy explicitly allows the requested operation.
If no such policy exists on the KES server or if the policy does not explicitly allow the requested operation, the KES server denies the client’s request.
KES uses policy-based access control (PBAC), where a policy describes the operations an authenticated client may perform.
YAML document provides an example of the :kesconf:
policy section of the KES server configuration document.
minio-sse includes the appropriate :API endpoints for supporting MinIO Server-Side Encryption:
policy: minio-sse: paths: - /v1/key/create/* - /v1/key/generate/* - /v1/key/decrypt/* - /v1/key/delete/* identities: - <SHA-256 HASH>
Each element in the
policy.policyname.pathsarray represents an
API endpointto which the policy grants access.
Each element in the
policy.policyname.identitiesarray represents the SHA-256 hash of an x.509 certificate presented by a client.
kes identity ofcommand to compute the identity hash of a client’s x.509 certificate.
Policies and identities have a one-to-many relationship, where one policy can contain many identities. However, a given identity can associate to at most one policy at a time.
The KES server provides two methods for configuring policies:
policysection of the KES configuration file lists the persistent policies for the KES server.
Policies created or modified using either
kes identitydisappear after restarting the KES server.
Each KES server has its own configuration file from which it derives all persistent policies. With distributed KES deployments, each server has its own independent and distinct policy-identity set based on its configuration file. This may allow for an identity to associate to different policies depending on which KES server a client connects to.
Exercise caution in allowing KES servers to contain differing policies, as it may result in inconsistent client encryption behavior between servers. MinIO strongly recommends synchronizing changes to configuration files in distributed KES deployments.
Supported KMS Targets
- Hashicorp Vault
- Fortanix SDKMS
- Thales CipherTrust Manager (formerly Gemalto KeySecure)
- AWS Secrets Manager
- Google Cloud Secret Manager
- Azure KeyVault
- Local Filesystem