Como usar chaves de criptografia gerenciadas pelo cliente

Nesta página, você verá como usar uma chave de criptografia do Cloud Key Management Service com o Cloud Storage, incluindo os primeiros passos no recurso, como usar chaves padrão em intervalos e como adicionar 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 ver detalhes sobre esse recurso, incluindo os países em que ele está disponível, consulte Chaves de criptografia gerenciadas pelo cliente. Para ver outras opções de criptografia no Cloud Storage, consulte Opções de criptografia de dados.

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.

     Com ela, você pode 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 roles/cloudkms.admin.

     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 intervalo do Cloud Storage:

   • Se você é proprietário do projeto que contém o intervalo, é 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 intervalo e a permissão storage.objects.get para ler objetos do intervalo. Consulte Como usar permissões do IAM para instruções sobre como conseguir um papel, por exemplo, roles/storage.objectAdmin, com essas permissões.

   • Para usar ACLs, é necessário ter a permissão WRITER no escopo do intervalo para gravar objetos e a permissão READER no escopo de objetos para ler objetos no intervalo. 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.

   Observação: você precisa criar a chave do Cloud KMS no mesmo local dos dados que pretende criptografar. Para conhecer os locais disponíveis do Cloud KMS, consulte Locais do Cloud KMS.
5. Observação: a etapa seguinte não é necessária ao usar a ferramenta gsutil.

   Encontre o endereço de e-mail da conta de serviço associada ao projeto que contém seu intervalo 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 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.

gsutil

Use o comando gsutil kms authorize para conceder à conta de serviço associada ao seu intervalo 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# (em inglês).

Ver no GitHub Feedback

        public static void AddMemberToCryptoKeyPolicy(string projectId, string locationId,
            string keyRingId, string cryptoKeyId, string role, string member)
        {
            KeyManagementServiceClient client = KeyManagementServiceClient.Create();
            CryptoKeyName cryptoKeyName =
                new CryptoKeyName(projectId, locationId, keyRingId, cryptoKeyId);

            Policy policy = client.GetIamPolicy(KeyNameOneof.From(cryptoKeyName));
            policy.Bindings.Add(new Binding
            {
                Role = role,
                Members = { member }
            });

            Policy updateResult = client.SetIamPolicy(KeyNameOneof.From(cryptoKeyName), policy);

            foreach (Binding bindingResult in updateResult.Bindings)
            {
                Console.WriteLine($"Role: {bindingResult.Role}");
                foreach (string memberResult in bindingResult.Members)
                {
                    Console.WriteLine($"  Member: {memberResult}");
                }
            }
        }

Go

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

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/iam"
	cloudkms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// addMemberRingPolicy adds a new member to a specified IAM role for the key ring.
func addMemberRingPolicy(w io.Writer, keyRingName, member string, role iam.RoleName) error {
	// keyRingName := "projects/PROJECT_ID/locations/global/keyRings/RING_ID"
	// member := "[e-mail]"
	// role := iam.Viewer
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("cloudkms.NewKeyManagementClient: %v", err)
	}

	// Get the KeyRing.
	keyRingObj, err := client.GetKeyRing(ctx, &kmspb.GetKeyRingRequest{Name: keyRingName})
	if err != nil {
		return fmt.Errorf("GetKeyRing: %v", err)
	}
	// Get IAM Policy.
	handle := client.KeyRingIAM(keyRingObj)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("Policy: %v", err)
	}
	// Add Member.
	policy.Add(member, role)
	if err = handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("SetPolicy: %v", err)
	}
	fmt.Fprintf(w, "Added member %s to keyring policy.", member)
	return nil
}

Java

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

Ver no GitHub Feedback

/**
 * Adds the given member to the given key, with the given role.
 *
 * @param projectId The id of the project.
 * @param locationId The location id of the key.
 * @param keyRingId The id of the keyring.
 * @param cryptoKeyId The id of the crypto key.
 * @param member The member to add. Must be in the proper format, eg:
 *
 * allUsers user:$userEmail serviceAccount:$serviceAccountEmail
 *
 * See https://g.co/cloud/kms/docs/reference/rest/v1/Policy#binding for more details.
 * @param role Must be in one of the following formats: roles/[role]
 * organizations/[organizationId]/roles/[role] projects/[projectId]/roles/[role]
 *
 * See https://g.co/cloud/iam/docs/understanding-roles for available values for [role].
 */
public static Policy addMemberToCryptoKeyPolicy(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, String member,
    String role)
    throws IOException {

  // Create the Cloud KMS client.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey version
    String keyName = CryptoKeyName.format(projectId, locationId, keyRingId, cryptoKeyId);

    // Get the current IAM policy
    Policy iamPolicy = client.getIamPolicy(keyName);

    // Create a new binding with the selected role and member
    Binding newBinding = Binding.newBuilder()
        .setRole(role)
        .addMembers(member)
        .build();

    // Create a new IAM policy containing the existing settings plus the new binding.
    Policy newPolicy = Policy.newBuilder()
        .mergeFrom(iamPolicy)
        .addBindings(newBinding)
        .build();

    // Set the new IAM Policy.
    Policy policyResult = client.setIamPolicy(keyName, newPolicy);

    return policyResult;
  }
}

Node.js

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

Ver no GitHub Feedback

async function addMemberToCryptoKeyPolicy(
  projectId = 'your-project-id', // Your GCP Project Id
  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
  cryptoKeyId = 'my-key', // Name of the crypto key
  member = 'user:[e-mail]', // Member to add to the crypto key
  role = 'roles/viewer' // Role to give the member
) {
  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

  // The location of the crypto key's key ring
  const locationId = 'global';

  // Get the full path to the crypto key
  const resource = client.cryptoKeyPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId
  );

  // Gets the IAM policy of a crypto key
  const [result] = await client.getIamPolicy({resource});
  let policy = Object.assign({bindings: []}, result);
  const index = policy.bindings.findIndex(binding => binding.role === role);

  // Add the role/member combo to the policy
  const members = [];
  const binding = Object.assign({role, members}, policy.bindings[index]);
  if (index === -1) {
    policy.bindings.push(binding);
  }
  if (!binding.members.includes(member)) {
    binding.members.push(member);
  }

  // Adds the member/role combo to the policy of the crypto key
  [policy] = await client.setIamPolicy({resource, policy});
  console.log(
    `${member}/${role} combo added to policy for crypto key ${cryptoKeyId}.`
  );
  if (policy.bindings) {
    policy.bindings.forEach(binding => {
      if (binding.members && binding.members.length) {
        console.log(`${binding.role}:`);
        binding.members.forEach(member => {
          console.log(`  ${member}`);
        });
      }
    });
  } else {
    console.log(`Policy for crypto key ${cryptoKeyId} is empty.`);
  }
}

PHP

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

Ver no GitHub Feedback

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

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $locationId = 'The location ID of the crypto key. Can be "global", "us-west1", etc.';
// $keyRingId = 'The KMS key ring ID';
// $cryptoKeyId = 'The KMS key ID';
// $member = 'Must be in the format "user:$userEmail" or "serviceAccount:$serviceAccountEmail"';
// $role = 'Must be in the format "roles/$role", "organizations/$organizationId/roles/$role", or "projects/$projectId/roles/$role"';

$kms = new KeyManagementServiceClient();

// The resource name of the CryptoKey.
$cryptoKeyName = $kms->cryptoKeyName($projectId, $locationId, $keyRingId, $cryptoKeyId);

// Get the current IAM policy and add the new account to it.
$policy = $kms->getIamPolicy($cryptoKeyName);
$bindings = $policy->getBindings();
$bindings[] = new Binding([
    'members' => [$member],
    'role' => $role,
]);
$policy->setBindings($bindings);

// Set the new IAM Policy.
$kms->setIamPolicy($cryptoKeyName, $policy);

printf('Member %s added to policy for cryptoKey %s in keyRing %s' . PHP_EOL, $member, $cryptoKeyId, $keyRingId);

Python

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

Ver no GitHub Feedback

def add_member_to_crypto_key_policy(
        project_id, location_id, key_ring_id, crypto_key_id, member, role):
    """Adds a member with a given role to the Identity and Access Management
    (IAM) policy for a given CryptoKey associated with a KeyRing."""

    from google.cloud import kms_v1

    # Creates an API client for the KMS API.
    client = kms_v1.KeyManagementServiceClient()

    # The resource name of the CryptoKey.
    resource = client.crypto_key_path_path(project_id, location_id,
                                           key_ring_id, crypto_key_id)
    # Get the current IAM policy.
    policy = client.get_iam_policy(resource)

    # Add member
    policy.bindings.add(
        role=role,
        members=[member])

    # Update the IAM Policy.
    client.set_iam_policy(resource, policy)

    # Print results
    print('Member {} added with role {} to policy for CryptoKey {} \
           in KeyRing {}'.format(member, role, crypto_key_id, key_ring_id))

Ruby

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

Ver no GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# location_id = "The location of the key ring"
# key_ring_id = "The ID of the key ring"
# member      = "Member to add to the key ring policy"
# role        = "Role assignment for new member"

require "google/cloud/kms/v1"
CloudKMS = Google::Cloud::Kms::V1

# Initialize the client
client = CloudKMS::KeyManagementServiceClient.new

# The key ring to use
key_ring =
  CloudKMS::KeyManagementServiceClient.key_ring_path project_id, location_id, key_ring_id

# Get the current IAM policy
policy = client.get_iam_policy key_ring

# Add new member to current bindings
policy.bindings ||= []
policy.bindings << Google::Iam::V1::Binding.new(members: [member], role: role)

# Update IAM policy
client.set_iam_policy key_ring, policy

puts "Member #{member} added to policy for " +
     "key ring #{key_ring_id}"

APIs REST

API JSON

Observação: nessa tarefa, é usado um endpoint separado em comparação com a maioria das tarefas do Cloud Storage.

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, [e-mail].

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.

Cuidado: essa solicitação substitui qualquer política atual do IAM no recurso da chave.

Observação: pode haver um atraso considerável entre a atribuição do papel e a aplicação dele na sua conta de serviço. Para conceder essa permissão de forma programática, aguarde 30 segundos antes de configurar o Cloud Storage.

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 intervalo

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

Console

1. Abra o navegador do Cloud Storage no Console do Google Cloud.
   Abrir o navegador do Cloud Storage

2. Selecione um intervalo na lista de intervalos.

3. Clique em Editar intervalo na parte superior da página.

4. Na página "Editar intervalo", clique na opção Mostrar configurações avançadas.

5. Se o intervalo 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.

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 intervalo pertinente. Por exemplo, my-bucket.

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

Authorized service account [SERVICE_ACCOUNT_NAME] to use key:
[KEY_RESOURCE]

Amostras de código

C++

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

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string key_name) {
  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().SetEncryption(
                       gcs::BucketEncryption{key_name}));

  if (!updated_metadata) {
    throw std::runtime_error(updated_metadata.status().message());
  }

  if (!updated_metadata->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated_metadata->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_metadata->name() << " to "
            << updated_metadata->encryption().default_kms_key_name << "."
            << "\nFull metadata: " << *updated_metadata << "\n";
}

C#

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	Encryption: &storage.BucketEncryption{DefaultKMSKeyName: keyName},
}
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

Java

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

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

Ver no GitHub Feedback

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

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

/**
 * 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';

// Enables a default KMS key for the bucket
await storage.bucket(bucketName).setMetadata({
  encryption: {
    defaultKmsKeyName,
  },
});

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

PHP

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

Ver no GitHub Feedback

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 Cloud Storage para Python (em inglês).

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

Ver no GitHub Feedback

# project_id      = "Your Google Cloud project ID"
# 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 project_id: project_id
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 Intervalo 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 intervalo 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 Intervalo 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 intervalo pertinente. Por exemplo, my-bucket.

Observação: os objetos gravados em um intervalo antes da adição ou alteração da chave padrão permanecem criptografados com o método anterior.

Como visualizar a chave padrão de um intervalo

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

Console

1. Abra o navegador do Cloud Storage no Console do Google Cloud.
   Abrir o navegador do Cloud Storage

2. Selecione um intervalo na lista de intervalos.

3. Na página de detalhes do intervalo, clique na guia Visão geral.

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

gsutil

Use o comando gsutil kms encryption:

gsutil kms encryption gs://[BUCKET_NAME]

Em que [BUCKET_NAME] é o nome do intervalo cuja chave você quer visualizar. Por exemplo, my-bucket.

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

Default encryption key for gs://[BUCKET_NAME]:
[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 Intervalo 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 intervalo cuja chave 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 Intervalo GET que inclua o encryption parâmetro de consulta:

   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 intervalo cuja chave 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 intervalo

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

Console

1. Abra o navegador do Cloud Storage no Console do Google Cloud.
   Abrir o navegador do Cloud Storage

2. Selecione um intervalo na lista de intervalos.

3. Clique em Editar intervalo na parte superior da página.

4. Na página "Editar intervalo", clique na opção Mostrar configurações avançadas.

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

6. Clique em Salvar.

gsutil

Use o comando gsutil kms encryption:

gsutil kms encryption -d gs://[BUCKET_NAME]

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

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

Clearing default encryption key for gs://[BUCKET_NAME]...

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 Intervalo 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 intervalo 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 Intervalo 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 intervalo pertinente. Por exemplo, my-bucket.

Observação: os objetos que foram gravados em um intervalo antes da remoção da chave padrão e que a usaram permanecerão criptografados por ela.

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

   Observação: também é possível incluir essas informações em cada comando da gsutil usando a sinalização de nível superior -o: -o "GSUtil:encryption_key=[KEY_RESOURCE]".

2. Grave um objeto no intervalo 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++ (em inglês).

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string object_name,
   std::string kms_key_name) {
  gcs::ObjectWriteStream stream = client.WriteObject(
      bucket_name, object_name, gcs::KmsKeyName(kms_key_name));

  // Line numbers start at 1.
  for (int lineno = 1; lineno <= 10; ++lineno) {
    stream << lineno << ": placeholder text for CMEK example.\n";
  }

  stream.Close();

  StatusOr<gcs::ObjectMetadata> metadata = std::move(stream).metadata();

  if (!metadata) {
    throw std::runtime_error(metadata.status().message());
  }

  std::cout << "Successfully wrote to object " << metadata->name()
            << " its size is: " << metadata->size()
            << "\nFull metadata: " << *metadata << "\n";
}

C#

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

Ver no GitHub Feedback

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

Ver no GitHub Feedback

obj := client.Bucket(bucket).Object(object)
// Encrypt the object's contents
wc := obj.NewWriter(ctx)
wc.KMSKeyName = keyName
if _, err := wc.Write([]byte("top secret")); err != nil {
	return err
}
if err := wc.Close(); err != nil {
	return err
}

Java

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

Ver no GitHub 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));

Node.js

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

Ver no GitHub Feedback

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

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

/**
 * 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';

// 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}.`);

PHP

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

Ver no GitHub Feedback

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 Cloud Storage para Python (em inglês).

Ver no GitHub Feedback

from google.cloud import storage

def upload_blob_with_kms(
    bucket_name, source_file_name, destination_blob_name, kms_key_name
):
    """Uploads a file to the bucket, encrypting it with the given KMS key."""
    # bucket_name = "your-bucket-name"
    # source_file_name = "local/path/to/file"
    # destination_blob_name = "storage-object-name"
    # kms_key_name = "projects/PROJ/locations/LOC/keyRings/RING/cryptoKey/KEY"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name, kms_key_name=kms_key_name)
    blob.upload_from_filename(source_file_name)

    print(
        "File {} uploaded to {} with encryption key {}.".format(
            source_file_name, destination_blob_name, kms_key_name
        )
    )

Ruby

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

Ver no GitHub Feedback

# project_id        = "Your Google Cloud project ID"
# 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 project_id: project_id

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

APIs REST

API JSON

Observação: estas etapas se aplicam especificamente à inserção de objetos por meio da API JSON. É possível seguir um procedimento semelhante para compor ou regravar objetos com a 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 que você está fazendo 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 intervalo para o qual você está fazendo o 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

Observação: estas etapas se aplicam especificamente ao upload de objetos por meio da API XML. É possível seguir um procedimento semelhante para compor ou copiar objetos com a 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 que você está fazendo 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 intervalo para o qual você está fazendo o 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.
   Abrir o navegador do Cloud Storage

2. Navegue até o objeto que você quer no intervalo pertinente.

3. Na coluna Criptografia, passe o cursor do mouse sobre a entrada do objeto que você quer.

   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 intervalo 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://[BUCKET_NAME]/[OBJECT_NAME]:
...
KMS key: [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 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 intervalo 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 intervalo que contém o objeto criptografado. Por exemplo, my-bucket.
   • [OBJECT_NAME] é o nome do objeto criptografado. Por exemplo, pets/dog.png.

Observação: se o objeto tiver sido gravado com um método de criptografia diferente do Cloud KMS, não haverá informações associadas a esse campo de metadados.

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

• Saiba mais sobre as chaves de criptografia gerenciadas pelo cliente.
• Saiba mais sobre o Cloud Key Management Service.
• Saiba mais sobre as chaves de criptografia fornecidas pelo cliente.