Claude Platform Docs
AdministraçãoChaves de criptografia

Configurar o Google Cloud KMS para CMEK

Use o Google Cloud KMS para fornecer uma chave de criptografia para sua organização.

Configure with the /claude-api skill in Claude Code
claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"

Este guia explica como configurar uma chave do Google Cloud KMS como uma "customer-managed encryption key" (chave de criptografia gerenciada pelo cliente), ou CMEK, para sua organização Anthropic.

Pré-requisitos

  • Um projeto do Google Cloud com faturamento habilitado.
  • A Cloud KMS API habilitada (cloudkms.googleapis.com).
  • Permissões para criar key rings e chaves do KMS e para definir políticas de IAM neles (roles/cloudkms.admin ou equivalente).
  • Uma chave de API Admin da Anthropic para sua organização.
  • A CLI gcloud instalada e autenticada.
  • Logs de auditoria de acesso a dados (Data Access audit logs) do Cloud KMS habilitados para o projeto (IAM & Admin > Audit Logs > Cloud Key Management Service, com DATA_READ e DATA_WRITE). Eles ficam desativados por padrão; sem eles, as operações de criptografia e descriptografia da Anthropic não geram entradas no Cloud Logging.

E-mail da conta de serviço da Anthropic

Para que a Anthropic use sua chave de criptografia, você deve conceder à conta de serviço da Anthropic uma chave que ela possa usar para criptografar dados. O e-mail da conta de serviço para CMEK da Anthropic é:

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

Configuração da chave de criptografia

  1. Crie ou escolha um key ring

    Pule esta etapa se você já tiver um key ring para reutilizar. Key rings são regionais. Escolha uma localização de região única nos EUA, como us-east5, que corresponda à geografia da Anthropic que você está configurando. Localizações multirregionais como us e global não são suportadas.

    gcloud kms keyrings create <your-keyring-name> \
  --project=<your-project-id> \
  --location=<region>

  2. Crie a chave criptográfica

    Crie uma chave simétrica com a finalidade ENCRYPT_DECRYPT. A Anthropic recomenda fortemente a proteção por HSM: as chaves HSM do Cloud KMS são validadas pelo FIPS 140-2 Nível 3, e a diferença de custo em relação às chaves de software é pequena.

    gcloud kms keys create <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --purpose=encryption \
  --protection-level=hsm

    Para usar proteção por software, omita --protection-level=hsm. Nada mais neste guia muda.

    Você também pode criar a chave pelo Google Cloud Console. Abra o key ring, clique em Create key, selecione Generated key, defina a finalidade e o algoritmo como criptografia e descriptografia simétricas e escolha HSM em nível de proteção.

    Página Create key do Google Cloud KMS com nível de proteção HSM e finalidade Symmetric encrypt/decrypt.
    Crie uma chave simétrica de criptografia/descriptografia (Symmetric encrypt/decrypt) protegida por HSM.

  3. Conceda à conta de serviço da Anthropic acesso à chave

    São necessárias duas vinculações de IAM em nível de chave. Ambas têm escopo restrito à chave criptográfica individual, não ao projeto inteiro nem ao key ring inteiro.

    Criptografia e descriptografia, que a Anthropic usa para criptografar e descriptografar as chaves de dados que protegem os dados do seu workspace (criptografia de envelope):

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

    Viewer, para a leitura de metadados (cryptoKeys.get) que a Anthropic realiza na inicialização para validar a finalidade e o algoritmo da chave:

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.viewer

    No Console, selecione a chave, abra o painel Permissions, clique em Grant access e adicione a conta de serviço com as funções Cloud KMS CryptoKey Encrypter/Decrypter e Cloud KMS Viewer. Certifique-se de estar na página de permissões da chave, não do key ring ou do projeto, para que a concessão tenha escopo restrito apenas a esta chave.

    Caixa de diálogo Grant access com a conta de serviço da Anthropic atribuída às funções Cloud KMS CryptoKey Encrypter/Decrypter e Viewer.
    Conceda à conta de serviço da Anthropic ambas as funções (Grant access), com escopo restrito à chave.

  4. Anote o nome completo do recurso da chave

    Você passa isso para a Anthropic ao registrar a chave. O formato é:

    projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>

    Recupere-o com:

    gcloud kms keys describe <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --format="value(name)"

    No Console, abra a página de detalhes da chave e clique em Copy resource name.

    Detalhes do key ring no Google Cloud com a ação Copy resource name destacada no menu de ações da chave.
    Copie o nome completo do recurso da chave (Copy resource name) no menu de ações.

Registre a chave na Anthropic

A forma de registrar a chave depende de qual produto você usa.

  1. Registre a chave na Anthropic

    Crie uma configuração de chave externa por meio da Admin API, usando o nome do recurso da etapa Anote o nome completo do recurso da chave em Configuração da chave de criptografia.

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    display_name="<friendly-name>",
    geo="us",
    provider_config={
        "type": "gcp",
        "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
    },
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    A resposta contém o ID da chave externa:

    {
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

  2. Valide a chave

    Dispare um ciclo completo de criptografia e descriptografia com sua chave.

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    Uma resposta bem-sucedida tem esta aparência:

    { "type": "external_key_validation", "status": "success", "error": null }

    Se a validação falhar, as causas comuns são:

    • VPC Service Controls: se um perímetro de serviço protege o Cloud KMS no seu projeto, adicione a Anthropic a um nível de acesso no perímetro (ou exclua o projeto da chave) para que a Anthropic possa alcançar a chave.
    • Compartilhamento restrito por domínio: a política organizacional constraints/iam.allowedPolicyMemberDomains pode remover a vinculação da conta de serviço da Anthropic (veja a nota anterior). Confirme que a vinculação está presente com gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>.
    • Versão da chave desabilitada ou destruída: confirme que a versão primária da chave está habilitada, e não desabilitada, agendada para destruição ou destruída.

  3. Anexe a chave a um workspace

    Depois que a chave for validada, anexe-a a um novo workspace antes de enviar qualquer requisição a esse workspace. Para um workspace que já recebe requisições, a chave pode levar até um dia para entrar em vigor.

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Terraform

Para implantações de infraestrutura como código, as mesmas etapas correspondem ao provedor google com os recursos google_kms_key_ring, google_kms_crypto_key e google_kms_crypto_key_iam_member.

Was this page helpful?