Install Key Manager on Linux

AIStor Key Manager supports installation on Linux and MacOS hosts running AMD64 or ARM64 architectures.

This procedure downloads and installs the Key Manager onto a single host machine. You can then expand the cluster with additional nodes to increase availability and resiliency.

1. Create a Key Manager system user and group

   This proceure 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
   

2. Create a directory structure for Key Manager files and configurations

   The following command creates files and directories to support running Key Manager. You may need sudo permissions to run the command:

   mkdir -p /opt/minkms/certs/CAs /opt/minkms/config /mnt/key-manager
   touch /etc/default/minkms
   

   The command creates the following structure:

   
   /opt/minkms
     /certs             # Directory for TLS certificates
       /CAs             # Certificate Authority files for client verification
     /config            # Key Manager configurations
   /mnt/key-manager     # Dedicated mounted volume for Key Manager 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 /opt/minkms
   chmod -R 660 /opt/minkms
   
   chown -R minkms-user:minkms-user /mnt/key-manager
   chmod -R 660 /mnt/key-manager
   
   chown -R minkms-user:minkms-user /etc/default/minkms
   chmod -R 660 /etc/default/minkms
   

3. Download your SUBNET license key

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

   

   Download the file to the /opt/minkms/minio.license.

4. Download the Key Manager binary

   Select the tab corresponding to your OS/Architecture combination. The displayed commands download the latest Key Manager 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.

5. Add the TLS certificates and Certificate Authorities

   Place the TLS private key private.key and public certificate public.crt in the /opt/minkms/certs directory. Ensure the TLS certificates have appropriate file permissions (600 or owner-only read/write).

   If Key Manager or the AIStor servers use a Certificate Authority that is not globally trusted, you may also need to add that CA to the /opt/minkms/certs/CAs directory. Include the root and all intermediate certificates necessary to validate certificates.

6. Create a service file for Key Manager

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

   [Unit]
   Description=MinKMS
   Documentation=https://min.io/docs/minkms
   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})
   

7. Generate an HSM Key

   Key Manager uses a hardware/software security module (HSM) for en/decrypting the keystore and for authenticating internode cals. All Key Manager 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
   

Key Manager uses an NIST.SP.800-108r1-compliant algorithm for generating a software-based HSM for use as the REK.

1ceb957 (CR fixups)

Store the returned value in a secure location, such as a dedicated secrets vault.

1. Build an environment file for Key Manager

   Open the file at /etc/default/minkms and enter the following content:

   MINIO_LICENSE=/opt/minkms/minio.license
   
   MINIO_KMS_HSM_KEY=hsm:aes256:KEYVALUE
   
   MINIO_KMS_VOLUME=/mnt/key-manager
   
   MINIO_KMS_OPTS="--config /opt/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 Key Manager to use for storage.

2. Create the Key Manager configuration file

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

   version: v1
   
   tls:
     certs:
       - key: /opt/minkms/certs/private.key
         cert: /opt/minkms/certs/public.crt
     ca: /opt/minkms/certs/CAs
   

3. Enable and start the Key Manager 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 the Key Manager.

   The output should include the Node hostname, API Endpoint, and a SysAdmin API Key for use with performing Key Manager operations. Store the SysAdmin API Key in a secure location, such as a dedicated secrets vault.

   The SysAdmin API Key can be re-computed using the HSM key:

   minkms identity hsm:aes256:KEYVALUE
   

4. Create an enclave and identity for AIStor Object Store

   Each Object Store requires an enclave and identity for accessing the Key Manager 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
   export MINIO_LICENSE=/opt/minmks/minio.license
   
   minkms add-enclave -k -a k1:SYSADMIN_API_KEY object-store-name
   
   minkms add-identity -k -a k1:SYSADMIN_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.

5. Next Steps

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