Importing a 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 raw 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.

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 ImportMethod that you want to use to wrap your key.

To create an import job:

gcloud

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

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:

gcloud

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

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

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:

gcloud

Run the gcloud beta kms import-jobs describe command.

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

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.

If your source HSM (or other key provider if not using HSM) supports exporting a key to a PKCS #11 with the RSA AES key wrap mechanism (CKM_RSA_AES_KEY_WRAP), use the HSM's export capability and the import job's public key to create a PKCS #11 file.

If your source HSM (or other key provider if not using HSM) does not support PKCS #11 using the RSA AES key wrap mechanism, you need to manually create a PKCS #11 file using the import job's public key. For one example of how to do this using OpenSSL, see Wrapping a key using OpenSSL on Linux.

The output of wrapping your key are the following items:

  • The wrapped ephemeral AES key, which is used to wrap the key you want to import.
  • The wrapped target key, which is for the key that you want to import.

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:

gcloud

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

gcloud beta kms keys 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

The following shows output from the gcloud beta kms keys 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:

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

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.

Verify your imported key

After your key is imported, you can verify that the key contains your key material and is HSM-protected.

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.

Kunde den här sidan hjälpa dig? Berätta:

Skicka feedback om ...