Integrate with Google Cloud Key Management

Access Google Cloud Key Management

Google Cloud Key Management can be accessed through the Google Cloud Platform or by using the Google Cloud SDK Shell Command-Line Interface (CLI). Follow the Google Cloud Key Management documentation to ensure that you use the appropriate authentication, and are communicating with a genuine Google Cloud Key Management server.

This operation requires the use of a Google KMS project with billing enabled. We recommend that you use the Google guides guide when carrying out the Google KMS operations because they might have been updated after the publication of this User Guide for the Cloud Integration Option Pack. See https://cloud.google.com/kms/docs/key-import and https://cloud.google.com/kms/docs/importing-a-key. Refer to the instructions for Importing a manually-wrapped key but note that the wrapping will be carried out using the cssadmin tool and not OpenSSL.

Create a target key and key ring

A Cloud KMS key is a container object that contains zero or more key versions. Each key version contains a cryptographic key.

When you import a key into Cloud KMS or Cloud HSM, the imported key becomes a new key version on an existing Cloud KMS or Cloud HSM key. In the rest of this topic, this key is called the target key. The target key must exist before you can import key material into it.

From the Google Cloud Console Web UI:

Go to the Cryptographic Keys page.
Click Create key ring.
1. enter a name for the key ring in the Key ring name field.
2. select a location from the Location dropdown see https://cloud.google.com/kms/docs/locations for more information.
3. Click Create - opens detail page for key ring.
Click Create key.
1. Select Imported key.
2. Enter name for the key in the Key name field.
3. Set Protection level to HSM.
4. Set Purpose to one of Symmetric encryption, Asymmetric signing, Asymmetric decrypt.
5. Set Key type and Algorithm.
6. Optionally set up rotation and labels.
7. Click create.

Alternatively use the Google Cloud SDK Shell.

gcloud kms keyrings create key-ring-name \
  --location location

gcloud kms keys create key-name \
  --location location \
  --keyring key-ring-name \
  --purpose purpose \
  --skip-initial-version-creation

Generate the Google KMS Wrapping Key

It is necessary to create an Import Job.

From the Google Cloud Console Web UI:

Go to the Cryptographic Keys page.
Click the name of the target key ring.
Click Create import job.
1. Set the Protection level to either Software or HSM. Use the same protection level as you set for the target key.
2. From the Import method dropdown, set the import method to either 3072 bit RSA or 4096 bit RSA.
3. Click Create.

Alternatively use the Google Cloud SDK Shell.

gcloud kms import-jobs create import-job \
  --location location \
  --keyring key-ring-name \
  --import-method import-method \
  --protection-level protection-level

Download the Google KMS Wrapping Key

It is necessary to retrieve the Wrapping Key from Google KMS.

From the Google Cloud Console Web UI

Go to the Cryptographic Keys page.
Click the name of the key ring that contains your import job.
Click on the Import Jobs tab.
Click the Actions icon for the import job.
Select Download Wrapping Key.

This will save the wrapping key to <name of import job>.pem in your browser’s Downloads folder.

Alternatively use the Google Cloud SDK Shell. You can specify the filename explicitly here. Use the appropriate syntax for your operating system. The example shows Linux syntax.

gcloud kms import-jobs describe \
  --location=location \
  --keyring=keyring \
  --format="value(publicKey.pem)" \
  import-job-name > ${HOME}/wrapping-key.pem

Use cssadmin to generate, wrap and export a key

Using the downloaded Wrapping Key file, call cssadmin as follows:

cssadmin google-cloud-key-management <key name> <wrapping key> --key-type <key type>

Where:

wrapping key: The file you downloaded, for example myimportjob.pem.
key-type: Optional and defaults to RSA 2048-bit if none is provided.

Note that, unlike with AWS and Google Compute Engine, no wrapping algorithm parameter is required with Google KMS because it only supports one algorithm.

The following target key types are available:

RSA Keys

2048-bit
3072-bit
4096-bit

Elliptic Curve Keys

NISTP256
NISTP384

AES Keys

AES-256

To maintain the security strength of the transferred target key, ensure that the security strength of the chosen Wrapping Key is greater than or equal to the security strength of the chosen target key. For example, for an Elliptic Curve key generated using NISP256, the Wrapping Key must be RSA 3072-bit or greater.

Running the cssadmin command creates a file called <key name>-wrapped.bin.

Upload the wrapped key material

To import the target key into Google KMS use the Google Cloud Platform or the Google Cloud SDK Shell CLI to upload the wrapped key file to Google KMS:

From the Google Cloud Console Web UI:

Go to the Cryptographic Keys page.
Click the name of the key ring that contains your import job.
Click on the name of the target key, then click Import key version.
Select your import job from the Select import dropdown.
In the Upload the wrapped key selector, select the key that you have already wrapped.
If you are importing an asymmetric key, select the algorithm from the Algorithm dropdown.
Click Import.

Alternatively use the Google Cloud SDK Shell. You can specify the filename explicitly here.

gcloud kms keys versions import \
  --import-job import-job \
  --location location \
  --keyring key-ring-name \
  --key key-name \
  --algorithm algorithm-name \
  --rsa-aes-wrapped-key-file path-to-wrapped-key-to-import

where

rsa-aes-wrapped-key-file: The bin file produced in Use cssadmin to generate, wrap and export a key.

The key-import request is initiated and you can monitor its status. The initial state for an imported key is PENDING_IMPORT. When the state is ENABLED, the key has been imported successfully. If the import fails, the status is IMPORT_FAILED. If the upload is successful, you can use this HSM-protected key in Google KMS.