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. 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:

Papel Nome Descrição Permissões Menor recurso
roles/cloudkms.admin Administrador do Cloud KMS Concede acesso total aos recursos do Cloud KMS, com exceção das operações de criptografia e descriptografia.
  • cloudkms.cryptoKeyVersions.create
  • cloudkms.cryptoKeyVersions.destroy
  • cloudkms.cryptoKeyVersions.get
  • cloudkms.cryptoKeyVersions.list
  • cloudkms.cryptoKeyVersions.restore
  • cloudkms.cryptoKeyVersions.update
  • cloudkms.cryptoKeys.*
  • cloudkms.importJobs.*
  • cloudkms.keyRings.*
  • resourcemanager.projects.get
CryptoKey
roles/cloudkms.cryptoKeyDecrypter Descriptografador de CryptoKey do Cloud KMS Permite usar os recursos do Cloud KMS apenas para operações de descriptografia.
  • cloudkms.cryptoKeyVersions.useToDecrypt
  • resourcemanager.projects.get
CryptoKey
roles/cloudkms.cryptoKeyEncrypter Criptografador de CryptoKey do Cloud KMS Permite usar os recursos do Cloud KMS apenas para operações de criptografia.
  • cloudkms.cryptoKeyVersions.useToEncrypt
  • resourcemanager.projects.get
CryptoKey
roles/cloudkms.cryptoKeyEncrypterDecrypter Criptografador/Descriptografador de CryptoKey do Cloud KMS Permite usar os recursos do Cloud KMS apenas para operações de criptografia e descriptografia.
  • cloudkms.cryptoKeyVersions.useToDecrypt
  • cloudkms.cryptoKeyVersions.useToEncrypt
  • resourcemanager.projects.get
CryptoKey
roles/cloudkms.importer Cloud KMS Importer Ativa as operações ImportCryptoKeyVersion, CreateImportJob, ListImportJobs e GetImportJob
  • cloudkms.importJobs.create
  • cloudkms.importJobs.get
  • cloudkms.importJobs.list
  • cloudkms.importJobs.useToImport
  • resourcemanager.projects.get
roles/cloudkms.publicKeyViewer Visualizador de chaves públicas de CryptoKey do Cloud KMS Permite operações GetPublicKey
  • cloudkms.cryptoKeyVersions.viewPublicKey
  • resourcemanager.projects.get
roles/cloudkms.signer Signatário de CryptoKey do Cloud KMS Ativa a operação AsymmetricSign
  • cloudkms.cryptoKeyVersions.useToSign
  • resourcemanager.projects.get
roles/cloudkms.signerVerifier Signatário/verificador de CryptoKey do Cloud KMS Ativa as operações AsymmetricSign e GetPublicKey
  • cloudkms.cryptoKeyVersions.useToSign
  • cloudkms.cryptoKeyVersions.viewPublicKey
  • 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.