Importing a raw key into Cloud KMS

Beta

This feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

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

Note: You can import only into keys with protection level HSM.

Introduction

Cloud KMS allows you to import cryptographic key material from an external source such as an on-premesis key management service or a different cloud services provider.

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. If you are going to use the gcloud command-line tool, install the Pyca cryptography library.

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

Key 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 automatically download the public key for the import job, encrypt your provided key material on the client, and then 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 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 ImportMethod that you want to use to wrap your key.

To create an import job:

gcloud

gcloud beta 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.

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. Once the state is ACTIVE, the import job is ready to use.

To check the state:

gcloud

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

gcloud beta 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.

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.

Make a request to import your key

To import the key:

gcloud beta 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 beta 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.

To check the state:

gcloud

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.

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.

Note: The imported key will not automatically rotate.You can enable automatic rotation (or manually rotate the key in Cloud KMS), but the rotated key will no longer be synchronized with your originally imported key.

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.