Install MinIO KMS on Linux

MinIO Key Management Service (KMS) supports installation on Linux hosts running AMD64 or ARM64 architectures.

This procedure downloads and installs MinIO KMS onto a single host machine. You can then expand the cluster with additional nodes to increase availability and resiliency. For production environments, ensure a minimum of 3 MinIO KMS hosts.

Procedure

The commands in this procedure may require sudo permissions to succeed depending on the level of access you have when accessing the host machine. If you do not have sudo or similar permissions, contact your systems administrator for assistance with completing the steps in this procedure.

Create a MinIO KMS system user and group

This procedure uses a Linux/Unix system-level user and group for normal operations. Create the user and group with the following commands:
```
sudo groupadd -r minkms-user
sudo useradd -M -r -g minkms-user minkms-user
```

Create a directory structure for KMS files and configurations

The following command creates files and directories to support running the KMS.

mkdir -p /etc/minkms/certs/CAs /etc/minkms/config /mnt/minio-kms
touch /etc/default/minkms

The command creates the following structure:


/etc/minkms
  /certs             # Directory for TLS certificates
    /CAs             # Certificate Authority files for client verification
  /config            # KMS configurations
/mnt/minio-kms     # Dedicated mounted volume for KMS data
/etc/default/minkms  # Environment variables for MinKMS process

Use chown and chmod to restrict access to these directories to only the minkms-user user and group.

chown -R minkms-user:minkms-user /etc/minkms
chmod -R 660 /etc/minkms

chown -R minkms-user:minkms-user /mnt/minio-kms
chmod -R 755 /mnt/minio-kms

chown -R minkms-user:minkms-user /etc/default/minkms
chmod -R 660 /etc/default/minkms

Download your SUBNET license key

License requirement dropped

Starting with RELEASE.2025-11-12T19-14-51Z, MinIO KMS no longer requires a license key to start up. This step remains in place for supporting installations from older versions of the binary.

Log into MinIO SUBNET and access your License Key. From the Deployment view, select License to view the key.

Download the file to the /etc/minkms/minio.license.
Download the MinIO KMS binary

Select the tab corresponding to your OS/Architecture combination. The displayed commands download the latest KMS binary, set it to executable, and move it into the system path at /usr/local/bin. You may need sudo for one or more of the commands.
Linux AMD64
```
curl --progress-bar --retry 10 -L https://dl.min.io/aistor/minkms/release/linux-amd64/minkms -o minkms
chmod +x ./minkms
mv ./minkms /usr/local/bin/
```
Linux ARM64
```
curl --progress-bar --retry 10 -L https://dl.min.io/aistor/minkms/release/linux-arm64/minkms -o minkms
chmod +x ./minkms
mv ./minkms /usr/local/bin/
```
You can validate the installation by running minkms help.
Add the TLS certificates and Certificate Authorities

Place the TLS private key private.key and public certificate public.crt in the /etc/minkms/certs directory. Ensure the TLS certificates have appropriate file permissions (600 or owner-only read/write):
```
chmod -R 600 /etc/certs/
```
If MinIO KMS or the AIStor servers use a Certificate Authority that is not globally trusted, you may also need to add that CA to the /etc/minkms/certs/CAs directory. Include the root and all intermediate certificates necessary to validate certificates.

Create a service file for MinIO KMS

Create a new minkms.service file at /usr/lib/systemd/system/minkms.service with the following content:

[Unit]
Description=MinKMS
Documentation=https://docs.min.io/enterprise/aistor-key-manager
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minkms

[Service]
WorkingDirectory=/usr/local

User=minkms-user
Group=minkms-user
ProtectProc=invisible

EnvironmentFile=-/etc/default/minkms
ExecStart=/usr/local/bin/minkms server $MINIO_KMS_VOLUME $MINIO_KMS_OPTS

# Let systemd restart this service always
Restart=always

# Specifies the maximum file descriptor number that can be opened by this process
LimitNOFILE=65536

# Specifies the maximum number of threads this process can create
TasksMax=infinity

# Disable timeout logic and wait until process is stopped
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

# Built for ${project.name}-${project.version} (${project.name})

Generate an HSM Key

MinIO KMS uses a hardware/software security module (HSM) for en/decrypting the keystore and for authenticating internode cals. All KMS nodes must use the same HSM configuration while part of the same cluster.

Generate an HSM key by using the following command:
```
minkms --soft-hsm
```
MinIO KMS uses an NIST.SP.800-108r1-compliant algorithm for generating a software-based HSM for use as the REK.

Store the returned value in a secure location, such as a dedicated secrets vault.
Build an environment file for MinIO KMS

Open the file at /etc/default/minkms and enter the following content:
```
MINIO_KMS_HSM_KEY=hsm:aes256:KEYVALUE

MINIO_KMS_VOLUME=/mnt/minio-kms

MINIO_KMS_OPTS="--config /etc/minkms/config.yaml"
```
Replace the MINIO_KMS_HSM_KEY with the value generated in the previous step.

Replace the MINIO_KMS_VOLUME with the path to the volume or mount point you want MinIO KMS to use for storage.

Previous versions of MinIO KMS (prior to RELEASE.2025-11-12T19-14-51Z) require the MINIO_LICENSE environment variable.

For license configuration instructions for previous versions, see the Legacy License Installation Guide.

Create the MinIO KMS configuration file

Create a file at /etc/minkms/config.yaml with the following content:

version: v1

tls:
  certs:
    - key: /etc/minkms/certs/private.key
      cert: /etc/minkms/certs/public.crt
  ca: /etc/minkms/certs/CAs

Enable and start the MinIO KMS service

Run the following commands to enable and start the service:
```
systemctl daemon-reload
systemctl enable minkms
systemctl start minkms
```
Use the journalctl -u minkms command to validate the status and output of MinIO KMS. The output should include the Node hostname, API Endpoint, and a root or superadmin API Key for use with performing KMS operations.

You can also filter the journactl output to only return the root or superadmin API Key:
```
journalctl -u minkms -g "API Key" -o cat --output-fields "MESSAGE"
```
Store the API key in a secure location, such as a dedicated secrets vault. You can also compute the API Key with the HSM key:
```
minkms identity hsm:aes256:KEYVALUE
```
Create an enclave and identity for AIStor Object Store

Each Object Store requires an enclave and identity for accessing MinIO KMS and performing cryptographic operations.

Use the following commands to generate the necessary resources. Change the object-store-name to reflect the name or label you want to associate with the object store.
```
export MINIO_KMS_SERVER=127.0.0.1:7373

# RELEASE.2025-11-12T19-14-51Z dropped the license requirement.
# Uncomment this line for older MinIO KMS versions.
# export MINIO_LICENSE=/etc/minmks/minio.license

minkms add-enclave -k -a k1:`root` or superadmin_API_KEY object-store-name

minkms add-identity -k -a k1:`root` or superadmin_API_KEY --enclave object-store-name --admin
```
The command returns the API Key and Identity for use with the Object Store. Copy the k1: prefixed value for use with enabling Server-Side Encryption with the Object Store.
Next Steps

Once you have configured an enclave and identity, you can use the k1:APIKEY value to enable AIStor Server Side Encryption.