Integrate with Google Cloud Key Management

Access Google Cloud Key Management

This operation requires the use of a Google KMS project with billing enabled.

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 that you are communicating with a genuine Google Cloud Key Management server.

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. However, note that the wrapping will be carried out using cloud_integration_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.

To create a target key and key ring from the Google Cloud console web UI:

  1. Select Security > Key Management > Create Key Ring.

  2. Enter a name for the key ring in the Key ring name field.

  3. Select a Location type and a Location from the list. See https://cloud.google.com/kms/docs/locations for more information.

  4. Select Create > Create Key.

  5. In Name and protection level > Key name, enter the name of the key.

  6. Set Protection level to HSM.

  7. In Key material select Imported key.

  8. In Purpose and algorithm, set Purpose to one of Symmetric encryption, Asymmetric signing, Asymmetric decrypt and set the Algorithm as appropriate.

  9. In Versions, select Import key settings and Key rotation period as required according to your organisation’s security guidance.

  10. (Optional) In Additional settings, set up Duration of 'scheduled for destruction' state and add Labels.

  11. Select Create.

To create a target key and key ring from 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

You have to create an import job.

To generate the Google KMS wrapping key from the Google Cloud console Web UI:

  1. On the Security > Key Management page select the Name of the target key ring.

  2. Select Create Import Job.

  3. Enter a Name for the import job

  4. Set the Protection level to the same as set for the target key.

  5. From the Import method list, select from one of the following:

    • 3072 bit RSA - OAEP padding - SHA1 digest + 256 bit AES-KWP

    • 4096 bit RSA - OAEP padding - SHA1 digest + 256 bit AES-KWP

    • 3072 bit RSA - OAEP padding - SHA256 digest + 256 bit AES-KWP

    • 4096 bit RSA - OAEP padding - SHA256 digest + 256 bit AES-KWP

  6. Select Create.

To generate the Google KMS wrapping key from 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

You have to retrieve the wrapping key from Google KMS.

To download the Google KMS wrapping key from the Google Cloud console web UI:

  1. On the Security > Key Management page select the Name of the key ring that contains the import job.

  2. On the Import Jobs tab, select Actions for the import job, then select Download wrapping key.

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

To download the Google KMS wrapping key from 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 cloud_integration_tool to generate, wrap and export a key

Using the downloaded wrapping key file, call cloud_integration_tool as follows:

cloud_integration_tool google-cloud-key-management <key name> <wrapping key> <wrapping algorithm> --key-type <key type>

Where:

wrapping key

The file you downloaded, for example myimportjob.pem.

wrapping algorithm

The wrapping algorithm selected in the creation of the import job.

key-type

Optional and defaults to RSA 2048-bit if none is provided.

The following target key types are available:

RSA Keys

  • 2048-bit

  • 3072-bit

  • 4096-bit

Elliptic Curve Keys

  • NISTP256

  • NISTP384

AES Keys

  • AES-256

Specify RSAES_OAEP_SHA_256 for wrapping algorithm if the import job was created with one of:

  • 3072 bit RSA - OAEP padding - SHA256 digest + 256 bit AES-KWP

  • 4096 bit RSA - OAEP padding - SHA256 digest + 256 bit AES-KWP

Specify RSAES_OAEP_SHA_1 for wrapping algorithm if the import job was created with one of:

  • 3072 bit RSA - OAEP padding - SHA1 digest + 256 bit AES-KWP

  • 4096 bit RSA - OAEP padding - SHA1 digest + 256 bit AES-KWP

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 cloud_integration_tool 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.

To upload the wrapped key material from the Google Cloud console web UI:

  1. On the Security > Key Management page select the Name of the key ring that contains the import job.

  2. Select the name of the target key, then select Import Key Version.

  3. Select the import job from the Select import job list.

  4. In Upload the wrapped key, select the wrapped key to be imported.

  5. If you are importing an asymmetric key, select from the Algorithm list.

  6. Select Import.

To upload the wrapped key material from 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 cloud_integration_tool 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.