Using HSM-based secrets encryption

HSM-based secrets encryption

Anthos clusters on VMware (GKE on-prem) versions 1.6 and later support user cluster secret encryption at rest with the Thales Luna network Hardware Security Module (HSM). The secret encryption key is stored in a partition on your HSM appliance. Authentication to the HSM appliance is performed with mutual TLS (mTLS).

Prerequisites

To use HSM-based secret encryption, you must have the following:

  • A Thales Luna network HSM appliance configured with the following:
    • Network access from your user clusters.
    • A PKCS#11 driver and certificates.
    • An available partition on the Luna HSM.
    • The Crypto Officer (CO) and Security Officer (SO) roles must be initialized. These users must not require a PIN/password change.
  • The following configuration items available:
    • A container image containing the Thales HSM driver. Contact your Thales representative for a copy. This image must be hosted by a container repository accessible from your user cluster.
    • Your Luna HSM appliance address and CA certificate.
    • A Client provisioned with a Certificate/Key pair.

Configuring your HSM

To configure your user cluster to use an HSM, you create a credentials file and then add configuration details to your user cluster configuration file.

Creating a credentials file

You provide the location of your PKCS#11 credentials to Anthos clusters on VMware with a YAML configuration file.

  1. Copy the following YAML configuration into a file.

    apiVersion: v1
kind: CredentialFile
# list of credentials
items:
- name: "CREDENTIALS_NAME"
  username: "PKCS_USER"
  password: "PKCS_PASSWORD"

    Replace the following:

    • CREDENTIALS_NAME with a name to reference your credentials. For example, pkcs-credentials.
    • PKCS_USER with the username of a user with the CO role on the partition in question.
    • PKCS_PASSWORD with the user's password.

  2. Save the file and copy the path for the following steps.

Configuring your user clusters

  1. Before you create a user cluster, you generate a User cluster configuration file using gkectl create-config cluster.

  2. You configure HSM-based secrets encryption in your user cluster configuration file by adding the secretsEncryption object. Open the configuration file in a text editor and copy the following section into your configuration file.

    secretsEncryption:
  mode: ThalesLunaHSM
  thaleslunahsm:
    pkcs11DriverImage: "DRIVER_IMAGE_LOCATION"
    server: "APPLIANCE_ADDRESS"
    caCertificate: "CA_CERTIFICATE_PEM_PATH"
    clientCertificate: "CLIENT_CERTIFICATE_PEM_PATH"
        clientKey: "CLIENT_KEY_PEM_PATH"
    pkcs11Label: PARTITION_LABEL
    pkcs11Pin:
      fileRef:
        path: "CREDENTIALS_YAML_PATH"
        entry: "CREDENTIALS_NAME"

    Replace the following:

    • DRIVER_IMAGE_LOCATION with the location of the Thales HSM driver container image you received from your Thales representative. For example, gcr.io/my-project/hsm-driver:latest.
    • APPLIANCE_ADDRESS with the appliance's IP address or DNS name.
    • CA_CERTIFICATE_PEM_PATH with the path to the appliance's CA Certificate in PEM format.
    • CLIENT_CERTIFICATE_PEM_PATH with the path to the network trust link service (NTLS) client certificate.
    • CLIENT_KEY_PEM_PATH with the path to the NTLS client key.
    • PARTITION_LABEL with the PKCS#11 token label applied to the key's partition.
    • CREDENTIALS_YAML_PATH with the path to the credentials file you created in the preceding section.
    • CREDENTIALS_NAME with the name of the credentials object in your credentials file. For example, pkcs-credentials.

What's next