Cifre su motor AgentCore de políticas con una clave KMS administrada por el cliente

La política AgentCore proporciona el cifrado de forma predeterminada para proteger los datos confidenciales de los clientes en reposo mediante claves de cifrado AWS propias. Como capa adicional de protección, Policy in AgentCore le permite cifrar sus motores de políticas mediante AWS claves administradas por el cliente (CMK) del Servicio de administración de claves (AWS KMS). Esta funcionalidad garantiza la protección de los datos confidenciales mediante el cifrado en reposo, lo que le ayuda a:

En las siguientes secciones se explica cómo configurar el cifrado para los nuevos motores de políticas y cómo administrar las claves de cifrado.

AWS Tipos de claves de KMS para Policy en AgentCore

La política se AgentCore integra con AWS KMS para administrar las claves de cifrado utilizadas para cifrar y descifrar los datos de los clientes. Para obtener más información sobre los tipos y estados de las claves, consulte los conceptos del servicio de administración de AWS claves en la Guía para desarrolladores de AWS KMS. Al crear un nuevo motor de políticas, puede elegir entre los siguientes tipos de claves de AWS KMS para cifrar sus datos:

AWS clave propia

El tipo de cifrado predeterminado. Policy in AgentCore es el propietario de la clave sin coste adicional para usted y cifra los datos de los recursos en reposo en el momento de su creación. No es necesaria ninguna configuración adicional en el código o las aplicaciones para cifrar o descifrar los datos mediante la clave propiedad de Policy in. AgentCore No necesita ver, administrar, usar ni auditar estas claves. Para obtener más información, consulte las claves AWS propias en la Guía para desarrolladores de AWS KMS.

Clave administrada por el cliente

Tú creas, eres el propietario y administras la clave de tu AWS cuenta. Usted tiene el control total sobre la clave KMS. AWS Se aplican cargos de KMS a las claves administradas por el cliente. Para obtener más información, consulte la página de precios de AWS KMS. Para obtener más información sobre los tipos de claves, consulte las claves administradas por el cliente en la Guía para desarrolladores de AWS KMS.

Al especificar una clave gestionada por el cliente para el cifrado de un motor de políticas, Policy in AgentCore cifra el motor de políticas y todos sus recursos secundarios (políticas, generaciones de políticas) con esa clave. Para cifrar un motor de políticas mediante una clave administrada por el cliente, debe permitir el acceso a Policy in AgentCore en su política de claves. Una política de claves es una política basada en recursos que se adjunta a la clave gestionada por el cliente para controlar el acceso a la misma. Consulte Autorizar el uso de su clave AWS KMS para la política para obtener más información AgentCore.

Además, para crear un motor de políticas cifrado con una clave administrada por el cliente o para realizar llamadas a la API a un motor de políticas cifrado con una clave administrada por el cliente, el usuario o rol de IAM que realiza la llamada también debe tener acceso a la clave. Si Policy in no puede acceder a la clave, AgentCore se denegará cualquier decisión de autorización que implique recursos cifrados por esa clave. Si no tiene acceso a la clave, no podrá leer, actualizar ni eliminar los recursos cifrados por esa clave, y cualquier llamada creada para utilizarla con fines de cifrado fallará.

Utilización AWS KMS y claves de datos con la política incluida AgentCore

La función Política de AgentCore cifrado en reposo utiliza una clave KMS y una jerarquía de claves de datos para proteger los datos de sus recursos.

Policy in AgentCore utiliza un modelo basado en subvenciones para acceder a la clave gestionada por el cliente. Al crear un motor de políticas con una clave gestionada por el cliente, Policy in AgentCore lleva a cabo los siguientes pasos:

Las dos subvenciones tienen diferentes propósitos:

Ambas concesiones están limitadas por el contexto de cifrado que utiliza la claveaws:bedrock-agentcore-policy:policy-engine-arn, que vincula las concesiones al recurso específico del motor de políticas.

Al eliminar un motor de políticas con una clave gestionada por el cliente, Policy in retira AgentCore automáticamente ambas concesiones.

Autorizar el uso de su AWS Clave KMS para la política en AgentCore

Para usar una clave administrada por el cliente con la política incluida AgentCore, tu política de claves de AWS KMS debe conceder permisos a tu AWS cuenta. Al crear un motor de políticas, Policy In AgentCore kms:CreateGrant utiliza tu identidad a través de una sesión de acceso directo (FAS). Por lo tanto, la política clave debe conceder kms:CreateGrant los permisos necesarios al director de la cuenta (no al director del servicio) y utiliza kms:ViaService esta condición para garantizar que la clave solo se utilice a través de la política de entrada AgentCore.

Como mínimo, Policy in AgentCore exige los siguientes permisos en una clave gestionada por el cliente:

Comprender el contexto de la fuente

El contexto de origen proporciona información sobre la persona que llama de origen que intenta realizar acciones de AWS KMS contra una clave determinada. Esto evita la confusión o el uso indebido de los datos cifrados al vincular el contexto a la fuente de los datos.

Cuando Policy in AgentCore realiza operaciones de AWS KMS mediante subvenciones en su nombre, el contexto de origen identifica la política del AgentCore recurso que inició la solicitud. Puede utilizar el contexto de origen como condición adicional en las operaciones basadas en subvenciones en su política clave para restringir el uso de claves a las solicitudes que se originen en cuentas o recursos específicos.

Por ejemplo, puede añadir aws:SourceArn condiciones a las operaciones aws:SourceAccount y declaraciones de validación del KMS en su política clave para garantizar que estas operaciones solo se realicen correctamente cuando la solicitud se origine en su cuenta y en los recursos del motor 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/*"
    }
  }
}

Esta política clave permite AgentCore a Policy In realizar llamadas de AWS KMS en su nombre mediante subvenciones, si la cuenta de origen es la misma que la cuenta en la que reside la clave de KMS. Estos valores deben poder verificarse al comprobar los registros de CloudTrail auditoría de la clave de KMS. Para obtener más información sobre las claves de AWS condición globales, consulte Uso de claves de SourceAccount condición aws: SourceArn o aws: en la Guía para desarrolladores de AWS KMS.

Entendiendo kms: ViaService

La clave de kms:ViaService condición limita el uso de una clave KMS a las solicitudes de AWS servicios específicos. Esta clave de condición se aplica a las sesiones de acceso directo (FAS). Para obtener más informaciónkms:ViaService, consulte kms: ViaService en la Guía para desarrolladores de AWS KMS.

En la política clave, el kms:ViaService valor sigue el formatobedrock-agentcore.REGION.amazonaws.com, que REGION es la AWS región en la que se creó el motor de políticas (por ejemplo,bedrock-agentcore.us-east-1.amazonaws.com).

Comprender el contexto de cifrado

El contexto de cifrado es un conjunto de pares clave-valor que contienen datos autenticados adicionales para comprobar la integridad del cifrado. Al incluir un contexto de cifrado en una solicitud de cifrado de datos, AWS KMS vincula criptográficamente el contexto de cifrado a los datos cifrados. Para descifrar los datos, debe pasar el mismo contexto de cifrado. Para obtener más información, consulte el contexto de cifrado en la Guía para desarrolladores de AWS KMS.

Policy in AgentCore utiliza el siguiente contexto de cifrado en todas las operaciones criptográficas de AWS KMS y se puede verificar en CloudTrail los registros cuando Policy in AgentCore realiza llamadas de AWS KMS en su nombre para procesos de cifrado y descifrado:

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

Puede usar este contexto de cifrado en las condiciones de su política clave para restringir qué motores de políticas pueden usar la clave. Por ejemplo, la política de claves de la siguiente sección utiliza una kms:EncryptionContext condición para permitir que la clave se utilice únicamente para los recursos del motor de políticas.

Completado AWS Política de claves de KMS

Basándose en los conceptos de las secciones anteriores, el siguiente ejemplo de política de claves proporciona los permisos necesarios para cifrar un motor de políticas y utilizar un motor de políticas cifrado. La política contiene claves de condición para cumplir con las mejores prácticas de seguridad.

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

La política contiene las siguientes declaraciones:

Requisitos previos para cifrar su motor de políticas

Antes de cifrar el motor de políticas, asegúrese de cumplir los siguientes requisitos previos:

Para obtener más información sobre cómo controlar los permisos de IAM para una clave de KMS, consulte el acceso y los permisos de las claves de KMS en la Guía para desarrolladores de AWS KMS.

Creación de un motor de políticas cifradas

Antes de crear un motor de políticas de cifrado, asegúrese de que la clave administrada por el cliente que está utilizando tenga las declaraciones de política de claves adecuadas establecidas para AgentCore que la política utilice la clave para el cifrado y el descifrado. Consulte Autorizar el uso de la clave AWS KMS para ver los permisos necesarios en AgentCore Policy in.

Para cifrar el motor de políticas mediante la AWS CLI, incluya el --encryption-key-arn parámetro al enviar una create-policy-engine solicitud:

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"

La respuesta incluye el ARN y el estado del motor 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"
}

Limitaciones

Las siguientes limitaciones se aplican al cifrado de claves gestionado por el cliente para los motores de políticas:

Resolución de problemas

En esta sección se describen los errores más comunes relacionados con las claves gestionadas por el cliente que se pueden encontrar al utilizar AgentCore Policy in y se proporcionan los pasos necesarios para solucionarlos.

Acceso denegado: AWS Problema de permiso de KMS

Error: «Acceso denegado para la clave KMS especificada. Compruebe que la política de claves concede los permisos necesarios».

Esto podría significar que la persona que llama carece de los permisos de acción kms: * requeridos en su política de IAM o en su política de claves de AWS KMS, o que la clave a la que se hace referencia no existe o ya no existe.

Para resolver este problema:

Excepción de validación: AWS Configuración de claves de KMS

Error: «La clave de KMS especificada no está en un estado utilizable. Compruebe que la clave esté habilitada y que no esté pendiente de ser eliminada».

Esto significa que la clave a la que se hace referencia no se puede utilizar para el cifrado de claves gestionado por el cliente debido a su configuración actual. Algunas de las causas posibles son:

Para resolver este problema: compruebe que la clave cumpla los requisitos previos descritos en Requisitos previos para cifrar su motor de políticas.