Object hierarchy

Cloud KMS 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. KeyRing
  4. CryptoKey
  5. CryptoKeyVersion

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 Google 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. You should consider the network performance implications of the Location you choose to host Cloud KMS resources, and note that there is no guarantee that your Cloud KMS data is permanently confined to the specified location.

Interactions with resources in a location close to you are more likely to be fast and reliable. Choose a specific region if the users and services that depend on a KMS resource are geographically concentrated. Remember that users and services who are far away from the location chosen may experience higher latency.

There is a special location for KMS resources called global. When created in the global location, your KMS resources are available from multiple data centers. This means that read operations, like keyRings.list will be served by a data center close to the requesting user or service. However, write operations, like keyRings.create, must propagate to multiple data centers when performed on global resources, and will be slower as a result. If your usage of KMS involves many read operations from users and services around the world, or involves very few write operations, consider creating global resources.

Available locations for Cloud KMS

Cloud KMS resources can be created in the following locations:

  • global
  • us-east1
  • us-central1
  • us-west1
  • europe-west1
  • asia-east1
  • asia-southeast1

More about locations

KeyRing

Resources

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

KeyRing resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the KeyRing, 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 KeyRing 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 KeyRing whose resource ID you are retrieving, click the More icon (3 vertical dots).

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

CryptoKey

A CryptoKey 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 CryptoKeyVersions are created.

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

CryptoKey resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the CryptoKey, 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 CryptoKey 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 KeyRing that contains the CryptoKey.

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

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

CryptoKeyVersion

A CryptoKeyVersion represents the key material associated with a CryptoKey at some point in time. Each CryptoKey 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 CryptoKey may be encrypted with different CryptoKeyVersions. 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 CryptoKey (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 CryptoKeyVersion 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) keys, used in Galois Counter Mode (GCM). Cloud KMS uses probabilistic encryption, so that the same plaintext encrypted with the same CryptoKeyVersion twice will not encrypt to the same ciphertext. Key modes are not currently exposed through our API.

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

A CryptoKey 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 CryptoKeyVersion and making that version the primary version, you can rotate a CryptoKey without losing access to any data which was encrypted with past versions.

For security reasons, the raw cryptographic key material represented by a CryptoKeyVersion 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.

CryptoKeyVersion resource ID

Some API calls and gcloud command-line tool commands may require the resource ID of the CryptoKeyVersion, 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 CryptoKeyVersion 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 KeyRing that contains the CryptoKey.

  3. Click the name of the CryptoKey that contains the CryptoKeyVersion.

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

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

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud KMS Documentation