Permissions and roles

In Cloud KMS, resources are organized into a hierarchy. This hierarchy helps you manage and grant access to resources at various levels of granularity. Keys are contained within key rings, and key rings exist within a project. EKM connections also exist within a project. Projects can be further organized into folders or organizations.

This topic provides more details about the hierarchy of resources within Cloud KMS. To learn more about Google Cloud resources in general, see Resource hierarchy.

Resource hierarchy

The scope of an IAM role changes depending on the level of the resource hierarchy where the role is granted. This table shows the effective capabilities granted by the Cloud KMS CryptoKey Encrypter role (roles/cloudkms.cryptoKeyEncrypter) at different levels of the hierarchy.

You can manage access to keys or key rings, but not to individual key versions.

Resource hierarchy Capability
Organization Encrypt using all keys in all projects in the organization
Folder Encrypt using all keys in all projects in the folder
Project Encrypt using all keys in the project
Key ring Encrypt using all keys on the key ring
Key Encrypt using only that key

Security principles

IAM helps enforce the interrelated security principles of separation of duties and least privilege:

  • When you enforce the principle of separation of duties, no single member has all of the access required to complete a critical business function. For example, a bank teller can only withdraw funds from an account when the account holder is physically present and initiates the transaction.

  • When you enforce the principle of least privilege, a member has only the minimum level of access required to complete that member's specific business functions. For example, a bank teller is not automatically granted the ability to approve a customer loan.

Predefined roles

IAM provides predefined roles that grant access for each kind of Google Cloud resources. If no predefined role meets your needs, you can create a custom role.

IAM offers the following predefined roles for Cloud KMS:

Role Permissions

(roles/cloudkms.admin)

Provides access to Cloud KMS resources, except for access to restricted resource types and cryptographic operations.

Lowest-level resources where you can grant this role:

  • CryptoKey

cloudkms.autokeyConfigs.*

  • cloudkms.autokeyConfigs.get
  • cloudkms.autokeyConfigs.update

cloudkms.cryptoKeyVersions.create

cloudkms.cryptoKeyVersions.destroy

cloudkms.cryptoKeyVersions.get

cloudkms.cryptoKeyVersions.list

cloudkms.cryptoKeyVersions.restore

cloudkms.cryptoKeyVersions.update

cloudkms.cryptoKeyVersions.useToDecryptViaDelegation

cloudkms.cryptoKeyVersions.useToEncryptViaDelegation

cloudkms.cryptoKeys.*

  • cloudkms.cryptoKeys.create
  • cloudkms.cryptoKeys.get
  • cloudkms.cryptoKeys.getIamPolicy
  • cloudkms.cryptoKeys.list
  • cloudkms.cryptoKeys.setIamPolicy
  • cloudkms.cryptoKeys.update

cloudkms.ekmConfigs.*

  • cloudkms.ekmConfigs.get
  • cloudkms.ekmConfigs.getIamPolicy
  • cloudkms.ekmConfigs.setIamPolicy
  • cloudkms.ekmConfigs.update

cloudkms.ekmConnections.*

  • cloudkms.ekmConnections.create
  • cloudkms.ekmConnections.get
  • cloudkms.ekmConnections.getIamPolicy
  • cloudkms.ekmConnections.list
  • cloudkms.ekmConnections.setIamPolicy
  • cloudkms.ekmConnections.update
  • cloudkms.ekmConnections.use
  • cloudkms.ekmConnections.verifyConnectivity

cloudkms.importJobs.*

  • cloudkms.importJobs.create
  • cloudkms.importJobs.get
  • cloudkms.importJobs.getIamPolicy
  • cloudkms.importJobs.list
  • cloudkms.importJobs.setIamPolicy
  • cloudkms.importJobs.useToImport

cloudkms.keyHandles.*

  • cloudkms.keyHandles.create
  • cloudkms.keyHandles.get
  • cloudkms.keyHandles.list

cloudkms.keyRings.*

  • cloudkms.keyRings.create
  • cloudkms.keyRings.createTagBinding
  • cloudkms.keyRings.deleteTagBinding
  • cloudkms.keyRings.get
  • cloudkms.keyRings.getIamPolicy
  • cloudkms.keyRings.list
  • cloudkms.keyRings.listEffectiveTags
  • cloudkms.keyRings.listTagBindings
  • cloudkms.keyRings.setIamPolicy

cloudkms.locations.get

cloudkms.locations.list

cloudkms.locations.optOutKeyDeletionMsa

cloudkms.operations.get

cloudkms.projects.showEffectiveAutokeyConfig

resourcemanager.projects.get

(roles/cloudkms.autokeyAdmin)

Enables management of AutokeyConfig.

cloudkms.autokeyConfigs.*

  • cloudkms.autokeyConfigs.get
  • cloudkms.autokeyConfigs.update

cloudkms.projects.showEffectiveAutokeyConfig

(roles/cloudkms.autokeyUser)

Grants ability to use KeyHandle resources.

cloudkms.keyHandles.*

  • cloudkms.keyHandles.create
  • cloudkms.keyHandles.get
  • cloudkms.keyHandles.list

cloudkms.operations.get

cloudkms.projects.showEffectiveAutokeyConfig

(roles/cloudkms.cryptoKeyDecrypter)

Provides ability to use Cloud KMS resources for decrypt operations only.

Lowest-level resources where you can grant this role:

  • CryptoKey

cloudkms.cryptoKeyVersions.useToDecrypt

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.cryptoKeyDecrypterViaDelegation)

Enables Decrypt operations via other Google Cloud services

cloudkms.cryptoKeyVersions.useToDecryptViaDelegation

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.cryptoKeyEncrypter)

Provides ability to use Cloud KMS resources for encrypt operations only.

Lowest-level resources where you can grant this role:

  • CryptoKey

cloudkms.cryptoKeyVersions.useToEncrypt

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.cryptoKeyEncrypterDecrypter)

Provides ability to use Cloud KMS resources for encrypt and decrypt operations only.

Lowest-level resources where you can grant this role:

  • CryptoKey

cloudkms.cryptoKeyVersions.useToDecrypt

cloudkms.cryptoKeyVersions.useToEncrypt

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.cryptoKeyEncrypterDecrypterViaDelegation)

Enables Encrypt and Decrypt operations via other Google Cloud services

cloudkms.cryptoKeyVersions.useToDecryptViaDelegation

cloudkms.cryptoKeyVersions.useToEncryptViaDelegation

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.cryptoKeyEncrypterViaDelegation)

Enables Encrypt operations via other Google Cloud services

cloudkms.cryptoKeyVersions.useToEncryptViaDelegation

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.cryptoOperator)

Enables all Crypto Operations.

cloudkms.cryptoKeyVersions.useToDecrypt

cloudkms.cryptoKeyVersions.useToEncrypt

cloudkms.cryptoKeyVersions.useToSign

cloudkms.cryptoKeyVersions.useToVerify

cloudkms.cryptoKeyVersions.viewPublicKey

cloudkms.locations.generateRandomBytes

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.ekmConnectionsAdmin)

Enables management of EkmConnections.

cloudkms.ekmConfigs.get

cloudkms.ekmConfigs.update

cloudkms.ekmConnections.create

cloudkms.ekmConnections.get

cloudkms.ekmConnections.list

cloudkms.ekmConnections.update

cloudkms.ekmConnections.verifyConnectivity

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.expertRawAesCbc)

Enables raw AES-CBC keys management.

cloudkms.cryptoKeyVersions.manageRawAesCbcKeys

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.expertRawAesCtr)

Enables raw AES-CTR keys management.

cloudkms.cryptoKeyVersions.manageRawAesCtrKeys

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.expertRawPKCS1)

Enables raw PKCS#1 keys management.

cloudkms.cryptoKeyVersions.manageRawPKCS1Keys

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

resourcemanager.projects.list

(roles/cloudkms.importer)

Enables ImportCryptoKeyVersion, CreateImportJob, ListImportJobs, and GetImportJob operations

cloudkms.importJobs.create

cloudkms.importJobs.get

cloudkms.importJobs.list

cloudkms.importJobs.useToImport

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.protectedResourcesViewer)

Enables viewing protected resources.

cloudkms.protectedResources.search

(roles/cloudkms.publicKeyViewer)

Enables GetPublicKey operations

cloudkms.cryptoKeyVersions.viewPublicKey

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.signer)

Enables Sign operations

cloudkms.cryptoKeyVersions.useToSign

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.signerVerifier)

Enables Sign, Verify, and GetPublicKey operations

cloudkms.cryptoKeyVersions.useToSign

cloudkms.cryptoKeyVersions.useToVerify

cloudkms.cryptoKeyVersions.viewPublicKey

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.verifier)

Enables Verify and GetPublicKey operations

cloudkms.cryptoKeyVersions.useToVerify

cloudkms.cryptoKeyVersions.viewPublicKey

cloudkms.locations.get

cloudkms.locations.list

resourcemanager.projects.get

(roles/cloudkms.viewer)

Enables Get and List operations.

cloudkms.autokeyConfigs.get

cloudkms.cryptoKeyVersions.get

cloudkms.cryptoKeyVersions.list

cloudkms.cryptoKeys.get

cloudkms.cryptoKeys.list

cloudkms.ekmConfigs.get

cloudkms.ekmConnections.get

cloudkms.ekmConnections.list

cloudkms.importJobs.get

cloudkms.importJobs.list

cloudkms.keyHandles.get

cloudkms.keyHandles.list

cloudkms.keyRings.get

cloudkms.keyRings.list

cloudkms.locations.get

cloudkms.locations.list

cloudkms.operations.get

resourcemanager.projects.get

Custom roles

In addition to predefined roles, you can create custom roles. Custom roles allow you to enforce the principle of least privilege by granting the role the minimum permissions required to perform a given task.

A custom role includes one or more of the permissions listed in the IAM reference. Permissions related to the Cloud Key Management Service API begin with the string cloudkms. For more information, see Support levels for permissions in custom roles.

For information about the permissions required to invoke a specific Cloud Key Management Service API method, see that method's API reference.

General guidelines for managing access in Cloud KMS

We recommend that you avoid using basic project-wide roles like owner, editor, and viewer. These roles do not separate the ability to manage keys from the ability to use the keys for cryptographic operations, and are not recommended for production environments. Instead, use predefined roles or create custom roles that reflect your business requirements.

The following examples help illustrate some good security guidelines:

  • For a large or complex organization, you might decide on an approach like the following:

    • Grant members of your IT security team the Cloud KMS Admin role (roles/cloudkms.admin) across all projects. If different team members handle different aspects of a key's lifecycle, you can grant those team members a more granular role, like the Cloud KMS Importer role (roles/cloudkms.importer).
    • Grant the Cloud KMS Encrypter / Decrypter role (roles/cloudkms.cryptoKeyEncrypterDecrypter) to users or applications that read or write encrypted data.
    • Grant the Cloud KMS Public Key Viewer role (roles/cloudkms.publicKeyViewer) to users or applications that need to view the public portion of a key used for asymmetric encryption.
    • Create predefined roles that match your business requirements. For example, the same user might need to monitor a project's quotas and to view log data.

  • For a small organization with simple security requirements, you might choose to take a simpler approach by granting a broad role such as Organization Admin (roles/resourcemanager.organizationAdmin). However, this approach might not scale with your ongoing requirements.

  • Consider hosting your keys in a separate Google Cloud project from the data protected by those keys. A user with a basic or highly privileged role in one project, such as editor, cannot use this role to gain unauthorized access to keys in a different project.

  • Avoid granting the owner role to any member. Without the owner role, no member in the project can both create a key and use it to decrypt data or for signing, unless each of these permissions is granted to that member. To grant broad administrative access without granting the ability to encrypt or decrypt, grant the Cloud KMS Admin role (roles/cloudkms.admin) role instead.

  • To limit access to encrypted data, such as customer data, you can restrict who can access the key and who can use the key for decryption. If necessary, you can create granular custom roles to meet your business requirements.

Checking permissions

For each Cloud KMS object type for which you can set granular IAM permissions, that object has a testIamPermissions method. The testIamPermissions method returns the set of permissions the caller has been granted for that object.

You cannot set IAM permissions on a key version, so the CryptoKeyVersion object type does not have this method.

An object's testIamPermissions method returns a TestIamPermissionsResponse.

For examples of invoking testIamPermissions methods, see the documentation for testing permissions in the IAM documentation.

What's next

  • Learn how IAM centralizes management of permissions and access scopes for Google Cloud resources.
  • Understand the different types of Cloud KMS objects.