As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Criptografe seu mecanismo de AgentCore políticas com uma chave KMS gerenciada pelo cliente

A política em AgentCore fornece criptografia por padrão para proteger os dados confidenciais do cliente em repouso usando chaves de criptografia AWS próprias. Como uma camada extra de proteção, o Policy in AgentCore permite que você criptografe seus mecanismos de políticas usando chaves gerenciadas pelo cliente (CMK) do AWS Key Management Service (AWS KMS). Essa funcionalidade garante a proteção de dados confidenciais por meio de criptografia em repouso, o que ajuda você a:

As seções a seguir explicam como configurar a criptografia para novos mecanismos de políticas e gerenciar suas chaves de criptografia.

AWS Tipos de chave KMS para política em AgentCore

A política AgentCore se integra ao AWS KMS para gerenciar chaves de criptografia usadas para criptografar e descriptografar dados do cliente. Para saber mais sobre os tipos e estados de chaves, consulte os conceitos do Serviço de Gerenciamento de AWS Chaves no Guia do Desenvolvedor do AWS KMS. Ao criar um novo mecanismo de política, você pode escolher entre os seguintes tipos de chave AWS KMS para criptografar seus dados:

AWS chave própria

O tipo de criptografia padrão. A Policy in AgentCore possui a chave sem nenhum custo adicional para você e criptografa os dados de recursos em repouso após a criação. Nenhuma configuração adicional é necessária em seu código ou aplicativos para criptografar ou descriptografar seus dados usando a chave de propriedade da Policy in. AgentCore Você não precisa visualizar, gerenciar, usar ou auditar essas chaves. Para obter mais informações, consulte chaves AWS próprias no Guia do desenvolvedor do AWS KMS.

Chave gerenciada pelo cliente

Você cria, possui e gerencia a chave em sua AWS conta. Você tem controle total sobre a chave KMS. AWS As cobranças de KMS se aplicam às chaves gerenciadas pelo cliente. Para obter mais informações, consulte a página de preços do AWS KMS. Para obter mais informações sobre os tipos de chave, consulte Chaves gerenciadas pelo cliente no Guia do desenvolvedor do AWS KMS.

Quando você especifica uma chave gerenciada pelo cliente para criptografia de um mecanismo de políticas, o Policy in AgentCore criptografa o mecanismo de políticas e todos os seus recursos secundários (políticas, gerações de políticas) com essa chave. Para criptografar um mecanismo de política usando uma chave gerenciada pelo cliente, você precisa conceder acesso à Política AgentCore em sua política de chaves. Uma política de chaves é uma política baseada em recursos que você anexa à sua chave gerenciada pelo cliente para controlar o acesso a ela. Consulte Autorizando o uso de sua chave AWS KMS para a Política em AgentCore para obter mais detalhes.

Além disso, para criar um mecanismo de política criptografado com uma chave gerenciada pelo cliente ou fazer chamadas de API para um mecanismo de política criptografado por uma chave gerenciada pelo cliente, o usuário ou a função do IAM que faz a chamada também precisa ter acesso à chave. Se o Policy in AgentCore não conseguir acessar a chave, qualquer decisão de autorização que envolva recursos criptografados por essa chave será negada. Quando você não tiver acesso à chave, não poderá ler, atualizar ou excluir recursos criptografados por essa chave, e qualquer chamada de criação para utilizar a chave para criptografia falhará.

Utilizar AWS KMS e chaves de dados com política em AgentCore

O recurso Política de AgentCore criptografia em repouso usa uma chave KMS e uma hierarquia de chaves de dados para proteger seus dados de recursos.

O Policy in AgentCore usa um modelo baseado em subsídios para acessar sua chave gerenciada pelo cliente. Quando você cria um mecanismo de política com uma chave gerenciada pelo cliente, o Policy in AgentCore executa as seguintes etapas:

Os dois subsídios têm propósitos diferentes:

Ambas as concessões são limitadas pelo contexto de criptografia usando a chaveaws:bedrock-agentcore-policy:policy-engine-arn, que vincula as concessões ao recurso específico do mecanismo de políticas.

Quando você exclui um mecanismo de política com uma chave gerenciada pelo cliente, o Policy in retira AgentCore automaticamente as duas concessões.

Autorizando o uso do seu AWS Chave KMS para política em AgentCore

Para usar uma chave gerenciada pelo cliente com a Política ativada AgentCore, sua política de chaves AWS KMS deve conceder permissões à sua AWS conta. Ao criar um mecanismo de política, a política em AgentCore chamadas kms:CreateGrant usando sua identidade por meio de uma Sessão de Acesso Avançado (FAS). Como resultado, a política de chaves deve conceder kms:CreateGrant qualquer outra permissão necessária ao responsável pela sua conta (não a um responsável pelo serviço) e usa a kms:ViaService condição para garantir que a chave seja usada somente por meio da Política em AgentCore.

No mínimo, o Policy in AgentCore exige as seguintes permissões em uma chave gerenciada pelo cliente:

Entendendo o contexto de origem

O contexto de origem fornece informações sobre a tentativa do chamador de origem de realizar ações de AWS KMS em uma determinada chave. Isso evita confusão ou uso indevido de dados criptografados ao vincular o contexto à fonte dos dados.

Quando o Policy in AgentCore executa operações de AWS KMS por meio de concessões em seu nome, o contexto de origem identifica a Política no AgentCore recurso que iniciou a solicitação. Você pode usar o contexto de origem como condições adicionais nas operações baseadas em subsídios em sua política de chaves para restringir o uso de chaves a solicitações originadas de contas ou recursos específicos.

Por exemplo, você pode adicionar aws:SourceArn condições às operações aws:SourceAccount e declarações de validação do KMS em sua política de chaves para garantir que essas operações sejam bem-sucedidas somente quando a solicitação for originada da sua conta e dos recursos do mecanismo de políticas:

{
  "Sid": "Allow Policy for KMS operations with source context",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:root"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
      "aws:SourceAccount": "111122223333"
    },
    "StringLike": {
      "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:policy-engine/*",
      "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
    }
  }
}

Essa política de chaves permite que o Policy in AgentCore faça chamadas AWS KMS em seu nome por meio de subsídios, se a conta de origem for a mesma em que essa chave KMS reside. Esses valores devem ser verificáveis ao verificar os registros de CloudTrail auditoria da chave KMS. Para obter mais informações sobre chaves de AWS condição globais, consulte Usando as chaves de SourceAccount condição aws: SourceArn ou aws: no Guia do desenvolvedor do AWS KMS.

Entendendo o kms: ViaService

A chave de kms:ViaService condição limita o uso de uma chave KMS às solicitações de AWS serviços específicos. Essa chave de condição se aplica às Sessões de Acesso Avançado (FAS). Para obter mais informações sobrekms:ViaService, consulte kms: ViaService no Guia do desenvolvedor do AWS KMS.

Na política principal, o kms:ViaService valor segue o formatobedrock-agentcore.REGION.amazonaws.com, em que REGION é a AWS região em que seu mecanismo de política foi criado (por exemplo,bedrock-agentcore.us-east-1.amazonaws.com).

Entendendo o contexto de criptografia

O contexto de criptografia é um conjunto de pares de valores-chave que contêm dados autenticados adicionais para verificações de integridade de criptografia. Quando você inclui um contexto de criptografia em uma solicitação para criptografar dados, o AWS KMS vincula criptograficamente o contexto de criptografia aos dados criptografados. Para descriptografar os dados, você deve passar pelo mesmo contexto de criptografia. Para obter mais informações, consulte Contexto de criptografia no Guia do desenvolvedor do AWS KMS.

O Policy in AgentCore usa o seguinte contexto de criptografia em todas as operações criptográficas do AWS KMS e pode ser verificado nos CloudTrail registros quando o Policy in AgentCore faz chamadas AWS KMS em seu nome para processos de criptografia e descriptografia:

{
  "aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:policy-engine/POLICY_ENGINE_ID"
}

Você pode usar esse contexto de criptografia em suas principais condições de política para restringir quais mecanismos de política podem usar a chave. Por exemplo, a política de chaves na seção a seguir usa uma kms:EncryptionContext condição para permitir que a chave seja usada somente para recursos do mecanismo de políticas.

Concluído AWS Política de chaves do KMS

Com base nos conceitos das seções anteriores, o exemplo de política de chaves a seguir fornece as permissões necessárias para criptografar um mecanismo de política e usar um mecanismo de política criptografado. A política contém chaves de condição para estar em conformidade com as melhores práticas de segurança.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Allow Policy to create grants",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
          "kms:GrantConstraintType": "EncryptionContextSubset"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        },
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Encrypt",
            "Decrypt",
            "GenerateDataKey",
            "GenerateDataKeyWithoutPlaintext",
            "ReEncryptFrom",
            "ReEncryptTo"
          ]
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS operations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS validation",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        }
      }
    }
  ]
}

A política contém as seguintes declarações:

Pré-requisitos para criptografar seu mecanismo de políticas

Antes de criptografar seu mecanismo de políticas, verifique se você atendeu aos seguintes pré-requisitos:

Para obter mais informações sobre como controlar as permissões do IAM para uma chave KMS, consulte Acesso e permissões da chave KMS no Guia do desenvolvedor do AWS KMS.

Criação de um mecanismo de política criptografado

Antes de criar um mecanismo de política criptografado, certifique-se de que a chave gerenciada pelo cliente que você está usando tenha as declarações de política de chaves adequadas definidas para que AgentCore a Policy in use a chave para criptografia e decodificação. Consulte Autorizando o uso de sua chave AWS KMS para Policy in AgentCore para obter as permissões necessárias.

Para criptografar seu mecanismo de política usando a AWS CLI, inclua o --encryption-key-arn parâmetro ao enviar uma solicitação: create-policy-engine

aws bedrock-agentcore-control create-policy-engine \
  --name "MyPolicyEngine" \
  --description "Policy engine with customer-managed encryption" \
  --encryption-key-arn "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"

A resposta inclui o ARN e o status do mecanismo de políticas:

{
  "policyEngineId": "MyPolicyEngine-abc123",
  "name": "MyPolicyEngine",
  "description": "Policy engine with customer-managed encryption",
  "policyEngineArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/MyPolicyEngine-abc123",
  "status": "CREATING",
  "statusReasons": [],
  "encryptionKeyArn": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
  "createdAt": "2026-02-24T12:00:00Z",
  "updatedAt": "2026-02-24T12:00:00Z"
}

Limitações

As limitações a seguir se aplicam à criptografia de chave gerenciada pelo cliente para mecanismos de políticas:

Solução de problemas

Esta seção descreve erros comuns relacionados à chave gerenciada pelo cliente que você pode encontrar ao usar o Policy in AgentCore e fornece etapas de solução de problemas para resolvê-los.

Acesso negado: AWS Problema de permissão do KMS

Erro: “Acesso negado para a chave KMS especificada. Verifique se a política de chaves concede as permissões necessárias.”

Isso pode significar que o chamador não tem as permissões de ação kms: * necessárias em sua política do IAM ou na política de chaves do AWS KMS, ou que a chave que está sendo referenciada não existe ou não existe mais.

Para resolver esse problema:

Exceção de validação: AWS Configuração da chave do KMS

Erro: “A chave KMS especificada não está em um estado utilizável. Verifique se a chave está ativada e não está pendente de exclusão.”

Isso significa que a chave referenciada não pode ser usada para criptografia de chave gerenciada pelo cliente devido à sua configuração atual. As possíveis causas incluem:

Para resolver esse problema: verifique se a chave atende aos pré-requisitos descritos em Pré-requisitos para criptografar seu mecanismo de políticas.