This topic covers conceptual information about importing keys intoCloud Key Management Service as new key versions. For step-by-step instructions, seeimporting a key version.

Introduction

You may be using existing cryptographic keys that were created on your premisesor in an external key management system. If you migrate an application toGoogle Cloud or if you add cryptographic support to an existingGoogle Cloud application, you can import the relevant keys intoCloud KMS.

• You can import into Multi-tenant Cloud HSM keys, Single-tenant Cloud HSM keys, or software keys in Cloud KMS.
• Key material is wrapped for protection in transit. You can use the Google Cloud CLI to automatically wrap the key, or you canwrap the key manually.
• Google Cloud has access to the wrapping key only within the scope of the import job. For Cloud HSM keys, the wrapping key never resides outside of Cloud HSM.

This topic provides details about limitations and requirements forimporting keys, and gives an overview ofhow key import works.

Limitations and requirements

Review these sections to verify that your keys can be imported intoCloud KMS.

Supported key formats

• Symmetric keys for encryption: Imported symmetric keys must be 16 bytes (forraw symmetric encryption only) or 32 bytes of binary data, and mustnot be encoded. If your key is hex-encoded or base64-encoded, then you must decode it before attempting to import it.
• Symmetric keys for signing (MAC keys): Imported HMAC signing keys must have a length equal to the output length of the cryptographic hash function being used (for example, HMAC-SHA256 keys must have a length of 32 bytes), and mustnot be encoded. If your key is hex-encoded or base64-encoded, then you must decode it before attempting to import it.
• Asymmetric keys for encryption or signing: Imported asymmetric keys must be in PKCS #8 format and must be DER-encoded. PCKS #8 format is defined inRFC 5208. DER encoding is defined inInternational Telecommunications Union X.680. Asymmetric keys must use one of thelength and algorithm combinations supported by Cloud KMS.

Important: An RSA key's public exponent must be 65,537 or higher. This is aDigital Signature Standard (DSS) requirement noted in the Criteria for IFC KeyPairs section ofFIPS PUB 186-4,Section B.3.1

Some aspects of a key, such as the key's length, cannot be changed after the keyis created. In these cases, the key cannot be imported into Cloud KMS.

To verify and reformat your key for import, seeFormatting keys for import.

Supported protection levels

You can import a key into a Cloud KMS key, aMulti-tenant Cloud HSM key, or a Single-tenant Cloud HSM key bysetting the key'sprotection level toSOFTWARE,HSM, orHSM_SINGLE_TENANT.You can't import into a Cloud External Key Manager key.

Supported wrapping key sizes

When you create an import job, you can control the size of the wrapping key usedto protect your key in transit to Google Cloud by setting the import job'simport method. The default size for the wrapping key is 3072. If you havespecific requirements, you can configure the import job to use a 4096-bit keyinstead.

You can learn more about the algorithms used forkey wrapping or aboutconfiguring an import job.

How key import works

This section illustrates what happens when you import a key. Some parts of theflow are different if you use automatic wrapping or manually wrap the key. Usingautomatic wrapping is recommended. For specific instructions, seeImport a key version. For specific instructionsabout manually wrapping your key before import, seeWrapping a key using OpenSSL on Linux.

The following diagram illustrates the key import process using automatic keywrapping. The phases shown in the diagram are described in this section.

1. Get ready to import keys.

   1. First, youcreate a target key ring andkey that will eventuallycontain the import job and the imported key material. At this point, thetarget key contains no key versions.

   2. Next, youcreate an import job. Theimport job defines the target key ring and key for the imported keymaterial. The import job also defines the import method, which is thealgorithm used to create the wrapping key that protects the key materialduring import requests.

      • The public key is used to wrap the key to be imported on the client.
      • The private key is stored within Google Cloud and is used tounwrap the key after it reaches the Google Cloud project.

      This separation prevents Google from being able to unwrap your keymaterial outside of the scope of the import job.

   3. The key must be cryptographically wrapped before transmitting it toGoogle. Most users can use the gcloud CLI to automaticallywrap, transmit, and import the key, as described in the next step. Ifyou have compliance or regulatory requirements towrap the key manually, you can do it at thistime. To wrap the key manually on the local system:

      1. Configure OpenSSL.
      2. Once per import job, download the wrapping key associated with theimport job.
      3. Once per key, set several environment variables and wrap the key.

2. For up to three days, until the import job expires, you can use it tomake import requests to importone or more keys. During an import request:

   1. If the key was not manually wrapped, the Google Cloud CLI downloads theimport job's public key from Google Cloud to the local system,then uses the public key, along with a private key associated with theclient, to wrap the local key material.
   2. The wrapped key material is transmitted to the Google Cloudproject.
   3. The key material is unwrapped using the import job's private key and isinserted as a new version of the target key on the target key ring. Thisis an atomic operation.
   4. For symmetric keys, you set the imported key version to be the primarykey version.
   Note: The imported key version is not automatically set to be the primarykey version.

After the import request completes successfully, you can use the imported keyversion to protect data in Google Cloud.

What's next

• Import a key version
• Encrypt and decrypt data using a symmetric key
• Encrypt and decrypt data using an asymmetrickey
• Learn aboutCreating and validating digitalsignatures