# レコメンデーションの暗号化
レコメンデーション`kmsKeyArn`で を指定すると、サービスは AWS Encryption SDK によるエンベロープ暗号化を使用して**レコメンデーション設定**とレ**コメンデーション結果を**暗号化します。他のすべてのレコメンデーションメタデータ (名前、タイプ、ステータス) は、 AWS 所有キーで暗号化されたままです。
`kmsKeyArn` は、 を介して作成時に指定されます`StartRecommendation`。
## 仕組み
レコメンデーション暗号化は、エンベロープ暗号化に AWS Encryption SDK を使用します。サービスがレコメンデーションデータを書き込みまたは読み取ると、KMS を呼び出してデータキーを生成または復号します。レコメンデーション結果は、同じカスタマーマネージドキーを使用して SSE-KMS で S3 にも保存されます。
API 時に、サービスは、ドライランチェック (転送アクセスセッション) を使用して発信者に KMS アクセス許可があることを検証します。これにより、レコメンデーションワークフロー中に非同期的に失敗するのではなく、アクセス許可の問題がすぐに検出されます。
レコメンデーションワークフローが非同期で実行されると、サービスプリンシパル (`bedrock-agentcore.amazonaws.com`) は設定を復号し、結果を暗号化します。サービスプリンシパルは、キーポリシーに `kms:GenerateDataKey`および アクセス`kms:Decrypt`許可を持っている必要があります。
AgentCore 最適化は、対称暗号化 KMS キーのみをサポートします。KMS キーは、レコメンデーションと同じ AWS リージョンに存在する必要があります。
### カスタマーマネージド KMS キーを使用するためのアクセス許可の設定
次のキーポリシーは、レコメンデーションの暗号化に必要な最小限のアクセス許可を提供します。このポリシーには以下の 3 つのステートメントがあります。
+ **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** – レコメンデーションの作成時にキー検証のアクセス`kms:DescribeKey`許可を IAM ロールに付与します。{{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 キーへのアクセスのスコープダウン
暗号化コンテキストを使用して、カスタマーマネージドキーへのアクセスの範囲を絞り込むことができます。AgentCore 最適化には、すべての KMS オペレーションに次の暗号化コンテキストが含まれます。
```
{
"aws:bedrock-agentcore:recommendationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:recommendation/recommendation-id"
}
```
この暗号化コンテキストをキーポリシー条件で使用して、上記のキーポリシーの例の `AllowCallerCryptoOps`ステートメントに示すように、KMS オペレーションを特定のレコメンデーションに制限できます。は、暗号化コンテキストではなくスコープ`aws:SourceArn`設定に `AllowServicePrincipalAccess`を使用することに注意してください。
## カスタマーマネージド KMS キーを使用したレコメンデーションの開始
を呼び出すときに `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 使用状況のモニタリング
レコメンデーション KMS オペレーションには、次の CloudTrail イベント名が表示されます。
+ `GenerateDataKey` — レコメンデーションを開始する場合 (暗号化設定）、およびレコメンデーションワークフローが完了した場合 (結果を暗号化する場合）。`encryptionContext` フィールドには が含まれます`aws:bedrock-agentcore:recommendationArn`。
+ `Decrypt` — レコメンデーションワークフローが設定を処理する場合、またはレコメンデーション結果を取得する場合。
+ `DescribeKey` — レコメンデーションの作成時にキーを検証する場合。
## キーが使用できなくなった場合の動作
レコメンデーションで使用されるカスタマーマネージド KMS キーを無効化または削除する場合:
+ **StartRecommendation** — での検証時に失敗します`ValidationException`。
+ **GetRecommendation** — KMS キーが無効または削除された`ValidationException`ことを示す に失敗します。
+ **ListRecommendations** — リストはメタデータのみを返し、KMS オペレーションを必要としないため、成功します。
+ **DeleteRecommendation** — 削除ではレコメンデーションデータを復号する必要がないため、成功します。