# 建議加密
<a name="recommendations-encryption"></a>

當您`kmsKeyArn`在建議上指定 時，服務會使用信封加密搭配加密 SDK 來 AWS 加密**建議組態**和**建議結果**。所有其他建議中繼資料 （名稱、類型、狀態） 都會使用 AWS 擁有的金鑰進行加密。

`kmsKeyArn` 是在建立時間透過 指定`StartRecommendation`。

## 運作方式
<a name="recommendations-encryption-how-it-works"></a>

建議加密使用 AWS 加密開發套件進行信封加密。當服務寫入或讀取建議資料時，它會呼叫 KMS 來產生或解密資料金鑰。建議結果也會使用相同的客戶受管金鑰儲存在具有 SSE-KMS 的 S3 中。

在 API 時間，服務會使用試轉檢查 （正向存取工作階段） 驗證發起人是否具有 KMS 許可。這會立即擷取許可問題，而不是在建議工作流程期間非同步失敗。

當建議工作流程以非同步方式執行時，服務主體 (`bedrock-agentcore.amazonaws.com`) 會解密組態並加密結果。服務主體必須在金鑰政策中具有 `kms:GenerateDataKey`和 `kms:Decrypt`許可。

AgentCore 最佳化僅支援對稱加密 KMS 金鑰。KMS 金鑰必須與建議位於相同的 AWS 區域。

### 設定使用客戶受管 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`內容範圍內的 IAM 角色`kms:GenerateDataKey`和`kms:Decrypt`許可。將 {{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>

下列 CloudTrail 事件名稱會針對建議 KMS 操作顯示：
+  `GenerateDataKey` — 開始建議時 （加密組態） 和建議工作流程完成時 （加密結果）。`encryptionContext` 欄位包含 `aws:bedrock-agentcore:recommendationArn`。
+  `Decrypt` — 建議工作流程處理組態時，或擷取建議結果時。
+  `DescribeKey` — 在建議建立時間驗證金鑰時。

## 當金鑰無法使用時的行為
<a name="recommendations-encryption-unavailable"></a>

如果您停用或刪除建議所使用的客戶受管 KMS 金鑰：
+  **StartRecommendation** — 使用 驗證時失敗`ValidationException`。
+  **GetRecommendation** — 失敗，`ValidationException`指出 KMS 金鑰已停用或刪除。
+  **ListRecommendations** — 成功，因為列出只會傳回中繼資料，不需要 KMS 操作。
+  **DeleteRecommendation** — 成功，因為刪除不需要解密建議資料。