Object hierarchy

Google Cloud Key Management Service stores cryptographic keys in a hierarchical structure designed for useful and elegant access control management. Access to resources in this structure is governed by Cloud IAM.

The levels in this hierarchy, from top to bottom, are:

  1. Project
  2. Location
  3. Key ring
  4. Key
  5. Key version

Project

Cloud KMS resources belong to a project, just like all other Google Cloud Platform resources. This means that accounts with primitive IAM roles on any project with Cloud KMS resources have corresponding permissions on those resources. For this reason, you may want to run Cloud KMS in a separate project from any other Cloud Platform resources.

Location

Within a project, Cloud KMS resources can be created in multiple locations. These represent the geographical data center location where requests to Cloud KMS regarding a given resource are handled, and where the corresponding cryptographic keys are stored.

There is a special location for Cloud KMS resources called global. When created in the global location, your Cloud KMS resources are available from multiple data centers.

For information about network performance implications of the locations you choose to host Cloud KMS resources, see Cloud KMS Locations.

Key ring

Resources

A key ring is a grouping of keys for organizational purposes. A key ring belongs to a Cloud Platform Project and resides in a specific location. Keys inherit permissions from the key ring that contains them. Grouping keys with related permissions together in a key ring allows you to grant, revoke, or modify permissions to those keys at the key ring level, without needing to act on each one individually.

Key ring resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the key ring, which is the fully-qualified KeyRing name. This value is in the form

projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]

You can retrieve the key ring resource ID using the Cloud Platform Console:

  1. Open the Cloud KMS page in the Cloud Platform Console.

    Open the Cloud KMS page

  2. For the key ring whose resource ID you are retrieving, click the More icon (3 vertical dots).

  3. Click Copy Resource ID. The resource ID for the key ring is copied to your clipboard.

Key

A key is a named object representing a cryptographic key used for a specific purpose. The key material, the actual bits used for encryption, can change over time as new key versions are created.

A key is used to protect some corpus of data. You could encrypt a collection of files with the same key, and people with decrypt permissions on that key would be able to decrypt those files.

Key resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the key, which is the fully-qualified CryptoKey name. This value is in the form:

projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]

You can retrieve the key resource ID using the Cloud Platform Console:

  1. Open the Cloud KMS page in the Cloud Platform Console.

    Open the Cloud KMS page

  2. Click the name of the key ring that contains the key.

  3. For the key whose resource ID you are retrieving, click the More icon (3 vertical dots).

  4. Click Copy Resource ID. The resource ID for the key is copied to your clipboard.

Key version

A key version represents the key material associated with a key at some point in time. Each key can have arbitrarily many versions, but must have at least one. Versions are numbered sequentially, starting with 1.

Returning to the example of a set of encrypted files, files encrypted with the same key may be encrypted with different key versions. Some of the files may be encrypted with version 1 and others with version 2. When you ask Cloud KMS to decrypt any one of these files, you specify the name of the key (not a specific version) which encrypted it. Cloud KMS automatically identifies which version was used for encryption, and uses it to decrypt the file if the version is still enabled.

The key material associated with a key version has a type, indicating the length of the key and the algorithm which will be used with it. Currently, all keys are 256-bit Advanced Encryption Standard (AES-256) keys, used in Galois Counter Mode (GCM). Cloud KMS uses probabilistic encryption, so that the same plaintext encrypted with the same key version twice will not encrypt to the same ciphertext. Key modes are not currently exposed through our API.

Key versions have states, which include enabled, disabled, scheduled for destruction or destroyed. Any version of a key can be used for decryption, until that version is explicitly moved to a disabled, destroyed, or scheduled for destruction state.

A key at any point in time will have a primary version. This is the version Cloud KMS will use to encrypt data. By creating a new key version and making that version the primary version, you can rotate a key without losing access to any data which was encrypted with past versions.

For security reasons, the raw cryptographic key material represented by a key version can never be viewed or exported. It can only be used to encrypt or decrypt data when an authorized user or application invokes the Cloud KMS service.

Key version resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the key version, which is the fully-qualified CryptoKeyVersion name. This value is in the form:

projects/[PROJECT_ID]/locations/[LOCATION]/keyRings/[KEY_RING]/cryptoKeys/[KEY]/cryptoKeyVersions/[VERSION]

You can retrieve the key version resource ID using the Cloud Platform Console:

  1. Open the Cloud KMS page in the Cloud Platform Console.

    Open the Cloud KMS page

  2. Click the name of the key ring that contains the key.

  3. Click the name of the key that contains the key version.

  4. For the key version whose resource ID you are retrieving, click the More icon (3 vertical dots).

  5. Click Copy Resource ID. The resource ID for the key version is copied to your clipboard.

Lifetime of objects

To prevent resource name collisions, key ring and key resources CANNOT be deleted. Key versions also cannot be deleted, but key version material can be destroyed so that the resources can no longer be used. Key rings and keys do not have billable costs or quota limitations, so their continued existence does not impact costs or production limits.

For information about destroying key versions, see Destroying and restoring key versions.

If you schedule the shut down of a Google Cloud Platform project, you will not be able to access the project's resources, including Cloud KMS resources, unless you recover the project by following the steps to restore a project.

Send feedback about...

Cloud KMS Documentation