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.
Create a key ring
When you create a key, you add it to a key ring in a given Google Cloud location. You can create a new key ring or use an existing one. In this topic, you create a new key ring and add a new key to it.
Create a key ring in a Google Cloud location that supports Cloud HSM.
Console
Go to the Key Management page in the Google Cloud console.
Click Create key ring.
For Key ring name, enter a name for your key ring.
For Key ring location, select a location like
"us-east1"
.Click Create.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
-
In your environment, run the
gcloud kms keyrings create
command:gcloud kms keyrings create KEY_RING \ --location LOCATION
Replace the following:
KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=KEY_RING" \ --request "POST" \ --header "authorization: Bearer TOKEN"
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
See the KeyRing.create
API documentation
for more information.
Create a key
Follow these steps to create a Cloud HSM key on the specified key ring and location.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring for which you will create a key.
Click Create key.
In the What type of key do you want to create?, choose Generated key.
In the Key name field, enter the name for your key.
Click the Protection level dropdown and select HSM.
Click the Purpose dropdown and select Symmetric encrypt/decrypt.
Accept the default values for Rotation period and Starting on.
Click Create.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys create key \ --keyring key-ring \ --location location \ --purpose "encryption" \ --protection-level "hsm"
Replace key with a name for the new key. Replace key-ring with the name of the existing key ring where the key will be located. Replace location with the Cloud KMS location for the key ring.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
Encrypt data
Now that you have a key, you can use that key to encrypt text or binary content.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms encrypt \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --plaintext-file FILE_TO_ENCRYPT \ --ciphertext-file ENCRYPTED_OUTPUT
Replace the following:
KEY_NAME
: the name of the key that you want to use for encryption.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location that contains the key ring.FILE_TO_ENCRYPT
: the path to the file that you want to encrypt.ENCRYPTED_OUTPUT
: the path where you want to save the encrypted output.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
When using JSON and the REST API, content must be base64 encoded before it can be encrypted by Cloud KMS.
To encrypt data, make a POST
request and provide the appropriate project and
key information and specify the base64 encoded text to be encrypted in the
plaintext
field of the request body.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:encrypt" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data "{\"plaintext\": \"PLAINTEXT_TO_ENCRYPT\"}"
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring and key that you want to use for encryption.LOCATION
: the Cloud KMS location that contains the key ring.KEY_RING
: the key ring that contains the key that you want to use for encryption.KEY_NAME
: the name of the key that you want to use for encryption.PLAINTEXT_TO_ENCRYPT
: the plaintext data that you want to encrypt. The plaintext must be base64 encoded before you call theencrypt
method.
Here is an example payload with base64 encoded data:
{ "plaintext": "U3VwZXIgc2VjcmV0IHRleHQgdGhhdCBtdXN0IGJlIGVuY3J5cHRlZAo=", }
Decrypt ciphertext
To decrypt encrypted content, you must use the same key that was used to encrypt the content.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms decrypt \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --ciphertext-file FILE_TO_DECRYPT \ --plaintext-file DECRYPTED_OUTPUT
Replace the following:
KEY_NAME
: the name of the key that you want to use for decryption.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location that contains the key ring.FILE_TO_DECRYPT
: the path to the file that you want to decrypt.DECRYPTED_OUTPUT
: the path where you want to save the decrypted output.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Decrypted text that is returned in the JSON from Cloud KMS is base64 encoded.
To decrypt encrypted data, make a POST
request and provide the appropriate
project and key information and specify the encrypted text (also known as
ciphertext) to be decrypted in the ciphertext
field of the request body.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:decrypt" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data "{\"ciphertext\": \"ENCRYPTED_DATA\"}"
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring and key that you want to use for decryption.LOCATION
: the Cloud KMS location that contains the key ring.KEY_RING
: the key ring that contains the key that you want to use for decryption.KEY_NAME
: the name of the key that you want to use for decryption.ENCRYPTED_DATA
: the encrypted data that you want to decrypt.
Here is an example payload with base64 encoded data:
{ "ciphertext": "CiQAhMwwBo61cHas7dDgifrUFs5zNzBJ2uZtVFq4ZPEl6fUVT4kSmQ...", }
Next steps
The encryption example in this topic used a symmetric key with the protection level of HSM. To encrypt using an asymmetric key with the protection level of HSM, follow the steps at Encrypting and decrypting data with an asymmetric key with these changes:
- Create the key ring in one of the supported regions for Cloud HSM.
- Create the key with protection level HSM.
To use an asymmetric key with the protection level of HSM for elliptic curve signing or RSA signing, follow the steps at Create and validate signatures with these changes:
- Create the key ring in one of the supported regions for Cloud HSM.
- Create the key with protection level HSM.
Start using the API.
Take a look at the Cloud KMS API Reference.
Read How-to guides to get started with creating, rotating, and setting permissions on keys.
Read Concepts to better understand object hierarchy, key states, and key rotation.
Learn about Logging in Cloud KMS. Note that logging is based on operations, and applies to keys with both HSM and software protection levels.
Learn more about how Cloud HSM protects your data in the Cloud HSM architecture whitepaper.
Known limitations
Message size is limited to 8 KiB (as opposed to 64 KiB for Cloud KMS software keys) for user-provided plaintext and ciphertext, including the additional authenticated data.
Cloud HSM may not be available in certain multi or dual regions. For details, see Supported regions for Cloud HSM.
If you use Cloud HSM keys with customer-managed encryption key (CMEK) integrations in other Google Cloud services, the locations you use for the services must match the locations of your Cloud HSM keys exactly. This applies to regional, dual-regional, and multi-regional locations.
For more information about CMEK integrations, see the relevant section of Encryption at rest.
Currently key operations for asymmetric keys stored in Cloud HSM may incur a noticeably greater latency compared to using Cloud KMS software keys.
Bare Metal Rack HSM
Google Cloud offers additional HSM options, such as single-tenancy. Bare Metal Rack HSM is available for customers to host their own HSMs in Google-provided space. Inquire with your account representative for additional information.