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

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.

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.

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.

Send feedback about...

Cloud KMS Documentation