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 Key Management Service.

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

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

6. Ensure that the key you want to import is in the correct 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, using one of the supported import methods. The import method determines the algorithm used to create the 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 tool 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 the gcloud tool, 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 one of the supported import methods.

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

Supported import methods

The following import methods are supported:

• rsa-oaep-3072-sha1-aes-256
• rsa-oaep-4096-sha1-aes-256.

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-and-file-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 output of the gcloud kms keys versions import shows the algorithm, the creation and generation timestamps, name, protection level, and enablement status of the imported key.

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 key-version \
  --location location \
  --keyring keyring-name \
  --key key-name

The value for key-version is the last portion of the name value.

Optionally, replace location with a valid Cloud 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 in 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.