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:
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.
Within a project, Cloud KMS resources can be created in multiple
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
When created in the
global location, your KMS resources are
available from multiple data centers. This means that read operations, like
will be served by a data center close to the requesting user or service. However, write operations, like
must propagate to multiple data centers when performed on
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
Available locations for Cloud KMS
Cloud KMS resources can be created in the following locations:
More about locations
is a grouping of
for organizational purposes. A
KeyRing belongs to a Google Cloud
Platform Project and resides in a specific
CryptoKeys inherit permissions from the
contains them. Grouping
CryptoKeys with related permissions
together in a
KeyRing allows you to grant, revoke, or modify
permissions to those
CryptoKeys at the
without needing to act on each one individually.
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
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
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
CryptoKey may be encrypted with different
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
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
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.