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

O Policy in AgentCore fornece criptografia por padrão para proteger 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 chaves KMS para Política em AgentCore

O Policy in AgentCore se integra ao AWS KMS para gerenciar as 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 AWS Key Management Service 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 de propriedade

O tipo de criptografia padrão. O Policy in AgentCore possui a chave sem custo adicional para você e criptografa os dados do recurso em repouso no momento da 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 na sua AWS conta. Você tem controle total sobre a chave KMS. AWS As cobranças do 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 chaves, 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ítica, o Policy in AgentCore criptografa o mecanismo de política 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 à 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 para 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 deve 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 a 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 doações 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 restringidas 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 de seu AWS Chave KMS para política em AgentCore

Para usar uma chave gerenciada pelo cliente com a Política em AgentCore, sua política de chaves do AWS KMS deve conceder permissões para sua AWS conta. Ao criar um mecanismo de política, use a Política em AgentCore chamadas kms:CreateGrant usando sua identidade por meio de uma sessão de acesso direto (FAS). Como resultado, a política de chaves deve conceder kms:CreateGrant e outras permissões necessárias ao responsável pela conta principal (não ao 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 da fonte

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

Quando a Policy in AgentCore executa operações do 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 doações em sua política de chaves para restringir o uso de chaves a solicitações provenientes 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 AgentCore a Policy in faça chamadas AWS KMS em seu nome por meio de concessões, se a conta de origem for a mesma da conta 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 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 especificados. Essa chave de condição se aplica às sessões de acesso direto (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, onde REGION é a AWS região em que seu mecanismo de política é 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 da 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 o 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 se adequar às 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 Policy in AgentCore para usar a chave para criptografia e descriptografia. Consulte Autorizando o uso de sua chave AWS KMS para a Política em AgentCore para obter as permissões necessárias.

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

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 seguintes limitações se aplicam à criptografia de chave gerenciada pelo cliente para mecanismos de políticas:

Solução de problemas

Esta seção descreve erros comuns relacionados a chaves gerenciadas 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 na política do IAM ou na política de chaves do AWS KMS, ou que a chave 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 que está sendo 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.