Chiffrez votre moteur de AgentCore politiques à l'aide d'une clé KMS gérée par le client

Policy in AgentCore fournit un chiffrement par défaut pour protéger les données sensibles des clients au repos à l'aide de clés de chiffrement AWS détenues. En tant que couche de protection supplémentaire, Policy in vous AgentCore permet de chiffrer vos moteurs de politiques à l'aide des AWS clés gérées par le client (CMK) du Key Management Service (AWS KMS). Cette fonctionnalité garantit la protection des données sensibles grâce au chiffrement au repos, ce qui vous permet de :

Les sections suivantes expliquent comment configurer le chiffrement pour les nouveaux moteurs de politiques et comment gérer vos clés de chiffrement.

AWS Types de clés KMS pour Policy in AgentCore

Policy in AgentCore s'intègre à AWS KMS pour gérer les clés de chiffrement utilisées pour chiffrer et déchiffrer les données des clients. Pour en savoir plus sur les types et les états des clés, consultez les concepts du service de gestion des AWS clés dans le guide du développeur AWS KMS. Lorsque vous créez un nouveau moteur de politiques, vous pouvez choisir parmi les types de clés AWS KMS suivants pour chiffrer vos données :

AWS clé possédée

Type de chiffrement par défaut. Policy in AgentCore détient la clé sans frais supplémentaires pour vous et chiffre les données des ressources au repos lors de leur création. Aucune configuration supplémentaire n'est requise dans votre code ou dans vos applications pour chiffrer ou déchiffrer vos données à l'aide de la clé détenue par Policy in. AgentCore Vous n'avez pas besoin de consulter, de gérer, d'utiliser ou d'auditer ces clés. Pour plus d'informations, consultez la section sur les clés AWS détenues dans le guide du développeur AWS KMS.

Clé gérée par le client

Vous créez, détenez et gérez la clé de votre AWS compte. Vous avez le contrôle total de la clé KMS. AWS Les frais KMS s'appliquent aux clés gérées par le client. Pour plus d'informations, consultez la page de tarification AWS KMS. Pour plus d'informations sur les types de clés, consultez la section Clés gérées par le client dans le guide du développeur AWS KMS.

Lorsque vous spécifiez une clé gérée par le client pour le chiffrement d'un moteur de politiques, Policy in AgentCore chiffre le moteur de politiques et toutes ses ressources dérivées (politiques, générations de politiques) avec cette clé. Pour chiffrer un moteur de politiques à l'aide d'une clé gérée par le client, vous devez autoriser l'accès à Policy AgentCore dans votre politique de clé. Une politique clé est une politique basée sur les ressources que vous associez à votre clé gérée par le client pour contrôler l'accès à celle-ci. Consultez Autoriser l'utilisation de votre clé AWS KMS pour Policy in AgentCore pour plus de détails.

En outre, pour créer un moteur de politique chiffré avec une clé gérée par le client, ou pour effectuer des appels d'API vers un moteur de politique chiffré par une clé gérée par le client, l'utilisateur ou le rôle IAM qui effectue l'appel doit également avoir accès à la clé. Si Policy in AgentCore ne parvient pas à accéder à la clé, toute décision d'autorisation impliquant des ressources chiffrées par cette clé sera refusée. Lorsque vous n'avez pas accès à la clé, vous ne pouvez pas lire, mettre à jour ou supprimer les ressources chiffrées par cette clé, et tout appel de création visant à utiliser la clé à des fins de chiffrement échouera.

Utilisation AWS KMS et clés de données avec politique intégrée AgentCore

La fonctionnalité Politique de AgentCore chiffrement au repos utilise une clé KMS et une hiérarchie de clés de données pour protéger les données de vos ressources.

Policy in AgentCore utilise un modèle basé sur les subventions pour accéder à votre clé gérée par le client. Lorsque vous créez un moteur de politiques avec une clé gérée par le client, Policy in AgentCore exécute les étapes suivantes :

Les deux subventions ont des objectifs différents :

Les deux autorisations sont limitées par le contexte de chiffrement utilisant la cléaws:bedrock-agentcore-policy:policy-engine-arn, qui lie les autorisations à la ressource spécifique du moteur de politiques.

Lorsque vous supprimez un moteur de politiques avec une clé gérée par le client, Policy in retire AgentCore automatiquement les deux autorisations.

Autoriser l'utilisation de votre AWS Clé KMS pour Policy in AgentCore

Pour utiliser une clé gérée par le client avec Policy in AgentCore, votre politique de clé AWS KMS doit accorder des autorisations à votre AWS compte. Lorsque vous créez un moteur de politiques, appliquez une politique dans AgentCore les appels kms:CreateGrant en utilisant votre identité via une session d'accès direct (FAS). Par conséquent, la politique des clés doit accorder les autres autorisations requises au principal de votre compte (kms:CreateGrantet non à un principal de service) et utilise kms:ViaService cette condition pour garantir que la clé est uniquement utilisée via Policy in AgentCore.

Policy in AgentCore nécessite au minimum les autorisations suivantes sur une clé gérée par le client :

Comprendre le contexte de la source

Le contexte source fournit des informations sur l'appelant source qui tente d'effectuer des actions AWS KMS sur une clé donnée. Cela permet d'éviter toute confusion ou toute utilisation abusive des données cryptées en liant le contexte à la source des données.

Lorsque Policy in AgentCore effectue des opérations AWS KMS par le biais de subventions en votre nom, le contexte source identifie la politique de la AgentCore ressource à l'origine de la demande. Vous pouvez utiliser le contexte source comme condition supplémentaire pour les opérations basées sur les subventions dans votre politique clé afin de limiter l'utilisation des clés aux demandes provenant de comptes ou de ressources spécifiques.

Par exemple, vous pouvez ajouter aws:SourceAccount des aws:SourceArn conditions aux opérations KMS et aux instructions de validation dans votre politique clé afin de garantir que ces opérations n'aboutissent que lorsque la demande provient de votre compte et des ressources de votre moteur de politiques :

{
  "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/*"
    }
  }
}

Cette politique clé permet AgentCore à Policy in de passer des appels AWS KMS en votre nom par le biais de subventions, si le compte source est le même que celui dans lequel réside cette clé KMS. Ces valeurs doivent être vérifiables lors de la CloudTrail vérification des journaux d'audit pour la clé KMS. Pour plus d'informations sur les clés de AWS condition globales, consultez la section Utilisation des clés de SourceAccount condition aws : SourceArn ou aws : dans le guide du développeur AWS KMS.

Compréhension des km : ViaService

La clé de kms:ViaService condition limite l'utilisation d'une clé KMS aux demandes provenant de AWS services spécifiques. Cette clé de condition s'applique aux sessions d'accès direct (FAS). Pour plus d'informations surkms:ViaService, voir kms : ViaService dans le guide du développeur AWS KMS.

Dans la politique clé, la kms:ViaService valeur suit le formatbedrock-agentcore.REGION.amazonaws.com, où se REGION trouve la AWS région dans laquelle votre moteur de politique est créé (par exemple,bedrock-agentcore.us-east-1.amazonaws.com).

Comprendre le contexte de chiffrement

Le contexte de chiffrement est un ensemble de paires clé-valeur qui contiennent des données authentifiées supplémentaires pour les contrôles d'intégrité du chiffrement. Lorsque vous incluez un contexte de chiffrement dans une demande de chiffrement de données, AWS KMS lie cryptographiquement le contexte de chiffrement aux données chiffrées. Pour déchiffrer les données, vous devez transmettre le même contexte de chiffrement. Pour plus d'informations, consultez la section Contexte du chiffrement dans le guide du développeur AWS KMS.

Policy in AgentCore utilise le contexte de chiffrement suivant dans toutes les opérations de chiffrement AWS KMS et peut être vérifié dans les CloudTrail journaux lorsque Policy in AgentCore effectue des appels AWS KMS en votre nom pour les processus de chiffrement et de déchiffrement :

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

Vous pouvez utiliser ce contexte de chiffrement dans vos conditions de politique de clé afin de limiter les moteurs de stratégie autorisés à utiliser la clé. Par exemple, la politique clé décrite dans la section suivante utilise une kms:EncryptionContext condition pour autoriser l'utilisation de la clé uniquement pour les ressources du moteur de politiques.

Complet AWS Politique de clé KMS

Sur la base des concepts décrits dans les sections précédentes, l'exemple de politique clé suivant fournit les autorisations nécessaires pour chiffrer un moteur de politique et utiliser un moteur de politique chiffré. La politique contient des clés de condition conformes aux meilleures pratiques de sécurité.

{
"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 politique contient les déclarations suivantes :

Conditions préalables au chiffrement de votre moteur de politiques

Avant de chiffrer votre moteur de politiques, assurez-vous de remplir les conditions préalables suivantes :

Pour plus d'informations sur le contrôle des autorisations IAM pour une clé KMS, consultez la section Accès aux clés KMS et autorisations dans le guide du développeur AWS KMS.

Création d'un moteur de politiques chiffré

Avant de créer un moteur de politique chiffré, assurez-vous que la clé gérée par le client que vous utilisez comporte les déclarations de politique clés appropriées définies pour Policy in AgentCore afin d'utiliser la clé pour le chiffrement et le déchiffrement. Consultez Autoriser l'utilisation de votre clé AWS KMS pour Policy in AgentCore pour connaître les autorisations requises.

Pour chiffrer votre moteur de politiques à l'aide de la AWS CLI, incluez le --encryption-key-arn paramètre lors de l'envoi d'une create-policy-engine demande :

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 réponse inclut l'ARN et le statut du moteur de politiques :

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

Limitations

Les limites suivantes s'appliquent au chiffrement des clés géré par le client pour les moteurs de politiques :

Résolution des problèmes

Cette section décrit les erreurs courantes liées aux clés gérées par le client que vous pouvez rencontrer lors de l'utilisation de Policy dans AgentCore et fournit des étapes de dépannage pour les résoudre.

Accès refusé : AWS Problème d'autorisation KMS

Erreur : « Accès refusé pour la clé KMS spécifiée. Vérifiez que la politique clé accorde les autorisations requises. »

Cela peut signifier que l'appelant ne dispose pas des autorisations d'action kms : * requises dans sa politique IAM ou sa politique de clé AWS KMS, ou que la clé référencée n'existe pas ou n'existe plus.

Pour résoudre ce problème, procédez comme suit :

Exception de validation : AWS Configuration de la clé KMS

Erreur : « La clé KMS spécifiée n'est pas utilisable. Vérifiez que la clé est activée et qu'elle n'est pas en attente de suppression. »

Cela signifie que la clé référencée ne peut pas être utilisée pour le chiffrement de clé géré par le client en raison de sa configuration actuelle. Les raisons possibles sont les suivantes :

Pour résoudre ce problème : vérifiez que la clé répond aux conditions requises décrites dans Conditions préalables au chiffrement de votre moteur de politiques.