Importing a key into Cloud KMS

This topic shows you how to use the gcloud command-line tool to automatically wrap and import key material that was created from outside of Cloud KMS.

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.

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. Install the Pyca cryptography library, which is required by the automatic wrapping functionality in the gcloud command-line tool.

  6. Ensure that the key you want to import is in the correct format.

Key import flow

Import flow

To import a key:

  1. Create an import job. When you create an import job, Cloud KMS generates a public/private key pair. The public key is used to encrypt your key material on the client, before it is sent to Cloud KMS. The private key is stored in Cloud HSM, which prevents Google from unwrapping your key material outside of Cloud HSM.

    An import job may be used multiple times until it expires 3 days after creation. Once expired, Cloud KMS will no longer be able to import or unwrap any key material corresponding to the import job.

  2. Make an import request. The gcloud command will:

    a. Automatically download the public key for the import job.

    b. Encrypt your provided key material on the client.

    c. Transmit the encrypted key material to Cloud KMS.

If you prefer to wrap the key yourself instead of using gcloud, please follow the instructions at Importing a pre-wrapped key instead.

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:

gcloud kms import-jobs create IMPORT_JOB \
  --location LOCATION \
  --keyring KEYRING_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.

Check the state of the import job

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

Use the describe command to check the state. You must wait for the state to become ACTIVE before attempting a key import.

gcloud kms import-jobs describe IMPORT_JOB \
  --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.

Make a request to import your key

To import the key:

gcloud kms keys versions import \
  --import-job IMPORT_JOB \
  --location LOCATION \
  --keyring KEYRING_NAME \
  --key KEY_NAME \
  --algorithm ALGORITHM_NAME \
  --target-key-file PATH_TO_KEY_TO_IMPORT

You can optionally use the --public-key-file flag to specify the file that contains the import job's public key. If --public-key-file is not specified, Cloud KMS will retrieve the public key from the import job.

You can optionally specify 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

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.

Use the versions describe command to check the state.

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

The value for VERSION is the last portion of the name value.

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

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

Verify your imported key

After your key is imported, you can verify that the key contains your key material and is HSM-protected. Verification varies based on the type of key that was imported into Cloud KMS.

Symmetric Keys

Use the Extended Key Checksum Value (EKCV) key attribute to verify the key material. This value is calculated by following RFC 5869, section 2. The value is derived using SHA-256-based HMAC-based Extract-and-Expand Key Derivation Function (HKDF) with 32 zero bytes as salt and expanding it with the fixed string Key Check Value as info. This value can be retrieved by looking at the key's attestation. For more information about checking the EKCV key attribute, see To verify key properties.

Asymmetric Keys

When you make the import request for an asymmetric key, you include your wrapped private key. The private key contains sufficient information for Cloud KMS to derive the public key. After your key is imported, you can retrieve the public key and verify that it matches the public key you have stored locally. For more information about checking the public key attribute, see To verify the public key.

You can also use the EKCV verification for asymmetric keys. In this case, the value is the SHA-256 digest of the DER-encoded public key. You can retrieve this value by looking at the key's attestation. For more information about checking the EKCV key attribute, see To verify key properties.

For additional information about attesting keys you import, see Verifying Attestations.

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

Send feedback about...