Using HSM-based secrets encryption

HSM-based secrets encryption

GKE on VMware 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 GKE 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