Importing a pre-wrapped key into Cloud KMS

This topic shows you how to manually wrap your key that was created from a source other than Cloud Key Management Service and then import it to Cloud KMS.

If you want to have Cloud KMS automatically wrap your key instead of you manually wrapping your key, see Importing a key.

Introduction

Cloud KMS allows you to import user-provided cryptographic keys. As an example, you might have existing keys that you use on-premises, with a key store other than Cloud KMS, and/or in a multi-cloud environment. You can import those keys if you want to use the existing key material with Cloud KMS.

To import your keys, first create an import job, which is a temporary resource used only for importing keys. When you create an import job, Cloud KMS generates a "wrapping key", which is a public/private key pair. You use the public key portion of the wrapping key to encrypt (also known as wrap) your pre-existing key material to protect it during the import process. Once your key material is wrapped, you can import it into a new key or key version. The private key portion of the wrapping key is available only within Cloud HSM. Restricting the private key portion to Cloud HSM prevents Google from unwrapping your key material outside of Cloud HSM.

You can repeatedly use the same import job to wrap multiple keys that you want to import. Note that an import job expires 3 days after it is created. Once expired, Cloud KMS will no longer be able to import or unwrap any key material that was wrapped with the import job's public key.

Before you begin

  1. This topic assumes you are already using Cloud KMS. If you are not already using Cloud KMS, follow the steps in the Cloud KMS QuickStart.
  2. Create a key ring in a region that supports Cloud HSM as described in Creating key rings.
  3. Create a key with protection level HSM as described in Creating keys.
  4. Set up Cloud Identity and Access Management permissions for the key ring and key.
  5. Ensure that the key you want to import is in the correct format.

Key import flow

To import a key, follow these steps.

  1. Create an import job.
  2. Retrieve the wrapping key from the import job.
  3. Wrap the key that you want to import.
  4. Make an import request.

Create an import job

Import jobs are ImportJob resources. When you create an import job, you need to specify the protection level and import method that you want to use to wrap your key.

To create an import job:

Console

  1. Open the Cryptographic Keys page in the GCP Console.

  2. Click the name of the key ring for which you will create an import job.

  3. Click Create import job.

  4. In the Name field, enter the name for your import job.

  5. From the Import method dropdown, select an import method.

  6. Click Create.

gcloud

gcloud kms import-jobs create \
--location LOCATION \
--keyring KEYRING_NAME \
IMPORTJOB_NAME \
--import-method IMPORT_METHOD \
--protection-level hsm

Replace IMPORT_METHOD with either rsa-oaep-3072-sha1-aes-256 or rsa-oaep-4096-sha1-aes-256.

You can optionally specify LOCATION with a valid KMS location. You can get a list of location values using gcloud kms locations list.

API

  1. Create an instance of the ImportJob type. Provide initial values for the ImportJob.protectionLevel and ImportJob.importMethod fields.

  2. Using your instance of ImportJob as the request body, call the ImportJob.create method.

Check the state of the import job

The initial state for an import job is PENDING_GENERATION. When the state is ACTIVE, the import job is ready to use.

To check the state:

Console

  1. Open the Cryptographic Keys page in the GCP Console.

  2. Click the name of the key ring that contains your import job.

  3. Click the Import Jobs tab at the top of the page.

  4. The state will be visible under Status next to your import job's name.

gcloud

Use the gcloud kms import-jobs describe command to check the state.

gcloud kms import-jobs \
describe IMPORTJOB_NAME \
--location LOCATION \
--keyring KEYRING_NAME

You can optionally specify LOCATION with a valid KMS location. You can get a list of location values using gcloud kms locations list.

API

Call the ImportJob.get method and check the state field. If state is PENDING_GENERATION, the import job is still being created. Periodically recheck the state until it is ACTIVE.

Retrieve the wrapping key

To retrieve the wrapping key:

Console

  1. Open the Cryptographic Keys page in the GCP Console.

  2. Click the name of the key ring that contains your import job.

  3. Click the Import Jobs tab at the top of the page.

  4. Click the More icon (3 vertical dots) next to your import job.

  5. Click Download wrapping key in the pop-up menu.

gcloud

Run the gcloud kms import-jobs describe command.

gcloud kms import-jobs \
describe IMPORTJOB_NAME \
--location LOCATION \
--keyring KEYRING_NAME

If the import job state becomes ACTIVE, the pem field within the public_key field is the public key encoded in Privacy Enhanced Mail (PEM) format.

You can optionally specify LOCATION with a valid KMS location. You can get a list of location values using gcloud kms locations list.

name: projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING_NAME]/importJobs/[IMPORTJOB_NAME]
createTime: '2019-03-21T17:10:10.864211749Z'
generateTime: '2019-03-21T17:10:10.864211749Z'
importMethod: [IMPORT_METHOD]
protectionLevel: [PROTECTION_LEVEL]
state: ACTIVE
public_key:
  pem: -----BEGIN PUBLIC KEY-----
[PUBLIC_KEY]
-----END PUBLIC KEY-----

API

  1. Call the ImportJob.get method.

  2. Retrieve the public key via the publicKey field of the ImportJob.get response. This value is of type WrappingPublicKey. The pem field of the WrappingPublicKey type is the public key encoded in Privacy Enhanced Mail (PEM) format.

For more information about the PEM-encoded format, see the RFC 7468 sections for General Considerations and Textual Encoding of Subject Public Key Info.

Wrap the key material

Wrap your pre-existing key material using the import job's public key, which is the PEM value that you retrieved in the previous step. The documentation for the import method associated with your import job contains more specific instructions for how your key should be wrapped.

Make a request to import your key

When you include wrapped key material in a request to create a new key or a new key version, Cloud KMS unwraps your key material and stores it in the resulting key version.

To make an import request that includes your wrapped key:

Console

Create a key to import your key material into.

  1. Open the Cryptographic Keys page in the GCP Console.

  2. Click the name of the key ring that contains your import job.

  3. Click Create key.

  4. In the Key name field, enter the name for your key.

  5. In the Protection level dropdown, select HSM.

  6. Select the Purpose corresponding to your key from the dropdown. If you selected an asymmetric purpose, select the appopriate Algorithm from the dropdown.

  7. Under Key material, select Import key material. Your Create key page should look similar to:

    Create a key

  8. Click Create.

You will be redirected to the Import key version page.

  1. Select your import job from the Select import job dropdown.

  2. In the Upload the wrapped key selector, selector the key material that you wrapped in the Wrap the key material step.

  3. If you are importing an asymmetric key, select the algorithm from the Algorithm dropdown. Your Import key version page should look similar to:

    Import key version

  4. Click Import.

gcloud

Import the key using the gcloud kms keys versions import command.

gcloud kms keys versions import \
--location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME \
--import-job IMPORTJOB_NAME \
--algorithm ALGORITHM_NAME \
--rsa-aes-wrapped-key-file=PATH_TO_WRAPPED_RSA_AES_KEY

You can specify a LOCATION with a valid KMS location. You can get a list of location values using gcloud kms locations list.

The following shows output from the gcloud kms keys versions import command.

algorithm: [ALGORITHM]
createTime: '2019-03-21T17:10:10.864211749Z'
generateTime: '2019-03-21T17:10:10.864211749Z'
name: projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING_NAME]/cryptoKeys/[KEY_NAME]/cryptoKeyVersions/1
protectionLevel: [PROTECTION_LEVEL]
state: ENABLED

API

  1. For the request body of the cryptoKeyVersions.import method, set the algorithm field to the algorithm of the key being imported. This value does not need to match the versionTemplate of the CryptoKey that is importing this version. The algorithm field is of type CryptoKeyVersionAlgorithm.

  2. Also for the request body, set the wrappedKeyMaterial field to the key material that you wrapped in the Wrap the key material step.

  3. Call the cryptoKeyVersions.import method. The cryptoKeyVersions.import response is of type CryptoKeyVersion. When a key is successfully imported, its state is ENABLED and you can use it via Cloud KMS.

Check the state of the imported key

The initial state for an imported key is PENDING_IMPORT. When the state is ENABLED, the imported key is ready to use.

To check the state:

Console

  1. Open the Cryptographic Keys page in the GCP Console.

  2. Click the name of the key ring that contains your key.

  3. Click the name of your key.

  4. The state will be visible under State next to the newly imported version.

gcloud

Use the gcloud kms keys versions describe command to check the state.

gcloud kms keys versions \
describe VERSION \
--location LOCATION \
--keyring KEYRING_NAME \
--key KEY_NAME

Replace LOCATION with a valid KMS location. You can get a list of location values using gcloud kms locations list.

API

Call the CryptoKeyVersions.get method and check the state field. If state is PENDING_IMPORT, the key is still being imported. Periodically recheck the state until it is ENABLED.

When a key is successfully imported, its state is ENABLED and you can use it via Cloud KMS.

To verify that the key contains your key material and is HSM-protected, see Verify your imported key.

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

Send feedback about...