Cloud HSM

This topic provides an overview of Cloud HSM and shows you how to create and use HSM-protected encryption keys in Cloud Key Management Service.

What is Cloud HSM?

Cloud HSM is a cloud-hosted Hardware Security Module (HSM) service that allows you to host encryption keys and perform cryptographic operations in a cluster of FIPS 140-2 Level 3 certified HSMs. Google manages the HSM cluster for you, so you don't need to worry about clustering, scaling, or patching. Because Cloud HSM uses Cloud KMS as its front end, you can leverage all the conveniences and features that Cloud KMS provides.

Before you begin

  • If you haven't already, enable billing for your project.

    Enable billing

Create a key ring

Create a key ring named hsm-ring.

console

  1. Go to the Cryptographic Keys page in the GCP Console.

  2. Click Create key ring.

  3. In the Key ring name field, enter hsm-ring.

  4. From the Location dropdown, select one of the supported regions for Cloud HSM.

  5. Click Create.

command line

Create a new key ring with name hsm-ring in one of the supported regions for Cloud HSM.

gcloud kms keyrings create hsm-ring \
  --location [LOCATION]

Create a key

Create a key named hsm-key.

console

  1. Go to the Cryptographic Keys page in the GCP Console.

  2. Click the key ring named hsm-ring.

  3. Click Create key.

  4. In the Key name field, enter hsm-key.

  5. Click the Purpose dropdown and select Symmetric encrypt/decrypt. To learn more about key purposes, see Key purposes.

  6. For Protection level, select HSM. To learn more about protection levels, see Protection levels.

  7. [Optional] In the Labels field, click Add label if you want to add labels to your key.

  8. Click Create.

command line

Create a new key hsm-key in the hsm-ring key ring.

  • Set --purpose to encryption. To learn more about key purposes, see Key purposes.
  • Set --protection-level to hsm. You can learn more about protection levels in Protection levels.
gcloud alpha kms keys create hsm-key \
  --location [LOCATION] \
  --keyring hsm-ring \
  --purpose encryption \
  --protection-level hsm

Encrypt data

Now that you have a key, you can use that key to encrypt text or binary content. Generate some text to be encrypted.

echo "Some text to be encrypted" > ~/my-secret-file

Encrypt the plain text into a file named my-secret-file.enc

gcloud kms encrypt \
  --location [LOCATION] \
  --keyring hsm-ring \
  --key hsm-key \
  --plaintext-file ~/my-secret-file \
  --ciphertext-file ~/my-secret-file.enc

Decrypt ciphertext

To decrypt encrypted content, you must use the same key that was used to encrypt the content. Decrypt the encrypted file my-secret-file.enc by issuing the following command:

gcloud kms decrypt \
  --location [LOCATION] \
  --keyring hsm-ring \
  --key hsm-key \
  --ciphertext-file ~/my-secret-file.enc \
  --plaintext-file ~/my-secret-file.dec

You should see that the contents of my-secret-file.dec and the original plaintext file my-secret-file are identical:

cat ~/my-secret-file.dec
Some text to be encrypted

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

Clean up consists of destroying the key versions used in this topic.

List the versions available for your key:

gcloud kms keys versions list \
  --location [LOCATION] \
  --keyring hsm-ring \
  --key hsm-key

To destroy a version, run the following command, replacing [VERSION_NUMBER] with the version number to be destroyed:

gcloud kms keys versions destroy \
  [VERSION_NUMBER] \
  --location [LOCATION] \
  --keyring hsm-ring \
  --key hsm-key

What's next

Known limitations

  • Block size is limited to 16,384 bytes (as opposed to 64 KiB for Cloud KMS software keys) for user-provided plaintext and ciphertext, including the additional authenticated data.

  • Cloud HSM is available only in certain regions. For details, see Supported regions for Cloud HSM.

  • Currently key operations for keys stored in Cloud HSM may incur a noticeably greater latency compared to using Cloud KMS software keys.

If you experience an error

If you run into an issue, see the feedback options at Support.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud KMS Documentation