View a markdown version of this page

Criptografia do pacote de configuração - Base da Amazônia AgentCore
Como funcionaMonitorando o uso do KMS para pacotes de configuraçãoComportamento quando uma chave fica indisponível

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

Criptografia do pacote de configuração

Quando você especifica a kmsKeyArn em um pacote de configuração, o serviço criptografa as configurações dos componentes (solicitações do sistema, descrições de ferramentas e outros conteúdos de configuração) usando criptografia de envelope. Todos os outros metadados do pacote (nome, descrição, IDs de versão, carimbos de data e hora) permanecem criptografados com a chave de propriedade. AWS

Como funciona

A criptografia do pacote de configuração usa criptografia de envelope com credenciais do chamador. Quando você cria ou atualiza um pacote com umkmsKeyArn, o serviço usa suas credenciais (por meio de sessões de acesso antecipado) para gerar uma chave de criptografia de dados (DEK) do KMS. O serviço criptografa as configurações do componente localmente usando essa DEK e, em seguida, armazena a DEK criptografada AES-GCM junto com o pacote. Quando você recupera o pacote, o serviço descriptografa a DEK usando suas credenciais e descriptografa os componentes.

O chamador deve ter kms:GenerateDataKeykms:Decrypt,kms:DescribeKey, e kms:ReEncrypt* permissões na chave.

AgentCore as otimizações suportam somente chaves KMS de criptografia simétrica. A chave KMS deve estar na mesma AWS região do pacote de configuração.

Configurando permissões para usar uma chave KMS gerenciada pelo cliente

A política de chaves a seguir fornece as permissões mínimas necessárias para a criptografia do pacote de configuração. A política tem duas instruções:

  • AllowCallerAccess— Permite que o usuário ou a função do IAM valide a chave viaDescribeKey.

  • AllowCallerCryptoOps— Permite que o usuário ou a função do IAM gere chaves de dados, descriptografe e criptografe novamente (para rotação de chaves), de acordo com o contexto de criptografia.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:ReEncrypt*"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*"
        }
      }
    }
  ]
}

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

  • AllowCallerAccess— Concede kms:DescribeKey permissão à função do IAM para validação da chave na criação do pacote ou no momento da atualização. 111122223333Substitua pelo ID da sua conta e MyConfigBundleRole pela função ou usuário do IAM que gerencia os pacotes de configuração.

  • AllowCallerCryptoOps— Concede a função kms:GenerateDataKey e kms:ReEncrypt* as permissões do IAM, de acordo com o contexto de aws:bedrock-agentcore:configurationBundleArn criptografia. kms:Decrypt A kms:ReEncrypt* permissão é necessária para a rotação de chaves (alteração da chave KMS em um pacote existente). Substitua 111122223333MyConfigBundleRole,, e us-east-1 por seus valores. Para permitir o acesso a todos os pacotes de configuração em sua conta, use um curinga comStringLike:. arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*

Definindo o escopo do acesso à chave KMS gerenciada pelo cliente

Você pode usar o contexto de criptografia para reduzir o acesso à chave gerenciada pelo cliente. AgentCore as otimizações incluem o seguinte contexto de criptografia em todas as operações do KMS:

{
  "aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/bundle-id"
}

Você pode usar esse contexto de criptografia nas principais condições de política para restringir as operações do KMS a pacotes de configuração específicos, conforme mostrado na AllowCallerCryptoOps declaração no exemplo de política de chaves acima.

Criação de um pacote de configuração com uma chave KMS gerenciada pelo cliente

Para criptografar um pacote de configuração, especifique o kmsKeyArn parâmetro ao chamar. CreateConfigurationBundle

exemplo
AWS CLI
aws bedrock-agentcore-control create-configuration-bundle \
  --bundle-name "MyEncryptedBundle" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --components '{
    "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent": {
      "configuration": {
        "systemPrompt": "You are a helpful assistant.",
        "modelId": "anthropic.claude-3-sonnet"
      }
    }
  }'
Python (Boto3)
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_configuration_bundle(
    bundleName='MyEncryptedBundle',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    components={
        'arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent': {
            'configuration': {
                'systemPrompt': 'You are a helpful assistant.',
                'modelId': 'anthropic.claude-3-sonnet'
            }
        }
    }
)

print(f"Bundle ID: {response['bundleId']}")

Alterando a configuração de criptografia em um pacote existente

Você pode alterar a configuração de criptografia em um pacote existente usando UpdateConfigurationBundle:

  • Adicionar criptografia — Especifique a kmsKeyArn em um pacote que foi criado sem uma. O serviço gera uma nova DEK e criptografa as configurações dos componentes.

  • Tecla de rotação — especifique uma diferentekmsKeyArn. O serviço reempacota a DEK existente da chave antiga para a nova chave usando. kms:ReEncrypt O chamador deve ter permissões em ambas as teclas. Se a chave antiga não estiver disponível (desativada, excluída ou sem permissões), a atualização falhará.

nota

Você não pode remover a criptografia de chave gerenciada pelo cliente de um pacote de configuração depois que ela for adicionada.

Monitorando o uso do KMS para pacotes de configuração

Os seguintes nomes de CloudTrail eventos aparecem para operações KMS do pacote de configuração:

  • GenerateDataKey— ao criar um pacote com uma chave gerenciada pelo cliente ou adicionar criptografia a um pacote existente. O encryptionContext campo contémaws:bedrock-agentcore:configurationBundleArn.

  • Decrypt— Ao recuperar o conteúdo do pacote (GetConfigurationBundle, GetConfigurationBundleVersion) ou ao atualizar um pacote criptografado.

  • ReEncrypt— Ao girar a chave KMS em um pacote existente via. UpdateConfigurationBundle

  • DescribeKey— Ao validar a chave na criação do pacote ou no momento da atualização.

Comportamento quando uma chave fica indisponível

Se você desativar ou excluir a chave KMS gerenciada pelo cliente usada por um pacote de configuração:

  • CreateConfigurationBundle— Falha na validação comValidationException.

  • UpdateConfigurationBundle— Falha porque o serviço não consegue descriptografar a DEK existente para criptografar novamente os novos componentes. A rotação de chaves também falha porque a chave antiga não está disponível para reempacotamento.

  • GetConfigurationBundle / GetConfigurationBundleVersion— Falha porque o serviço não consegue descriptografar a DEK ou as configurações do componente.

  • ListConfigurationBundles / ListConfigurationBundleVersions— É bem-sucedido porque a listagem retorna somente metadados e não exige operações KMS.

  • DeleteConfigurationBundle— É bem-sucedida porque a exclusão não exige a descriptografia dos dados do pacote.

Para restaurar o acesso, reative a chave ou atualize a política de chaves para conceder as permissões necessárias.