Cloud KMS resources

This topic discusses each type of resource in Cloud KMS. You can learn more about the hierarchy of resources.

Keys

A Cloud KMS key is a named object containing one or more key versions, along with metadata for the key. A key exists on exactly one key ring tied to a specific location.

You can allow and deny access to keys using Identity and Access Management (IAM) permissions and roles. It's not possible to manage access to a key version.

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 shown as a string of capital letters, like SOFTWARE.
  • When using the Google Cloud console, the property is shown as a string with initial capitalization, like Software.

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

Type

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

In symmetric encryption, the entire key is required to encrypt or decrypt data. Symmetric keys cannot be used for signing.

In asymmetric encryption or signing, the key consists of a public and private key.

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

    A key's type can't be changed after the key is created.

A key's type is one component of its purpose.

Purpose

A key's purpose determines whether the key can be used for encryption or for signing. You choose the purpose when creating the key, and all versions have the same purpose.

The purpose of a symmetric key is always Symmetric encrypt/decrypt.

The purpose of an asymmetric key is either Asymmetric encrypt/decrypt or Asymmetric signing.

A key's purpose can't be changed after the key is created.

Primary version

A key has multiple versions, but a symmetric key can have at most one primary key version. The primary key version is used to encrypt data if you do not specify a key version.

Asymmetric keys do not have primary versions; you must specify the version when using the key.

For both symmetric and asymmetric keys, you can use any enabled key version to encrypt or decrypt data, whether it is the primary version or not.

Key versions

Each version of a key contains key material used for encryption or signing. A key's version is represented by an integer, starting at 1. To decrypt data or verify a signature, you must use the same key version that was used to encrypt or sign the data. To find and reference a key version's resource ID, see Retrieving a key's resource ID.

You can disable or destroy a key version without affecting other versions. Rotating a key creates a new version. You can learn more about rotating keys.

Disabling or destroying a key also disables or destroys all versions of that key. You can selectively disable a key version without affecting other key versions.

It's not possible to manage access to a key version. Granting access to a key also grants access to all of its enabled versions.

For security reasons, no Google Cloud principal can view or export the raw cryptographic 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

A key version's state is always one of the following:

  • Enabled
  • Disabled
  • Scheduled for destruction
  • Destroyed

A key version can only be used when it is enabled. Key versions in any state other than destroyed incur costs.

Protection level

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

  • Software (SOFTWARE in the Google Cloud CLI and Cloud Key Management Service API)
  • HSM
  • External (EXTERNAL in the Google Cloud CLI and Cloud Key Management Service API)
  • External_VPC (EXTERNAL_VPC in the Google Cloud CLI and Cloud Key Management Service API)

Although the protection level is a property of a key version, it cannot be changed after the key is created.

Algorithm

A key version's algorithm determines how the key material is created and the parameters required for cryptographic operations. Symmetric and asymmetric keys support different algorithms.

If you do not specify an algorithm when creating a new key version, the algorithm from 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 does not encrypt to the same ciphertext.

Key rings

A key ring organizes keys in a specific Google Cloud location and allows you to manage access control on groups of keys. A key ring's name does not need to be unique across a Google Cloud project, but must be unique within a given location. After creation, a key ring cannot be deleted. Key rings do not incur storage costs.

EKM connections

An EKM connection is a Cloud KMS resource that organizes VPC connections to your on-premises EKMs in a specific Google Cloud location. An EKM connection allows you to connect to and use keys from an external key manager over a VPC network. After creation, an EKM connection cannot be deleted. EKM connections do not incur storage costs.

Retrieving a resource's ID

Some API calls and gcloud CLI might require you to refer to a key ring, key, or key version by its resource ID, which is a string representing the fully-qualified CryptoKeyVersion name. Resource IDs are hierarchical, similar to a filesystem path. A key's resource ID also contains information about the key ring and location.

Object Resource Id format
Key ring projects/project-id/locations/location/keyRings/keyring
Key projects/project-id/locations/location/keyRings/keyring/cryptoKeys/key
Key version projects/project-id/locations/location/keyRings/keyring/cryptoKeys/key/cryptoKeyVersions/version
EKM connection projects/project-id/locations/location/ekmConnections/ekmConnection

To learn more, see Getting a Cloud KMS resource ID.

Organizing resources

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

  • By environment, such as prod,test, and develop.
  • By work area, such as payroll or insurance_claims.
  • By data sensitivity or characteristics, such as unrestricted, restricted, confidential, top-secret.

Resource life cycles

Key rings, keys, and key versions cannot be deleted. This ensures that the resource identifier of a key version is unique and always points to the original key material for that key version unless it has been destroyed. You can store an unlimited number of key rings, enabled or disabled keys, and enabled, disabled, or destroyed key versions. For more information, see Pricing and Quotas.

To learn how to destroy or restore a key version, see Destroying and restoring key versions.

If you schedule the shutdown of a Google Cloud 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.

What's next