KES on a MinIO Deployment
This tutorial shows how to setup a KES server and then configure a MinIO deployment as a KES client for object encryption.
This tutorial focuses on a simple KES server setup. We use the local filesystem as key store and omit the KMS integration.
For production use, choose any supported KMS implementation that meets your requirements.
KES Server Setup
-
Generate KES Server Private Key & Certificate
Generate a TLS private key and certificate for the KES server.
A KES server is secure-by-default and can only be run with TLS. In this guide, we use self-signed certificates for simplicity.
The following command generates a new TLS private key (
private.key
) and a self-signed X.509 certificate (public.crt
) issued for the IP127.0.0.1
and DNS namelocalhost
:$ kes identity new --ip "127.0.0.1" localhost Private key: private.key Certificate: public.crt Identity: 2e897f99a779cf5dd147e58de0fe55a494f546f4dcae8bc9e5426d2b5cd35680
Existing Key & Certificate:If you already have a TLS private key & certificate, such as from a WebPKI or internal Certificate Authority, you can use them instead. Remember to adjust thetls
config section. -
Generate MinIO Credentials
MinIO needs credentials to access the KES server. The following command generates a new TLS private/public key pair:
$ kes identity new --key=client.key --cert=client.crt MinIO Private key: client.key Certificate: client.crt Identity: 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
The identity
02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
is a unique fingerprint of the public key inclient.crt
. You can re-compute it at anytime:$ kes identity of client.crt Identity: 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
-
Configure KES Server
Create the KES server configuration file:
config.yml
. Ensure the identity in thepolicy
section matches yourclient.crt
identity.address: 0.0.0.0:7373 # Listen on all network interfaces on port 7373 admin: identity: disabled # We disable the admin identity since we don't need it in this guide tls: key: private.key # The KES server TLS private key cert: public.crt # The KES server TLS certificate policy: my-app: allow: - /v1/key/create/minio-* - /v1/key/generate/minio-* - /v1/key/decrypt/minio-* identities: - 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b # Use the identity of your client.crt keystore: fs: path: ./keys # Choose a directory for the secret keys
-
Start KES Server
$ kes server --config config.yml --auth off
Linux Swap Protection:In Linux environments, KES can use the
mlock
syscall to prevent the OS from writing in-memory data to disk (swapping). This prevents leaking sensitive data.Use the following command to allow KES to use the mlock syscall without running with
root
privileges:$ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
Start a KES server instance with memory protection:
$ kes server --config config.yml --auth off --mlock
MinIO Server Setup
-
Install MinIO
You can either download a static binary or follow the MinIO Quickstart Guide.
Select the tab for your operating system for an OS-specific quickstart.
-
Set
MINIO_KMS_KES_ENDPOINT
This environment variable tells MinIO which KES server to access:
export MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
-
Set MinIO Client Credentials
These environment variables set the access credentials MinIO uses to access the KES server:
export MINIO_KMS_KES_CERT_FILE=client.crt
export MINIO_KMS_KES_KEY_FILE=client.key
-
Set MinIO Default Key
This environment variable sets the default key for MinIO to use if its S3 client does not specify an encryption key.
export MINIO_KMS_KES_KEY_NAME=minio-default-key
MinIO creates this key automatically if it does not exist. -
Trust the KES Server Certificate
This step is optional if the KES server uses a certificate issued by a trusted Certificate Authority.
When using self-signed certificates, MinIO cannot verify the the KES server certificate. This environment variable establishes the trust relationship manually.
export MINIO_KMS_KES_CAPATH=public.crt
In this case,
public.crt
is the public certificate of the KES server. -
Set the MinIO root credentials:
export MINIO_ROOT_USER=minio export MINIO_ROOT_PASSWORD=minio123
-
Start the MinIO Server
minio server /data
Encrypt Bucket
Enable server-side encryption on a specific bucket using the PutBucketEncryption
S3 API.
This can be done with the MinIO Client.
-
Create Key
For a full reference, see the
mc admin kms key
documentation.mc admin kms key create <alias> minio-my-bucket
Replace
minio-my-bucket
with your MinIO server alias. -
Configure Bucket
Add a server-side encryption configuration to your bucket with
mc encrypt set
.For example:
mc encrypt set sse-kms minio-my-bucket <alias>/my-bucket
Replace
minio-my-bucket
with your MinIO server alias.