This topic shows you how to import a cryptographic key into Cloud HSM or Cloud Key Management Service as a new key version.
For more details about importing keys, including limitations and restrictions, see key import.
You can complete the steps in this topic in 5 to 10 minutes, not including the Before you begin steps. Wrapping the key manually adds complexity to the task.
Before you begin
We recommend that you create a new project to test this feature, to ease clean-up after testing and to ensure that you have adequate Identity and Access Management (IAM) permissions to import a key.
Before you can import a key, you need to prepare the project, the local system, and the key itself.
Preparing the project
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
The user performing the import needs the following IAM permissions to create key rings, keys, and import jobs. If the user is not the project owner, you can assign both of the following two predefined roles to the user:
roles/editor
roles/cloudkms.importer
For more information about available IAM roles and permissions for Cloud KMS, refer to Permissions and roles.
Preparing the local system
Prepare the local system by choosing one of the following options. Automatic key wrapping is recommended for most users.
- If you want to allow the Google Cloud CLI to wrap your keys automatically before transmitting them to Google Cloud, you must install the Pyca cryptography library on your local system. The Pyca library is used by the import job that wraps and protects the key locally before sending it to Google Cloud.
- If you want to wrap your keys manually, you must configure OpenSSL for manual key wrapping.
Preparing the key
Verify that your key's algorithm and length are supported. Allowable algorithms for a key depend upon whether the key is used for symmetric encryption, asymmetric encryption or asymmetric signing, as well as whether the key is stored in software or an HSM. You specify the key's algorithm as part of the import request.
Separately, you must also verify how the key is encoded, and make adjustments if necessary.
The following can't be changed for a key version after it is created or imported:
The protection level indicates whether the key persists in software, in an HSM, or in an external key management system. Key material cannot be moved from one of these storage environments to another. All versions of a key have the same protection level.
The purpose indicates whether versions of the key are used for symmetric encryption, asymmetric encryption, or asymmetric signing. The purpose of the key limits the possible algorithms that can be used to create versions of that key. All versions of a key have the same purpose.
If you don't have a key to import but want to validate the procedure for importing keys, you can create a symmetric key on the local system, using the following command:
openssl rand 32 > ${HOME}/test.bin
Use this key for testing only. A key created this way might not be appropriate for production use.
If you need to wrap the key manually, do that before continuing with the procedures in this topic.
Create the target key and key ring
A Cloud KMS key is a container object that contains zero or more key versions. Each key version contains a cryptographic key.
When you import a key into Cloud KMS or Cloud HSM, the imported key becomes a new key version on an existing Cloud KMS or Cloud HSM key. In the rest of this topic, this key is called the target key. The target key must exist before you can import key material into it.
Importing a key version has no effect on that key's existing versions. However, It is recommended to create an empty key when testing key import. An empty key has no version, isn't active, and can't be used.
You may optionally specify that your newly created key may only contain imported versions, which prevents accidental generation of new versions in Cloud KMS.
A key exists on a key ring; in this topic, this key ring is called the target key ring. The location of the target key ring determines the location where the key material is available after import. Cloud HSM keys cannot be created or imported in some locations. After a key is created, it cannot be moved to a different key ring or location.
Follow these steps to create an empty key on a new key ring using the Google Cloud CLI or the Google Cloud console.
Console
In the Google Cloud console, go to the Key Management page.
Click Create key ring.
In the Key ring name field, enter the name for your key ring.
Under Location type, select a location type and location.
Click Create. The Create key page opens.
In the Key name field, enter the name for your key.
For Protection level, select either Software or HSM, and then click Continue.
For Key material, select Imported key and then click Continue. This prevents an initial key version from being created.
Set the Purpose and Algorithm for the key and then click Continue.
Optional: If you want this key to contain only imported key versions, select Restrict key versions to import only. This prevents you from accidentally creating new key versions in Cloud KMS.
Optional: For imported keys, automatic rotation is disabled by default. To enable automatic rotation, select a value from the Key rotation period field.
If you enable automatic rotation, new key versions will be generated in Cloud KMS, and the imported key version will no longer be the default key version after a rotation.
Click Create.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Create the target key ring. If you intend to import into a Cloud HSM key, select a location with support for Cloud HSM.
gcloud kms keyrings create KEY_RING \ --location LOCATION
You can learn more about creating key rings.
Create the target key.
- Specify the key's purpose.
- Prevent an initial version from being created by using the
--skip-initial-version-creation
flag. - Optional: Prevent new versions from being created in
Cloud KMS by using the
--import-only
flag. - Optional: Do not specify a rotation policy. If you enable automatic
rotation, new key versions will be generated in
Cloud KMS, and the imported key version will no longer
be the default key version after a rotation. You may not specify a
rotation policy if you specified the
--import-only
flag.
gcloud kms keys create KEY_NAME \ --location LOCATION \ --keyring KEY_RING \ --purpose PURPOSE \ --skip-initial-version-creation \ --import-only
You can learn more about creating Cloud KMS keys or Cloud HSM keys.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Create a new key ring:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings?keyRingId=KEY_RING" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --header "x-goog-user-project: PROJECT_ID" \ --data "{}"
See the
KeyRing.create
API documentation for more information.Create an empty, import-only key:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?cryptoKeyId=KEY_NAME&skipInitialVersionCreation=true&importOnly=true" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --header "x-goog-user-project: PROJECT_ID" \ --data "{"purpose":"PURPOSE", "versionTemplate":{"protectionLevel":"PROTECTION_LEVEL","algorithm":"ALGORITHM"}}"
See the
CryptoKey.create
API documentation for more information.
The key ring and key now exist, but the key contains no key material, has no version, and is not active. Next, you create an import job.
Create the import job
An import job defines the characteristics of the keys it imports, including properties that cannot be changed after the key is imported.
The protection level defines whether keys imported by this import job will reside in software, in a HSM, or in an external key management system. The protection level can't be changed after the key is eventually imported.
The import method defines the algorithm used to create the wrapping key that protects imported keys during transit from your local system to the target Google Cloud project. You can choose a 3072-bit or a 4096- bit RSA key. Unless you have specific requirements, the 3072-bit wrapping key is recommended.
You can create an import job using the gcloud CLI, the Google Cloud console, or the Cloud Key Management Service API.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the target key ring.
Set the Protection level to either Software or HSM. Use the same protection level as you set for the target key.
Click Create import job.
In the Name field, enter the name for your import job.
From the Import method dropdown, set the import method to either 3072 bit RSA or 4096 bit RSA.
Click Create.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Use a command like the following to create an import job.
gcloud kms import-jobs create IMPORT_JOB \ --location LOCATION \ --keyring KEY_RING \ --import-method IMPORT_METHOD \ --protection-level PROTECTION_LEVEL
- Use the same key ring and location as the target key.
- Set the protection level to either
software
orhsm
. - Set the import method to either
rsa-oaep-3072-sha1-aes-256
rsa-oaep-4096-sha1-aes-256
,rsa-oaep-3072-sha256-aes-256
,rsa-oaep-4096-sha256-aes-256
,rsa-oaep-3072-sha256
, orrsa-oaep-4096-sha256
.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To create an import job, use the
ImportJobs.create
method:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs?import_job_id=IMPORT_JOB_ID" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"import_method": "IMPORT_METHOD", "protection_level": "PROTECTION_LEVEL"}'
Replace the following:
- IMPORT_METHOD: a supported key-wrapping method.
- PROTECTION_LEVEL: the protection level of the key versions imported by this import job.
Checking the state of the import job
The initial state for an import job is PENDING_GENERATION
. When the state is
ACTIVE
, you can use it to import keys.
An import job expires after three days. If the import job is expired, you must create a new one.
You can check the status of an import job using the Google Cloud CLI, the Google Cloud console, or the Cloud Key Management Service API.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains your import job.
Click the Import Jobs tab at the top of the page.
The state will be visible under Status next to your import job's name.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
When an import job is active, you can use it to import keys. This may take a few minutes. Use this command to verify that the import job is active. Use the location and keyring where you created the import job.
gcloud kms import-jobs describe IMPORT_JOB \ --location LOCATION \ --keyring KEY_RING \ --format="value(state)"
The output is similar to the following:
state: ACTIVE
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To check the state of an import job, use the
ImportJobs.get
method:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/importJobs/IMPORT_JOB_ID" \ --request "GET" \ --header "authorization: Bearer TOKEN"
As soon as the import job is active, you can make a request to import a key.
Preventing modification of import jobs
The import job determines many characteristics of the imported key, including the key's algorithm and whether an imported key is an HSM key or a software key. You can configure IAM permissions to prevent users from creating import jobs, while allowing them to use import jobs to import keys.
- Grant the
importjobs.create
permission only to key administrators. - Grant the
importjobs.useToImport
permission for a specific import job to the operator who will use that job to import keys. - When you create the import job, specify the protection level and algorithm for key versions imported using it.
Until the import job expires, users who have the importjobs.useToImport
and
do not have the importjobs.create
permission for a given import job can import
keys, but cannot modify the characteristics of the import job.
Import the key
After checking the status of the import job, you can make an import request.
You use different flags to make the import request, depending on whether you want the Google Cloud CLI to wrap your key automatically or if you have already wrapped your key manually.
Regardless of whether you wrapped your key manually or automatically, you must set the algorithm to a supported algorithm that matches the length of the actual key to be imported, and specifies the key's purpose.
Keys with purpose
ENCRYPT_DECRYPT
use thegoogle-symmetric-encryption
algorithm, and have a length of 32.Keys with purpose
ASYMMETRIC_DECRYPT
orASYMMETRIC_SIGN
support a variety of algorithms and lengths.A key's purpose cannot be changed after the key is created, but subsequent key versions can be created at different lengths than the initial key version.
Automatically wrapping and importing a key
If you want to use automatic wrapping, you must use the Google Cloud CLI.
Use a command like the following. Set --target-key-file
to the location of the
unwrapped key to wrap and import. Do not set --wrapped-key-file
.
You can optionally set the
--public-key-file
flag to the location where the public key has already been
downloaded. When importing a large number of keys, this prevents the public key
from being downloaded during each import. For example, you could write a script
that downloaded the public key once, then provided its location when importing
each key.
gcloud kms keys versions import \ --import-job IMPORT_JOB \ --location LOCATION \ --keyring KEY_RING \ --key KEY_NAME \ --algorithm ALGORITHM \ --target-key-file PATH_TO_UNWRAPPED_KEY
The key is wrapped by the wrapping key associated with the import job, transmitted to Google Cloud, and imported as a new key version on the target key.
Importing a manually-wrapped key
Use the instructions in this section to import a key that
you have wrapped manually. Set
--wrapped-key-file
to the location of key that you manually wrapped.
Do not set --target-key-file
.
You can optionally set the
--public-key-file
flag to the location where the public key has already been
downloaded. When importing a large number of keys, this prevents the public key
from being downloaded during each import. For example, you could write a script
that downloaded the public key once, then provided its location when importing
each key.
Console
Open the Key Management page in the Google Cloud console.
Click the name of the key ring that contains your import job. The target key is shown, along with any other keys on the key ring.
Click the name of the target key, then click Import key version.
Select your import job from the Select import job dropdown.
In the Upload the wrapped key selector, select the key that you have already wrapped.
If you are importing an asymmetric key, select the algorithm from the Algorithm dropdown. Your Import key version page should look similar to:
Click Import.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Use a command like the following.
gcloud kms keys versions import \ --import-job IMPORT_JOB \ --location LOCATION \ --keyring KEY_RING \ --key KEY_NAME \ --algorithm ALGORITHM \ --wrapped-key-file PATH_TO_WRAPPED_KEY
For more information, see the output of the
gcloud kms keys versions import --help
command.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Use the cryptoKeyVersions.import
method to
import a key.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions:import" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"importJob": "IMPORT_JOB_ID", "algorithm": "ALGORITHM", "wrappedKey": "WRAPPED_KEY"}'
Replace the following:
IMPORT_JOB_ID: the full resource name of the corresponding import job.
ALGORITHM: the
algorithm
of the key being imported, which is of typeCryptoKeyVersionAlgorithm
.WRAPPED_KEY: the manually-wrapped key in base64 format.
The key-import request is initiated. You can monitor its status.
Check the state of the imported key version
The initial state for an imported key version is PENDING_IMPORT
. When the
state is ENABLED
, the key version has been imported successfully. If the
import fails, the status is IMPORT_FAILED
.
You can check the status of an import request using the Google Cloud CLI, the Google Cloud console, or the Cloud Key Management Service API.
Console
Open the Key Management page in the Google Cloud console.
Click the name of the key ring that contains your import job.
Click the Import Jobs tab at the top of the page.
The state will be visible under Status next to your import job's name.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Use the versions list
command to check the state. Use the same
location, target key ring, and target key that you created earlier in this
topic.
gcloud kms keys versions list \ --keyring KEY_RING \ --location LOCATION \ --key KEY_NAME
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS 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
.
After the initial key version is imported, the key's status changes to Active. For symmetric keys, you must set the imported key version as the primary version before you can use the key.
Symmetric keys: Set the primary version
This step is required when importing symmetric keys, and is not relevant for asymmetric keys. An asymmetric key does not have a primary version. You must use the Google Cloud CLI to set the primary version.
gcloud kms keys set-primary-version KEY_NAME\ --location=LOCATION\ --keyring=KEY_RING\ --version=KEY_VERSION
Re-import a previously destroyed key
Cloud Key Management Service supports key re-import, which allows you to restore a
previously imported key version in DESTROYED
or IMPORT_FAILED
state to
ENABLED
state by providing the original key material. If no original key
material has ever been imported due to initial import failure, any key material
may be supplied.
Restrictions
- Only previously imported
CryptoKeyVersions
can be re-imported. - Re-imported key material must match the original key material exactly if the version was previously successfully imported.
CryptoKeyVersions
destroyed prior to the release of this feature can't be re-imported. Thereimport_eligible
field of theCryptoKeyVersion
istrue
if the version is eligible for re-import andfalse
if it isn't.
Software and Cloud HSM keys can be re-imported, but external keys can't be re-imported.
Re-importing a destroyed key
Create an ImportJob
for re-import by following the steps in
Create the import job. You may use either an existing
ImportJob
or a new ImportJob
as long as the protection level matches the
original protection level.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose key version you will re-import.
Click the key whose key version you want to re-import.
Click the three dots next to the key version you want to re-import.
Select Re-import key version
Select your import job from the Select import job dropdown.
In the Upload the wrapped key selector, select the key that you have already wrapped. This key must match the original key material.
Click Re-Import.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Re-import the key version using the original key material.
gcloud kms keys versions import \ --location LOCATION \ --keyring KEY_RING \ --key KEY_NAME \ --version KEY_VERSION \ --algorithm ALGORITHM \ --import-job IMPORT_JOB \ --target-key-file PATH_TO_KEY \
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
In the request body of the
cryptoKeyVersions.import
method, set thecryptoKeyVersion
field to the key version name of the version being imported. This must be a child of the crypto key.In the request body, set the
algorithm
field to the algorithm of the key being imported. This value must match the algorithm of the original key version. Thealgorithm
field is of typeCryptoKeyVersionAlgorithm
.In the request body, set the
wrappedKeyMaterial
field to the key material that you that you have already wrapped.Call the
cryptoKeyVersions.import
method. ThecryptoKeyVersions.import
response is of typeCryptoKeyVersion
. When a key is successfully imported, its state isENABLED
and you can use it in Cloud KMS.
What's next
- Verify an imported key. After you confirm that the imported key material is identical to the original key, you can use the key for signing or to protect data.
- Troubleshoot a failed key import.