Usar chaves de criptografia gerenciadas pelo cliente

Acessar conceitos

Nesta página, descrevemos como usar uma chave de criptografia do Cloud Key Management Service com o Cloud Storage, incluindo a configuração de chaves padrão em buckets e a adição de chaves a objetos individuais. Uma chave de criptografia do Cloud KMS é uma chave de criptografia gerenciada pelo cliente. Essas chaves são criadas e gerenciadas por meio do Cloud KMS e armazenadas como chaves de software, em um cluster do HSM ou externamente.

Pré-requisitos

Antes de usar este recurso no Cloud Storage, realize estas etapas:

Ative a API Cloud KMS para o projeto que armazenará as chaves de criptografia.

Ativar a API
Tenha permissões suficientes para o projeto que armazenará as chaves de criptografia:
- Se você é proprietário do projeto que armazenará as chaves, é provável que tenha a permissão necessária.
- Se planejar criar novas chaves e keyrings de criptografia, deverá ter permissão para cloudkms.keyRings.create e cloudkms.cryptoKeys.create.
- Se você planeja usar keyrings e chaves novas ou atuais, é preciso ter a permissão cloudkms.cryptoKeys.setIamPolicy para as chaves que você usará para criptografia.
  
  Essa permissão possibilita conceder aos agente de serviço do Cloud Storage o acesso a chaves do Cloud KMS.
- As permissões acima estão contidas no papel Administrador do Cloud KMS.
  
  Consulte Como usar IAM com o Cloud KMS para ver instruções sobre como receber esse ou outros papéis do Cloud KMS.
Tenha um keyring do Cloud KMS e pelo menos uma chave dentro dele.

Observação: é preciso criar a chave do Cloud KMS no mesmo local dos dados que pretende criptografar, mas a chave pode estar em um projeto diferente. Para conhecer os locais disponíveis do Cloud KMS, consulte Locais do Cloud KMS.
Tenha permissões suficientes para trabalhar com objetos no bucket do Cloud Storage:
- Se você é proprietário do projeto que contém o bucket, é provável que tenha a permissão necessária.
- Para usar o IAM, é necessário ter a permissão storage.objects.create para gravar objetos no bucket e a permissão storage.objects.get para ler objetos do bucket. Consulte Como usar permissões do IAM para ver instruções sobre como conseguir um papel, como Administrador de objetos do Storage, com essas permissões.
- Para usar ACLs, é necessário ter a permissão WRITER no escopo do bucket para gravar objetos e a permissão READER no escopo de objetos para ler objetos do bucket. Consulte Como configurar ACLs para instruções sobre como fazer isso.
Observação: a etapa seguinte não é necessária ao usar a ferramenta gsutil.

Encontre o endereço de e-mail do agente de serviço associado ao projeto que contém seu bucket do Cloud Storage. Ao executar esta etapa, você cria automaticamente o agente de serviço, se ele não existir.

Atribuir uma chave do Cloud KMS a um agente de serviço

Para usar chaves de criptografia gerenciadas pelo cliente, conceda ao agente de serviço do Cloud Storage associado à permissão do bucket o uso da chave do Cloud KMS:

Console

Abra o navegador de chaves do Cloud Key Management Service no Console do Google Cloud.
Abrir o navegador de Chaves do Cloud KMS
Clique no nome do keyring que contém a chave que você quer.
Marque a caixa de seleção da chave.

A guia Permissões fica disponível no painel da janela à direita.
Na caixa de diálogo Adicionar participantes, especifique o endereço de e-mail do agente de serviço do Cloud Storage a que você está concedendo acesso.
Na lista suspensa Selecionar um papel, escolha Criptografador/descriptografador do Cloud KMS CryptoKey.
Clique em Add.

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

Linha de comando

Use o comando gsutil kms authorize para conceder ao agente de serviço associado ao bucket permissão para criptografar e descriptografar objetos usando a chave do Cloud KMS:

gsutil kms authorize -p PROJECT_STORING_OBJECTS -k KEY_RESOURCE

Em que:

PROJECT_STORING_OBJECTS é o ID ou o número do projeto que contém os objetos que você quer criptografar ou descriptografar. Por exemplo, my-pet-project.
KEY_RESOURCE é o recurso de chave do Cloud KMS. Por exemplo, projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key.

Se quiser remover a permissão concedida, use a Google Cloud CLI ou o Console do Google Cloud.

Amostras de código

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Veja no GitHub Feedback


using Google.Cloud.Iam.V1;
using Google.Cloud.Kms.V1;

public class IamAddMemberSample
{
    public Policy IamAddMember(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      string member = "user:foo@example.com")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the resource name.
        CryptoKeyName resourceName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // The resource name could also be a key ring.
        // var resourceName = new KeyRingName(projectId, locationId, keyRingId);

        // Get the current IAM policy.
        Policy policy = client.IAMPolicyClient.GetIamPolicy(
            new GetIamPolicyRequest
            {
                ResourceAsResourceName = resourceName
            });

        // Add the member to the policy.
        policy.AddRoleMember("roles/cloudkms.cryptoKeyEncrypterDecrypter", member);

        // Save the updated IAM policy.
        Policy result = client.IAMPolicyClient.SetIamPolicy(
            new SetIamPolicyRequest
            {
                ResourceAsResourceName = resourceName,
                Policy = policy
            });

        // Return the resulting policy.
        return result;
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Veja no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
)

// iamAddMember adds a new IAM member to the Cloud KMS key
func iamAddMember(w io.Writer, name, member string) error {
	// NOTE: The resource name can be either a key or a key ring. If IAM
	// permissions are granted on the key ring, the permissions apply to all keys
	// in the key ring.
	//
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// member := "user:foo@example.com"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %v", err)
	}
	defer client.Close()

	// Get the current IAM policy.
	handle := client.ResourceIAM(name)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("failed to get IAM policy: %v", err)
	}

	// Grant the member permissions. This example grants permission to use the key
	// to encrypt data.
	policy.Add(member, "roles/cloudkms.cryptoKeyEncrypterDecrypter")
	if err := handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("failed to save policy: %v", err)
	}

	fmt.Fprintf(w, "Updated IAM policy for %s\n", name)
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Veja no GitHub Feedback

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class IamAddMember {

  public void iamAddMember() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String keyId = "my-key";
    String member = "user:foo@example.com";
    iamAddMember(projectId, locationId, keyRingId, keyId, member);
  }

  // Add the given IAM member to the key.
  public void iamAddMember(
      String projectId, String locationId, String keyRingId, String keyId, String member)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the key version name from the project, location, key ring, key,
      // and key version.
      CryptoKeyName resourceName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // The resource name could also be a key ring.
      // KeyRingName resourceName = KeyRingName.of(projectId, locationId, keyRingId);

      // Get the current policy.
      Policy policy = client.getIamPolicy(resourceName);

      // Create a new IAM binding for the member and role.
      Binding binding =
          Binding.newBuilder()
              .setRole("roles/cloudkms.cryptoKeyEncrypterDecrypter")
              .addMembers(member)
              .build();

      // Add the binding to the policy.
      Policy newPolicy = policy.toBuilder().addBindings(binding).build();

      client.setIamPolicy(resourceName, newPolicy);
      System.out.printf("Updated IAM policy for %s%n", resourceName.toString());
    }
  }
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Veja no GitHub Feedback

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const keyId = 'my-key';
// const member = 'user:foo@example.com';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the resource name
const resourceName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  keyId
);

// The resource name could also be a key ring.
// const resourceName = client.keyRingPath(projectId, locationId, keyRingId);

async function iamAddMember() {
  // Get the current IAM policy.
  const [policy] = await client.getIamPolicy({
    resource: resourceName,
  });

  // Add the member to the policy.
  policy.bindings.push({
    role: 'roles/cloudkms.cryptoKeyEncrypterDecrypter',
    members: [member],
  });

  // Save the updated policy.
  const [updatedPolicy] = await client.setIamPolicy({
    resource: resourceName,
    policy: policy,
  });

  console.log('Updated policy');
  return updatedPolicy;
}

return iamAddMember();

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Veja no GitHub Feedback

use Google\Cloud\Iam\V1\Binding;
use Google\Cloud\Kms\V1\KeyManagementServiceClient;

function iam_add_member(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $member = 'user:foo@example.com'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the resource name.
    $resourceName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // The resource name could also be a key ring.
    // $resourceName = $client->keyRingName($projectId, $locationId, $keyRingId);

    // Get the current IAM policy.
    $policy = $client->getIamPolicy($resourceName);

    // Add the member to the policy.
    $bindings = $policy->getBindings();
    $bindings[] = (new Binding())
        ->setRole('roles/cloudkms.cryptoKeyEncrypterDecrypter')
        ->setMembers([$member]);
    $policy->setBindings($bindings);

    // Save the updated IAM policy.
    $updatedPolicy = $client->setIamPolicy($resourceName, $policy);
    printf('Added %s' . PHP_EOL, $member);

    return $updatedPolicy;
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Veja no GitHub Feedback

def iam_add_member(project_id, location_id, key_ring_id, key_id, member):
    """
    Add an IAM member to a resource.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        key_id (string): ID of the key to use (e.g. 'my-key').
        member (string): Member to add (e.g. 'user:foo@example.com')

    Returns:
        Policy: Updated Cloud IAM policy.

    """

    # Import the client library.
    from google.cloud import kms

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Build the resource name.
    resource_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # The resource name could also be a key ring.
    # resource_name = client.key_ring_path(project_id, location_id, key_ring_id);

    # Get the current policy.
    policy = client.get_iam_policy(request={'resource': resource_name})

    # Add the member to the policy.
    policy.bindings.add(
        role='roles/cloudkms.cryptoKeyEncrypterDecrypter',
        members=[member])

    # Save the updated IAM policy.
    request = {
        'resource': resource_name,
        'policy': policy
    }

    updated_policy = client.set_iam_policy(request=request)
    print('Added {} to {}'.format(member, resource_name))
    return updated_policy

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Veja no GitHub Feedback

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# member      = "user:foo@example.com"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the resource name.
resource_name = client.crypto_key_path project:    project_id,
                                       location:   location_id,
                                       key_ring:   key_ring_id,
                                       crypto_key: key_id

# The resource name could also be a key ring.
# resource_name = client.key_ring_path project: project_id, location: location_id, key_ring: key_ring_id

# Create the IAM client.
iam_client = Google::Cloud::Kms::V1::IAMPolicy::Client.new

# Get the current IAM policy.
policy = iam_client.get_iam_policy resource: resource_name

# Add the member to the policy.
policy.bindings << Google::Iam::V1::Binding.new(
  members: [member],
  role:    "roles/cloudkms.cryptoKeyEncrypterDecrypter"
)

# Save the updated policy.
updated_policy = iam_client.set_iam_policy resource: resource_name, policy: policy
puts "Added #{member}"

APIs REST

API JSON

Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth. Para ver instruções, consulte Autenticação de APIs.
Crie um arquivo JSON com as informações a seguir:
```
{
  "policy": {
    "bindings": {
      "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
      "members": "serviceAccount:SERVICE_AGENT_EMAIL_ADDRESS"
    },
  }
}
```
Em que SERVICE_AGENT_EMAIL_ADDRESS é o endereço de e-mail associado ao agente de serviço. Por exemplo, service-7550275089395@gs-project-accounts.iam.gserviceaccount.com.
Use cURL para chamar a API Cloud KMS com uma solicitação POST setIamPolicy:
```
curl -X POST --data-binary @JSON_FILE_NAME \
-H "Authorization: Bearer OAUTH2_TOKEN" \
-H "Content-Type: application/json" \
"https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"
```
Em que:
- JSON_FILE_NAME é o caminho para o arquivo JSON criado na Etapa 2.
- OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
- KEY_RESOURCE é o recurso de chave do Cloud KMS. Por exemplo, projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key.

API XML

Não é possível usar a API XML para atribuir um Cloud KMS a um agente de serviço. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Usar chaves de criptografia padrão

Configurar a chave padrão de um bucket

Para adicionar, alterar ou remover a chave do Cloud KMS que é usada por padrão quando os objetos são gravados em um bucket:

Console

No Console do Cloud, acesse a página Navegador do Cloud Storage.

Acessar o navegador
Selecione um bucket na lista de buckets.
Na página de detalhes do bucket, clique na guia Configuração.
Clique no ícone de lápis associado à entrada Tipo de criptografia.
Defina ou remova a chave padrão do Cloud KMS para o bucket.
1. Se o bucket não estiver usando uma chave do Cloud KMS, selecione o botão de opção Chave gerenciada pelo cliente e, em seguida, selecione uma das chaves disponíveis no menu suspenso associado.
2. Se o bucket atualmente usa uma chave do Cloud KMS, altere a chave do Cloud KMS no menu suspenso ou remova a chave do Cloud KMS selecionando o botão de opção chave gerenciada pelo Google.
Clique em Save.

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

Linha de comando

Use o comando gsutil kms encryption:

gsutil kms encryption STATE gs://BUCKET_NAME

Em que:

STATE é o estado desejado da chave padrão no bucket. Use um dos seguintes formatos:
- -k e um recurso de chave do Cloud KMS, se você quiser adicionar ou alterar uma chave padrão. Por exemplo, -k projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key.
- -d, se você quiser remover a chave padrão no bucket.
BUCKET_NAME é o nome do bucket relevante. Por exemplo, my-bucket.

Se bem-sucedida, a resposta terá esta aparência:

Setting default KMS key for bucket gs://my-bucket...

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

No exemplo a seguir, uma chave de criptografia padrão gerenciada pelo cliente é definida em um bucket:

Usar chaves de criptografia gerenciadas pelo cliente

Pré-requisitos

Atribuir uma chave do Cloud KMS a um agente de serviço

Console

Linha de comando

Amostras de código

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Usar chaves de criptografia padrão

Configurar a chave padrão de um bucket

Console

Linha de comando

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Visualizar a chave padrão de um bucket

Console

Linha de comando

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Criptografar um objeto com uma chave do Cloud KMS

Console

Linha de comando

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Fazer a rotação de uma chave fornecida pelo cliente para uma chave do Cloud KMS

Console

Linha de comando

Amostras de código

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

APIs REST

API JSON

API XML

Identificar a chave usada para criptografar um objeto

Console

Linha de comando