View a markdown version of this page

Chiffrement des recommandations - Amazon Bedrock AgentCore
Comment ça marcheCommencer une recommandation avec une clé KMS gérée par le clientSurveillance de l'utilisation du KMS pour obtenir des recommandationsComportement lorsqu'une clé n'est plus disponible

Chiffrement des recommandations

Lorsque vous spécifiez une recommandation, kmsKeyArn le service chiffre la configuration de la recommandation et le résultat de la recommandation à l'aide du chiffrement d'enveloppe avec le SDK de AWS chiffrement. Toutes les autres métadonnées de recommandation (nom, type, statut) restent cryptées avec la clé AWS détenue.

Le kmsKeyArn est spécifié au moment de la création viaStartRecommendation.

Comment ça marche

Le chiffrement des recommandations utilise le SDK AWS de chiffrement pour le chiffrement des enveloppes. Lorsque le service écrit ou lit des données de recommandation, il appelle KMS pour générer ou déchiffrer des clés de données. Le résultat de la recommandation est également stocké dans S3 en SSE-KMS utilisant la même clé gérée par le client.

Au moment de l'API, le service vérifie que l'appelant dispose des autorisations KMS à l'aide d'une vérification à sec (Forward Access Sessions). Cela permet de détecter immédiatement les problèmes d'autorisation plutôt que d'échouer de manière asynchrone pendant le flux de travail de recommandation.

Lorsque le flux de travail de recommandation s'exécute de manière asynchrone, le principal de service (bedrock-agentcore.amazonaws.com) déchiffre la configuration et chiffre le résultat. Le directeur du service doit disposer kms:GenerateDataKey d'une kms:Decrypt autorisation dans la politique clé.

AgentCore les optimisations ne prennent en charge que les clés KMS de chiffrement symétriques. La clé KMS doit se trouver dans la même AWS région que la recommandation.

Configuration des autorisations pour utiliser une clé KMS gérée par le client

La politique clé suivante fournit les autorisations minimales requises pour le chiffrement des recommandations. La stratégie comporte trois déclarations :

  • AllowCallerAccess— Permet à l'utilisateur ou au rôle IAM de valider la clé viaDescribeKey.

  • AllowCallerCryptoOps— Permet à l'utilisateur ou au rôle IAM de chiffrer et de déchiffrer, en fonction du contexte de chiffrement.

  • AllowServicePrincipalAccess— Permet au principal du AgentCore service de chiffrer et de déchiffrer les données de recommandation pendant le flux de travail de recommandation asynchrone, défini par compte source et ARN source.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyRecommendationRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyRecommendationRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*"
        }
      }
    },
    {
      "Sid": "AllowServicePrincipalAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*"
        }
      }
    }
  ]
}

La politique contient les déclarations suivantes :

  • AllowCallerAccess— Accorde au rôle IAM l'kms:DescribeKeyautorisation de valider les clés au moment de la création de la recommandation. 111122223333Remplacez-le par votre identifiant de compte et MyRecommendationRole par le rôle ou l'utilisateur IAM qui lance les recommandations.

  • AllowCallerCryptoOps— Accorde le rôle kms:GenerateDataKey et les kms:Decrypt autorisations IAM, dans le cadre du contexte de aws:bedrock-agentcore:recommendationArn chiffrement. Remplacez 111122223333MyRecommendationRole, et us-east-1 par vos valeurs. Pour autoriser l'accès à toutes les recommandations de votre compte, utilisez un caractère générique avec StringLike :arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*.

  • AllowServicePrincipalAccess— Accorde le principal du AgentCore service kms:GenerateDataKey et kms:Decrypt les autorisations nécessaires pour chiffrer et déchiffrer les données de recommandation pendant le flux de travail asynchrone. Délimité par compte source et ARN source (aws:SourceArn) pour éviter les attaques secondaires confuses. Remplacez us-east-1 et 111122223333 par votre région et votre numéro de compte.

Délimitation de l'accès à la clé KMS gérée par le client

Vous pouvez utiliser le contexte de chiffrement pour limiter l'accès à la clé gérée par le client. AgentCore les optimisations incluent le contexte de chiffrement suivant dans toutes les opérations KMS :

{
  "aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}

Vous pouvez utiliser ce contexte de chiffrement dans des conditions de politique clés pour limiter les opérations KMS à des recommandations spécifiques, comme indiqué dans la AllowCallerCryptoOps déclaration figurant dans l'exemple de politique clé ci-dessus. Notez que cela est AllowServicePrincipalAccess utilisé aws:SourceArn à des fins de cadrage plutôt que de contexte de chiffrement.

Commencer une recommandation avec une clé KMS gérée par le client

Spécifiez le kmsKeyArn paramètre lors de l'appel StartRecommendation :

Exemple
AgentCore CLI
agentcore run recommendation \
  -t system-prompt \
  -r MyAgent \
  -e Builtin.Correctness \
  --inline "You are a helpful assistant" \
  --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
AWS CLI
aws bedrock-agentcore start-recommendation \
  --name "MyEncryptedRecommendation" \
  --type SYSTEM_PROMPT_RECOMMENDATION \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --recommendation-config '{
    "systemPromptRecommendationConfig": {
      "systemPrompt": {
        "text": "You are a helpful assistant."
      },
      "agentTraces": {
        "cloudwatchLogs": {
          "logGroupArns": ["arn:aws:logs:us-east-1:111122223333:log-group:/aws/bedrock-agentcore/sessions/my-agent"],
          "serviceNames": ["my-agent.DEFAULT"],
          "startTime": "2025-01-01T00:00:00Z",
          "endTime": "2025-01-02T00:00:00Z"
        }
      },
      "evaluationConfig": {
        "evaluators": [{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]
      }
    }
  }'
Python (Boto3)
import boto3

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

response = client.start_recommendation(
    name='MyEncryptedRecommendation',
    type='SYSTEM_PROMPT_RECOMMENDATION',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    recommendationConfig={
        'systemPromptRecommendationConfig': {
            'systemPrompt': {
                'text': 'You are a helpful assistant.'
            },
            'agentTraces': {
                'cloudwatchLogs': {
                    'logGroupArns': ['arn:aws:logs:us-east-1:111122223333:log-group:/aws/bedrock-agentcore/sessions/my-agent'],
                    'serviceNames': ['my-agent.DEFAULT'],
                    'startTime': '2025-01-01T00:00:00Z',
                    'endTime': '2025-01-02T00:00:00Z'
                }
            },
            'evaluationConfig': {
                'evaluators': [{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}]
            }
        }
    }
)

print(f"Recommendation ID: {response['recommendationId']}")

Surveillance de l'utilisation du KMS pour obtenir des recommandations

Les noms CloudTrail d'événements suivants apparaissent pour les opérations KMS recommandées :

  • GenerateDataKey— Lors du lancement d'une recommandation (configuration de chiffrement) et lorsque le flux de travail de recommandation est terminé (chiffrement du résultat). Le encryptionContext champ contientaws:bedrock-agentcore:recommendationArn.

  • Decrypt— Lorsque le flux de travail de recommandation traite la configuration ou lorsqu'il récupère les résultats des recommandations.

  • DescribeKey— Lors de la validation de la clé au moment de la création de la recommandation.

Comportement lorsqu'une clé n'est plus disponible

Si vous désactivez ou supprimez la clé KMS gérée par le client utilisée par une recommandation :

  • StartRecommendation— Échoue lors de la validation avecValidationException.

  • GetRecommendation— Impossible d'ValidationExceptionindiquer que la clé KMS est désactivée ou supprimée.

  • ListRecommendations— Succès car le listage renvoie uniquement des métadonnées et ne nécessite aucune opération KMS.

  • DeleteRecommendation— Succès car la suppression ne nécessite pas le déchiffrement des données de recommandation.