This page describes each type of resource in Cloud KMS. You canlearn more about thehierarchy of resources.

Keys

A Cloud KMS key is a named object containing one or morekeyversions, along with metadata for the key. A key exists onexactly onekey ring tied to a specific location.

You can allow and deny access to keys using Identity and Access Management (IAM)permissions and roles. You can't manage access to a keyversion.

Disabling or destroying a key also disables or destroys each key version.

The following sections discuss the properties of a key.

Depending on the context, a key's properties are shown in a different format.

• When using the Google Cloud CLI or the Cloud Key Management Service API, the property is shownas a string of capital letters, likeSOFTWARE.
• When using the Google Cloud console, the property is shown as a string withinitial capitalization, likeSoftware.

In the following sections, each format is shown where it is appropriate.

Type

A key's type determines whether the key is used for symmetric or asymmetriccryptographic operations.

In symmetric encryption or signing, the same key is used to encrypt and decryptdata or to sign and verify a signature.

In asymmetric encryption or signing, the key consists of a public key and aprivate key. A private key with its corresponding public key is called akeypair.

• The private key is sensitive data, and is required to decrypt data or forsigning, depending on the key's configured purpose.
• The public key is not considered sensitive, and is required to encrypt dataor to verify a signature, depending on the key's configured purpose.

A key's type is one component of the key's purpose, and can't be changed afterthe key is created.

Purpose

A key's purpose indicates what kind of cryptographic operations the key can beused for—for example,Symmetric encrypt/decrypt orAsymmetricsigning. You choose the purpose when creating the key, and all versions of akey have the same purpose. A key's purpose can't be changed after the key iscreated. For more information about key purposes, seeKey purposes.

Protection level

A key's protection level determines the key's storage environment atrest. The protection level is one of the following:

• Software (SOFTWARE)
• Multi-tenant HSM (HSM)
• Single-tenant HSM (HSM_SINGLE_TENANT)
• External (EXTERNAL)
• External_VPC (EXTERNAL_VPC)

The protection level of a key can't be changed after the key is created.

Primary version

Keys can have multiplekey versions active and enabled at onetime. Symmetric encryption keys have a primary key version, which is the keyversion used by default to encrypt data if you don't specify a key version.

Asymmetric keys don't have primary versions; you must specify the version whenusing the key.

For both symmetric and asymmetric keys, you can use any enabled key version toencrypt and decrypt data or to sign and validate signatures.

Key versions

Each version of a key contains key material used for encryption or signing. Eachversion is assigned a version number, starting at1. Rotating a key creates anew key version. You can learn more aboutrotatingkeys.

To decrypt data or verify a signature, you must use the same key version thatwas used to encrypt or sign the data. To find a key version's resource ID, seeRetrieving a key's resource ID.

You can disable or destroy individual key versions without affecting otherversions. You can also disable or destroy all key versions for a given key.

You can't control access to key versions independently of the permissions ineffect on the key. Granting access to a key grants access to all of that key'senabled versions.

For security reasons, no Google Cloud principal can view or export the rawcryptographic key material represented by a key version. Instead,Cloud KMS accesses the key material on your behalf.

The following sections discuss the properties of a key version.

State

Each key version has astate that tells you what its status is. Usually, akey's state will be one of the following:

• Enabled
• Disabled
• Scheduled for destruction
• Destroyed

A key version can only be used when it's enabled.Key versions in any state other than destroyed incurcosts.For more information about key version states and how versions can transitionbetween them, seeKey version states.

Algorithm

A key version'salgorithm determines how the key material is created and theparameters required for cryptographic operations. Symmetric and asymmetric keysuse different algorithms. Encryption and signing use different algorithms.

If you don't specify an algorithm when creating a new key version, the algorithmof the previous version is used.

Regardless of the algorithm, Cloud KMS uses probabilistic encryption,so that the same plaintext encrypted with the same key version twice doesn'treturn the same ciphertext.

Key rings

A key ring organizes keys in a specific Google Cloudlocation and lets you manage access control on groups of keys. A key ring's namedoes not need to be unique across a Google Cloud project, but must beunique within a given location. After creation, a key ring cannot be deleted.Key rings don't incur any costs.For a list of available locations, seeCloud KMS locations.

Key handles

A key handle is a Cloud KMS resource that helps you safely span theseparation of duties to create new Cloud KMS keys for CMEK usingAutokey. The creation of a key handle in a resource project triggersthe creation of a Cloud KMS key in the key project for on-demand CMEKsetup.

A key handle holds a reference to the Cloud KMS key that wascreated. You can retrieve the Cloud KMS resource ID of a key createdby Autokey from the key handle. Infrastructure-as-code tooling likeTerraform can work with key handles to manage CMEK-protected resources withoutelevated privileges.

Key handles are not visible in the Google Cloud console, but to use Autokeywith the REST API or Terraform, you must work with key handles. For moreinformation about using key handles, seeCreate protected resources usingCloud KMS Autokey.

Autokey configs

An Autokey config is a folder-level resource that defines whetherAutokey is enabled for the folder. The Autokey config alsodefines which key project is used for keys created by Cloud KMS Autokey toprotect resources in that folder. When you enable Autokey, you createor update an Autokey config on the resource folder. For moreinformation about using Autokey configs, seeEnableCloud KMS Autokey.

EKM connections

An EKM connection is a Cloud KMS resource that organizesVPC connections to your on-premises EKMs in a specificGoogle Cloud location. An EKM connection lets you connect to and usekeys from an external key manager over a VPC network. Aftercreation, an EKM connection cannot be deleted.EKM connections don't incur any costs.

Retrieving a resource's ID

Some API calls and gcloud CLI might require you to refer to a keyring, key, or key version by its resource ID, which is a string representing thefully-qualifiedCryptoKeyVersion name. Resource IDs are hierarchical, similarto a file system path. A key's resource ID also contains information about thekey ring and location.

Object	Resource Id format
Key ring	projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING
Key	projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME
Key version	projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION
Key handle	projects/RESOURCE_PROJECT_ID/locations/LOCATION/keyHandles/KEY_HANDLE
EKM connection	projects/PROJECT_ID/locations/LOCATION/ekmConnections/EKM_CONNECTION
Autokey config	folders/FOLDER_NUMBER/autopilotConfig

To learn more, seeGetting a Cloud KMS resource ID.

Organizing resources

When you are planning how to organize the resources in your Google Cloudproject, consider your business rules and how you plan to manage access. You cangrant access to a single key, all keys on a key ring, or all keys in a project.The following organization patterns are common:

• By environment, such asprod,test, anddevelop.
• By work area, such aspayroll orinsurance_claims.
• By data sensitivity or characteristics, such asunrestricted,restricted,confidential,top-secret.

Resource life cycles

Key rings, keys, and key versions cannot be deleted. This ensures that theresource identifier of akey version is unique and always points to the original key material for that key version unless ithas been destroyed.You can store an unlimited number of key rings, enabled or disabled keys, andenabled, disabled, or destroyed key versions.For more information, seePricing andQuotas.

To learn how to destroy or restore a key version, seeDestroying and restoringkey versions.

After you schedule theshutdown of a Google Cloud project,you can't access the project's resources, including Cloud KMSresources, unless you recover the project by following the steps torestore aproject.

Warning: Once you schedule the shutdown of a project, there is alimited periodof time when you can recover the project. After the limitedtime, the project and all the resources under it are permanently destroyed andcan't be recovered.

What's next

• Create a key.
• Learn more aboutpermissions and roles inCloud KMS.