Key import

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

Introduction

You may be using existing cryptographic keys that were created on your premises or in an external key management system. If you migrate an application to Google Cloud or if you add cryptographic support to an existing Google Cloud application, you can import the relevant keys into Cloud 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 can wrap 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 for importing keys, and gives an overview of how key import works.

Limitations and requirements

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

Supported key formats

  • Symmetric keys for encryption: Imported symmetric keys must be 16 bytes (for raw symmetric encryption only) or 32 bytes of binary data, and must not 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 must not 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 in RFC 5208. DER encoding is defined in International Telecommunications Union X.680. Asymmetric keys must use one of the length and algorithm combinations supported by Cloud KMS.

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

To verify and reformat your key for import, see Formatting keys for import.

Supported protection levels

You can import a key into a Cloud KMS key, a Multi-tenant Cloud HSM key, or a Single-tenant Cloud HSM key by setting the key's protection level to SOFTWARE, HSM, or HSM_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 used to protect your key in transit to Google Cloud by setting the import job's import method. The default size for the wrapping key is 3072. If you have specific requirements, you can configure the import job to use a 4096-bit key instead.

You can learn more about the algorithms used for key wrapping or about configuring an import job.

How key import works

This section illustrates what happens when you import a key. Some parts of the flow are different if you use automatic wrapping or manually wrap the key. Using automatic wrapping is recommended. For specific instructions, see Import a key version. For specific instructions about manually wrapping your key before import, see Wrapping a key using OpenSSL on Linux.

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