本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 推荐加密
<a name="recommendations-encryption"></a>

当您在推荐中`kmsKeyArn`指定时，该服务**使用加密 SDK 的信封加密来加密****推荐配置**和推荐结果。 Amazon 所有其他推荐元数据（名称、类型、状态）仍使用 Amazon 拥有的密钥进行加密。

在创建时通过指定`StartRecommendation`。`kmsKeyArn`

## 工作原理
<a name="recommendations-encryption-how-it-works"></a>

建议加密使用加 Amazon 密 SDK 进行信封加密。当该服务写入或读取推荐数据时，它会调用 KMS 来生成或解密数据密钥。推荐结果也 SSE-KMS 使用相同的客户管理密钥存储在 S3 中。

在 API 时，该服务使用试运行检查（转发访问会话）来验证调用者是否具有 KMS 权限。这样可以立即捕获权限问题，而不是在推荐工作流程中异步失败。

当推荐工作流程异步运行时，服务主体 (`bedrock-agentcore.amazonaws.com`) 会解密配置并加密结果。服务主体必须拥有`kms:GenerateDataKey`密钥政策中的`kms:Decrypt`许可。

AgentCore 优化仅支持对称加密 KMS 密钥。KMS 密钥必须与建议位于同一 Amazon 区域。

### 配置使用客户管理的 KMS 密钥的权限
<a name="recommendations-encryption-key-policy"></a>

以下密钥策略提供了建议加密所需的最低权限。该策略包含三条语句：
+  **AllowCallerAccess**— 允许 IAM 用户或角色通过验证密钥`DescribeKey`。
+  **AllowCallerCryptoOps**— 允许 IAM 用户或角色加密和解密，范围受加密上下文限制。
+  **AllowServicePrincipalAccess**— 允许 AgentCore 服务主体在异步推荐工作流程中加密和解密推荐数据，范围限于源账户和来源 ARN。

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

该政策包含以下声明：
+  **AllowCallerAccess**— 在创建建议时授予 IAM 角色进行密钥验证的`kms:DescribeKey`权限。{{111122223333}}替换为您的账户 ID {{MyRecommendationRole}} 以及启动推荐的 IAM 角色或用户。
+  **AllowCallerCryptoOps**— 授予受`aws:bedrock-agentcore:recommendationArn`加密上下文`kms:Decrypt`限制的 IAM 角色`kms:GenerateDataKey`和权限。将{{111122223333}}{{MyRecommendationRole}}、和{{us-east-1}}替换为您的值。要允许访问您账户中的所有推荐，请使用通配符和`StringLike`:`arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/*`。
+  **AllowServicePrincipalAccess**— 向 AgentCore 服务主体`kms:GenerateDataKey`授予在异步工作流程期间加密和解密推荐数据的`kms:Decrypt`权限。按来源账户和来源 ARN (`aws:SourceArn`) 设定范围，以防止混乱的副手攻击。将{{us-east-1}}和{{111122223333}}替换为您的地区和账户 ID。

### 缩小对客户管理的 KMS 密钥的访问权限
<a name="recommendations-encryption-scoping"></a>

您可以使用加密上下文来缩小对客户管理密钥的访问范围。 AgentCore 优化在所有 KMS 操作中包括以下加密上下文：

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

您可以在密钥策略条件中使用此加密上下文将 KMS 操作限制在特定的建议范围内，如上面示例密钥策略中的`AllowCallerCryptoOps`声明所示。请注意，`AllowServicePrincipalAccess``aws:SourceArn`用于范围界定而不是加密上下文。

## 使用客户管理的 KMS 密钥开始推荐
<a name="recommendations-encryption-creating"></a>

调用时指定`kmsKeyArn`参数`StartRecommendation`：

**Example**  

```
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 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"}]
      }
    }
  }'
```

```
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']}")
```

## 监控 KMS 使用情况以获取建议
<a name="recommendations-encryption-monitoring"></a>

建议的 KMS 操作会显示以下 CloudTrail 事件名称：
+  `GenerateDataKey`— 启动推荐时（加密配置）和建议工作流程完成时（加密结果）。该`encryptionContext`字段包含`aws:bedrock-agentcore:recommendationArn`。
+  `Decrypt`— 推荐工作流程处理配置时，或检索推荐结果时。
+  `DescribeKey`— 在创建建议时验证密钥时。

## 密钥不可用时的行为
<a name="recommendations-encryption-unavailable"></a>

如果您禁用或删除建议使用的客户管理的 KMS 密钥：
+  **StartRecommendation**— 使用进行验证时失败`ValidationException`。
+  **GetRecommendation**— 无法`ValidationException`指示 KMS 密钥已禁用或删除。
+  **ListRecommendations**— 之所以成功，是因为清单仅返回元数据，不需要 KMS 操作。
+  **DeleteRecommendation**— 成功是因为删除不需要解密推荐数据。