Como 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. A chave de criptografia do Cloud KMS é uma chave de criptografia gerenciada pelo cliente, criada pelo Cloud KMS e gerenciada por você.

Para mais informações gerais sobre o Cloud KMS, consulte Cloud KMS.

Pré-requisitos

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

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

    Ativar a API

  2. Tenha permissões suficientes no 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 planeja criar novas chaves e keyrings de criptografia, deve ter permissão para cloudkms.keyRings.create e cloudkms.cryptoKey.create.

    • Se você planeja usar keyrings e chaves novas ou atuais, é preciso ter a permissão cloudkms.cryptoKey.setIamPolicy para as chaves que você usará para criptografia.

      Essa permissão possibilita conceder às contas 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.

  3. 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 no bucket. Consulte Como configurar ACLs para instruções sobre como fazer isso.

  4. Tenha um keyring do Cloud KMS e pelo menos uma chave dentro dele.

  5. Encontre o endereço de e-mail da conta de serviço associada ao projeto que contém seu bucket do Cloud Storage.

Como atribuir uma chave do Cloud KMS a uma conta de serviço

Para usar chaves de criptografia gerenciadas pelo cliente, conceda permissão à sua conta de serviço do Cloud Storage para utilizar a chave do Cloud KMS:

Console

  1. Abra o navegador de chaves do Cloud Key Management Service no Console do Google Cloud.
    Abrir o navegador de Chaves do Cloud KMS
  2. Clique no nome do keyring que contém a chave que você quer.

  3. Marque a caixa de seleção da chave.

    A guia Permissões fica disponível no painel da janela à direita.

  4. Na caixa de diálogo Adicionar membros, especifique o endereço de e-mail da conta de serviço do Cloud Storage a que você está concedendo acesso.

  5. Na lista suspensa Selecionar um papel, escolha Criptografador/descriptografador do Cloud KMS CryptoKey.

  6. Clique em Adicionar.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil kms authorize para conceder à conta de serviço associada ao seu 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 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 você quiser remover a permissão concedida, use a ferramenta de linha de comando gcloud 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#.


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.GetIamPolicy(resourceName);

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

        // Save the updated IAM policy.
        Policy result = client.SetIamPolicy(resourceName, 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.

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)
	}

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

Ver no GitHub (em inglês) 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 do Cloud Storage para Node.js.

Ver no GitHub (em inglês) 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 do Cloud Storage para PHP.

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

function iam_add_member_sample(
    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 do Cloud Storage para Python.

Ver no GitHub (em inglês) 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.

# 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

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "policy": {
        "bindings": {
          "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
          "members": "SERVICE_ACCOUNT_EMAIL_ADDRESS"
        },
      }
    }

    Em que SERVICE_ACCOUNT_EMAIL_ADDRESS é o endereço de e-mail associado à conta de serviço. Por exemplo, service-7550275089395@gs-project-accounts.iam.gserviceaccount.com.

  3. Use cURL para chamar a API Cloud KMS com uma solicitação POST setIamPolicy:

    curl -X POST --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo que você criou 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 uma conta de serviço. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Como usar chaves de criptografia padrão

Como adicionar ou alterar a chave padrão de um bucket

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

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abrir o navegador do Cloud Storage
  2. Selecione um bucket na lista de buckets.

  3. Na página de detalhes do bucket, clique na guia Configuração.

  4. Clique no ícone de lápis associado à entrada Tipo de criptografia.

  5. Se o bucket não estiver usando uma chave do Cloud KMS, selecione o botão de opção Chave gerenciada pelo cliente.

  6. No menu suspenso associado às chaves gerenciadas pelo cliente, selecione uma das chaves disponíveis.

  7. Clique em Salvar.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil kms encryption:

gsutil kms encryption -k KEY_RESOURCE gs://BUCKET_NAME

Em que:

  • 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.
  • 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++.

Ver no GitHub (em inglês) Feedback
namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& key_name) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().SetEncryption(
                       gcs::BucketEncryption{key_name}));
  if (!updated) throw std::runtime_error(updated.status().message());

  if (!updated->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated->name()
              << " was sucessful, but the encryption is not set."
              << "This is unexpected, maybe a concurrent change?\n";
    return;
  }

  std::cout << "Successfully set default KMS key on bucket "
            << updated->name() << " to "
            << updated->encryption().default_kms_key_name << "."
            << "\nFull metadata: " << *updated << "\n";
}

C#

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

private void AddBucketDefaultKmsKey(string bucketName,
    string keyLocation, string kmsKeyRing, string kmsKeyName)
{
    string KeyPrefix = $"projects/{s_projectId}/locations/{keyLocation}";
    string FullKeyringName = $"{KeyPrefix}/keyRings/{kmsKeyRing}";
    string FullKeyName = $"{FullKeyringName}/cryptoKeys/{kmsKeyName}";
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName, new GetBucketOptions()
    {
        Projection = Projection.Full
    });
    bucket.Encryption = new Bucket.EncryptionData
    {
        DefaultKmsKeyName = FullKeyName
    };
    var updatedBucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration,
    });
}

Go

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

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// setBucketDefaultKMSKey sets the Cloud KMS encryption key for the bucket.
func setBucketDefaultKMSKey(w io.Writer, bucketName, keyName string) error {
	// bucketName := "bucket-name"
	// keyName := "key"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		Encryption: &storage.BucketEncryption{DefaultKMSKeyName: keyName},
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Default KMS Key Name: %v", bucketAttrsToUpdate.Encryption.DefaultKMSKeyName)
	return nil
}

Java

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

Ver no GitHub (em inglês) Feedback
// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of the existing bucket to set a default KMS key for, e.g. "my-bucket"
// String bucketName = "my-bucket"

// The name of the KMS-key to use as a default
// Key names are provided in the following format:
// 'projects/<PROJECT>/locations/<LOCATION>/keyRings/<RING_NAME>/cryptoKeys/<KEY_NAME>'
// String kmsKeyName = ""

BucketInfo bucketInfo =
    BucketInfo.newBuilder(bucketName).setDefaultKmsKeyName(kmsKeyName).build();

Bucket bucket = storage.update(bucketInfo);

System.out.println("Default KMS Key Name: " + bucket.getDefaultKmsKeyName());

Node.js

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

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const defaultKmsKeyName = 'KMS key resource id, e.g. my-key';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableDefaultKMSKey() {
  await storage.bucket(bucketName).setMetadata({
    encryption: {
      defaultKmsKeyName,
    },
  });

  console.log(
    `Default KMS key for ${bucketName} was set to ${defaultKmsKeyName}.`
  );
}

enableDefaultKMSKey().catch(console.error);

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Enable a bucket's requesterpays metadata.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName Name of your Google Cloud Storage bucket.
 * @param string $kmsKeyName KMS key ID to use as the default KMS key.
 *
 * @return void
 */
function enable_default_kms_key($projectId, $bucketName, $kmsKeyName)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'encryption' => [
            'defaultKmsKeyName' => $kmsKeyName
        ]
    ]);
    printf('Default KMS key for %s was set to %s' . PHP_EOL,
        $bucketName,
        $bucket->info()['encryption']['defaultKmsKeyName']);
}

Python

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

Ver no GitHub (em inglês) Feedback
from google.cloud import storage

def enable_default_kms_key(bucket_name, kms_key_name):
    """Sets a bucket's default KMS key."""
    # bucket_name = "your-bucket-name"
    # kms_key_name = "projects/PROJ/locations/LOC/keyRings/RING/cryptoKey/KEY"

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    bucket.default_kms_key_name = kms_key_name
    bucket.patch()

    print(
        "Set default KMS key for bucket {} to {}.".format(
            bucket.name, bucket.default_kms_key_name
        )
    )

Ruby

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

# bucket_name     = "Name of your Google Cloud Storage bucket"
# default_kms_key = "KMS key resource id"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_kms_key = default_kms_key

puts "Default KMS key for #{bucket.name} was set to #{bucket.default_kms_key}"

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "encryption": {
        "defaultKmsKeyName": "KEY_RESOURCE"
      }
    }

    Em que 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.

  3. Use cURL para chamar a API JSON com uma solicitação de bucket PATCH:

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"

    Em que:

    • JSON_FILE_NAME é o arquivo criado na Etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

API XML

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .xml com as informações a seguir:

    <EncryptionConfiguration>
      <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName>
    </EncryptionConfiguration>

    Em que 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.

  3. Use cURL para chamar a API XML com uma solicitação de bucket PUT e um parâmetro de string de consulta encryption:

    curl -X PUT --data-binary @XML_FILE_NAME.xml \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"

    Em que:

    • XML_FILE_NAME é o arquivo criado na Etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Como visualizar a chave padrão de um bucket

Para visualizar a chave do Cloud KMS definida como padrão no bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abrir o navegador do Cloud Storage
  2. Selecione um bucket na lista de buckets.

  3. Na página de detalhes do bucket, clique na guia Configuração.

  4. A chave padrão atual do seu bucket aparece no campo Chave de criptografia.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil kms encryption:

gsutil kms encryption gs://BUCKET_NAME

Em que BUCKET_NAME é o nome do bucket com a chave que você quer visualizar. Por exemplo, my-bucket.

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

Default encryption key for gs://my-bucket:
KEY_RESOURCE

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API JSON com uma solicitação de bucket GET que inclui o fields desejado:

    curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket com a chave que você quer visualizar. Por exemplo, my-bucket.

    A resposta terá esta aparência:

    {
      "encryption" : {
         "defaultKmsKeyName": "KEY_RESOURCE"
       },
    }

API XML

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API XML com uma solicitação de bucket GET que inclua o parâmetro de consulta encryption:

    curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket com a chave que você quer visualizar. Por exemplo, my-bucket.

    A resposta terá esta aparência:

    <EncryptionConfiguration>
      <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName>
    </EncryptionConfiguration>

Como remover a chave padrão de um bucket

Para remover qualquer conjunto de chaves padrão do Cloud KMS em um bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abrir o navegador do Cloud Storage
  2. Selecione um bucket na lista de buckets.

  3. Na página de detalhes do bucket, clique na guia Configuração.

  4. Clique no ícone de lápis associado à entrada Tipo de criptografia.

  5. Selecione o botão de opção Chave gerenciada pelo Google.

  6. Clique em Salvar.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil kms encryption:

gsutil kms encryption -d gs://BUCKET_NAME

em que BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

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

Clearing default encryption key for 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++.

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().ResetEncryption());
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "Successfully removed default KMS key on bucket "
            << updated->name() << "\n";
}

Java

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

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveBucketDefaultKMSKey {
  public static void removeBucketDefaultKmsKey(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setDefaultKmsKeyName(null).build().update();

    System.out.println("Default KMS key was removed from " + bucketName);
  }
}

Python

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

from google.cloud import storage

def bucket_delete_default_kms_key(bucket_name):
    """Delete a default KMS key of bucket"""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.default_kms_key_name = None
    bucket.patch()

    print("Default KMS key was removed from {}".format(bucket.name))
    return bucket

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "encryption": {
        "defaultKmsKeyName": null
      }
    }
  3. Use cURL para chamar a API JSON com uma solicitação de bucket PATCH:

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"

    Em que:

    • JSON_FILE_NAME é o arquivo criado na Etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

API XML

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .xml com as informações a seguir:

    <EncryptionConfiguration></EncryptionConfiguration>
  3. Use cURL para chamar a API XML com uma solicitação de bucket PUT e o parâmetro de string de consulta encryption:

    curl -X PUT --data-binary @XML_FILE_NAME.xml \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"

    Em que:

    • XML_FILE_NAME é o arquivo criado na Etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Como criptografar um objeto com uma chave do Cloud KMS

Você pode criptografar um objeto individual com uma chave do Cloud KMS. Isso é útil se você quiser usar uma chave diferente do conjunto de chaves padrão no bucket ou se ele não tiver um conjunto de chaves padrão.

Console

O Console do Cloud não pode ser usado para criptografar objetos individuais. Use a gsutil ou as bibliotecas de cliente.

gsutil

  1. Adicione a seguinte opção à seção [GSUtil] do arquivo de configuração .boto:

    encryption_key = KEY_RESOURCE

    Em que 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.

  2. Grave um objeto no bucket como faria normalmente, por exemplo, com gsutil cp ou gsutil rewrite.

Amostras de código

C++

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

Ver no GitHub (em inglês) Feedback
namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& old_csek_key_base64,
   std::string const& new_cmek_key_name) {
  StatusOr<gcs::ObjectMetadata> metadata = client.RewriteObjectBlocking(
      bucket_name, object_name, bucket_name, object_name,
      gcs::SourceEncryptionKey::FromBase64Key(old_csek_key_base64),
      gcs::DestinationKmsKeyName(new_cmek_key_name));
  if (!metadata) throw std::runtime_error(metadata.status().message());

  std::cout << "Changed object " << metadata->name() << " in bucket "
            << metadata->bucket()
            << " from using CSEK to CMEK key.\nFull Metadata: " << *metadata
            << "\n";
}

C#

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

        private void UploadEncryptedFileWithKmsKey(string bucketName,
            string keyLocation, string kmsKeyRing, string kmsKeyName,
            string localPath, string objectName = null)
        {
            string KeyPrefix = $"projects/{s_projectId}/locations/{keyLocation}";
            string FullKeyringName = $"{KeyPrefix}/keyRings/{kmsKeyRing}";
            string FullKeyName = $"{FullKeyringName}/cryptoKeys/{kmsKeyName}";

            var storage = StorageClient.Create();
            using (var f = File.OpenRead(localPath))
            {
                objectName = objectName ?? Path.GetFileName(localPath);
                storage.UploadObject(bucketName, objectName, null, f,
                    new UploadObjectOptions()
                    {
                        KmsKeyName = FullKeyName
                    });
                Console.WriteLine($"Uploaded {objectName}.");
            }
        }

Go

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

Ver no GitHub (em inglês) Feedback
import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// uploadWithKMSKey writes an object using Cloud KMS encryption.
func uploadWithKMSKey(w io.Writer, bucket, object, keyName string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// keyName := "projects/projectId/locations/global/keyRings/keyRingID/cryptoKeys/cryptoKeyID"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	obj := client.Bucket(bucket).Object(object)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	// Encrypt the object's contents.
	wc := obj.NewWriter(ctx)
	wc.KMSKeyName = keyName
	if _, err := wc.Write([]byte("top secret")); err != nil {
		return fmt.Errorf("Writer.Write: %v", err)
	}
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %v", err)
	}
	fmt.Fprintf(w, "Uploaded blob %v with KMS key.\n", object)
	return nil
}

Node.js

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

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'Local file to upload, e.g. ./local/path/to/file.txt';
// const kmsKeyName = 'KMS key resource id, e.g. my-key';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function uploadFileWithKmsKey() {
  // Uploads a local file to the bucket with the kms key
  await storage.bucket(bucketName).upload(filename, {
    kmsKeyName,
  });

  console.log(`${filename} uploaded to ${bucketName} using ${kmsKeyName}.`);
}

uploadFileWithKmsKey().catch(console.error);

PHP

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

use Google\Cloud\Storage\StorageClient;

/**
 * Upload a file using KMS encryption.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of the object.
 * @param string $source the path to the file to upload.
 * @param string $kmsKeyName KMS key ID used to encrypt objects server side.
 *
 * @return Psr\Http\Message\StreamInterface
 */
function upload_with_kms_key($projectId, $bucketName, $objectName, $source, $kmsKeyName)
{
    $storage = new StorageClient([
        'projectId' => $projectId,
    ]);
    $file = fopen($source, 'r');
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->upload($file, [
        'name' => $objectName,
        'destinationKmsKeyName' => $kmsKeyName,
    ]);
    printf('Uploaded %s to gs://%s/%s using encryption key %s' . PHP_EOL,
        basename($source),
        $bucketName,
        $objectName,
        $kmsKeyName);
}

Python

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

Ver no GitHub (em inglês) Feedback
from google.cloud import storage

def object_csek_to_cmek(bucket_name, blob_name, encryption_key, kms_key_name):
    """Change a blob's customer-supplied encryption key to KMS key"""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # encryption_key = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="
    # kms_key_name = "projects/PROJ/locations/LOC/keyRings/RING/cryptoKey/KEY"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    current_encryption_key = base64.b64decode(encryption_key)
    source_blob = bucket.blob(blob_name, encryption_key=current_encryption_key)

    destination_blob = bucket.blob(blob_name, kms_key_name=kms_key_name)
    token, rewritten, total = destination_blob.rewrite(source_blob)

    while token is not None:
        token, rewritten, total = destination_blob.rewrite(source_blob, token=token)

    print(
        "Blob {} in bucket {} is now managed by the KMS key {} instead of a customer-supplied encryption key".format(
            blob_name, bucket_name, kms_key_name
        )
    )
    return destination_blob

Ruby

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

# bucket_name       = "Your Google Cloud Storage bucket name"
# local_file_path   = "Path to local file to upload"
# storage_file_path = "Path to store the file in Google Cloud Storage"
# kms_key           = "KMS key resource id"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket bucket_name

file = bucket.create_file local_file_path, storage_file_path,
                          kms_key: kms_key

puts "Uploaded #{file.name} and encrypted service side using #{file.kms_key}"

Java

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

Na amostra a seguir, um objeto é criptografado usando uma chave de criptografia gerenciada pelo cliente:

Ver no GitHub (em inglês) Feedback
byte[] data = "Hello, World!".getBytes(UTF_8);

// The name of the existing bucket to set a default KMS key for, e.g. "my-bucket"
// String bucketName = "my-bucket"

// The name of the KMS-key to use as a default
// Key names are provided in the following format:
// 'projects/<PROJECT>/locations/<LOCATION>/keyRings/<RING_NAME>/cryptoKeys/<KEY_NAME>'
// String kmsKeyName = ""

BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, data, BlobTargetOption.kmsKeyName(kmsKeyName));

O exemplo a seguir altera a chave usada para criptografar um objeto de uma chave de criptografia fornecida pelo cliente para uma gerenciada pelo cliente:

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ChangeObjectCSEKtoKMS {
  public static void changeObjectFromCSEKtoKMS(
      String projectId,
      String bucketName,
      String objectName,
      String decryptionKey,
      String kmsKeyName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The Base64 encoded decryption key, which should be the same key originally used to encrypt
    // the object
    // String decryptionKey = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=";

    // The name of the KMS key to manage this object with
    // String kmsKeyName =
    // "projects/your-project-id/locations/global/keyRings/your-key-ring/cryptoKeys/your-key";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    Storage.CopyRequest request =
        Storage.CopyRequest.newBuilder()
            .setSource(blobId)
            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(decryptionKey))
            .setTarget(blobId, Storage.BlobTargetOption.kmsKeyName(kmsKeyName))
            .build();
    storage.copy(request);

    System.out.println(
        "Object "
            + objectName
            + " in bucket "
            + bucketName
            + " is now managed by the KMS key "
            + kmsKeyName
            + " instead of a customer-supplied encryption key");
  }
}

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Adicione os dados do objeto ao corpo da solicitação.

  3. Use cURL para chamar a API JSON com uma solicitação de Objeto POST:

    curl -X POST --data-binary @OBJECT \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME&kmsKeyName=KEY_RESOURCE"

    Em que:

    • OBJECT é o caminho para o objeto do qual está sendo feito o upload. Por exemplo, Desktop/dog.png.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • OBJECT_CONTENT_TYPE é o tipo de conteúdo do objeto. Por exemplo, image/png.
    • BUCKET_NAME é o nome do bucket de upload do objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto do qual você está fazendo upload. Por exemplo, pets/dog.png.
    • 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

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Adicione os dados do objeto ao corpo da solicitação.

  3. Use cURL para chamar a API XML com uma solicitação de Objeto PUT:

    curl -X PUT --data-binary @OBJECT \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-encryption-kms-key-name: KEY_RESOURCE" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Em que:

    • OBJECT é o caminho para o objeto do qual está sendo feito o upload. Por exemplo, Desktop/dog.png.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • OBJECT_CONTENT_TYPE é o tipo de conteúdo do objeto. Por exemplo, image/png.
    • BUCKET_NAME é o nome do bucket de upload do objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto do qual você está fazendo upload. Por exemplo, pets/dog.png.
    • 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.

Como identificar a chave usada para criptografar um objeto

Para encontrar o nome da chave do Cloud KMS que foi usada para criptografar um objeto:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome daquele que contém o objeto que você quer.

    A página Detalhes do bucket será aberta, com a guia Objetos selecionada.

  3. Navegue até o objeto, que pode estar localizado em uma pasta.

  4. Na coluna Criptografia, passe o cursor do mouse sobre a entrada do objeto desejado.

    O nome da chave aparece no formato:

    LOCATION/KEY_RING_NAME/KEY_NAME/KEY_VERSION

gsutil

Use o comando gsutil stat:

gsutil stat gs://BUCKET_NAME/OBJECT_NAME

Em que:

  • BUCKET_NAME é o nome do bucket que contém o objeto criptografado. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto criptografado. Por exemplo, pets/dog.png.

Se bem-sucedida, a resposta conterá o nome da chave:

gs://my-bucket/pets/dog.png:
...
KMS key: projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
...

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API JSON com uma solicitação de Objeto GET:

    curl -X GET \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?fields=kmsKeyName"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket que contém o objeto criptografado. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto criptografado. Por exemplo, pets/dog.png.

API XML

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API XML com uma solicitação de Objeto GET:

    curl -X GET \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?encryption"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket que contém o objeto criptografado. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto criptografado. Por exemplo, pets/dog.png.

Como descriptografar um objeto

A descriptografia de um objeto criptografado com uma chave gerenciada pelo cliente ocorre automaticamente se a conta de serviço relevante tiver acesso à chave. Para mais informações, consulte Contas de serviço com chaves de criptografia gerenciadas pelo cliente.

A seguir