Google Cloud HSM

Google Cloud HSM provides hardware-based key protection. The private key never leaves the HSM.

Prerequisites

Enable Cloud KMS

Create or use a Google Cloud project and enable the Cloud KMS API.

Create HSM key

Create an HSM key ring and an asymmetric signing key in Cloud KMS (see Creating an HSM Key below).

Create service account

Create a service account with the cloudkms.signerVerifier role so Documenso can use the key.

Export public certificate

Export the public certificate from the HSM key; Documenso needs it to embed in signatures.

Environment Variables

Variable	Description
`NEXT_PRIVATE_SIGNING_TRANSPORT`	Set to `gcloud-hsm`
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_KEY_PATH`	Full resource path to the HSM key version
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_PATH`	Path to the public certificate file
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_CONTENTS`	Base64-encoded public certificate
`NEXT_PRIVATE_SIGNING_GCLOUD_APPLICATION_CREDENTIALS_CONTENTS`	Base64-encoded Google Cloud service account JSON
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_FILE_PATH`	Path to the certificate chain file
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_CERT_CHAIN_CONTENTS`	Base64-encoded certificate chain
`NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH`	Google Secret Manager path for certificate retrieval

Configuration Example

NEXT_PRIVATE_SIGNING_TRANSPORT=gcloud-hsm
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_KEY_PATH=projects/my-project/locations/global/keyRings/documenso/cryptoKeys/signing-key/cryptoKeyVersions/1
NEXT_PRIVATE_SIGNING_GCLOUD_HSM_PUBLIC_CRT_FILE_PATH=/opt/documenso/public.crt
NEXT_PRIVATE_SIGNING_GCLOUD_APPLICATION_CREDENTIALS_CONTENTS=eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...

Key Path Format

The HSM key path follows this format:

projects/{project}/locations/{location}/keyRings/{keyring}/cryptoKeys/{key}/cryptoKeyVersions/{version}

Example:

projects/my-company/locations/us-east1/keyRings/document-signing/cryptoKeys/prod-signing/cryptoKeyVersions/1

Creating an HSM Key

Using gcloud CLI:

# Create a key ring
gcloud kms keyrings create document-signing \
    --location=us-east1 \
    --project=my-project

# Create an asymmetric signing key
gcloud kms keys create prod-signing \
    --keyring=document-signing \
    --location=us-east1 \
    --purpose=asymmetric-signing \
    --default-algorithm=rsa-sign-pkcs1-2048-sha256 \
    --protection-level=hsm \
    --project=my-project

On this page