View a markdown version of this page

권장 암호화 - Amazon Bedrock AgentCore
작동 방식고객 관리형 KMS 키로 권장 사항 시작권장 사항에 대한 KMS 사용량 모니터링키를 사용할 수 없게 될 때의 동작

권장 암호화

권장 kmsKeyArn 사항에를 지정하면 서비스는 Encryption SDK를 사용한 봉투 암호화를 사용하여 권장 사항 구성 및 권장 사항 결과를 AWS 암호화합니다. 다른 모든 권장 사항 메타데이터(이름, 유형, 상태)는 AWS 소유 키로 암호화된 상태로 유지됩니다.

는 생성 시를 통해 지정kmsKeyArn됩니다StartRecommendation.

작동 방식

권장 암호화는 봉투 암호화에 AWS Encryption SDK를 사용합니다. 서비스가 권장 데이터를 작성하거나 읽을 때 KMS를 호출하여 데이터 키를 생성하거나 해독합니다. 권장 사항 결과는 동일한 고객 관리형 키를 사용하여 SSE-KMS와 함께 S3에도 저장됩니다.

API 시간에 서비스는 직접 실행 검사(Forward Access Sessions)를 사용하여 호출자에게 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 - 권장 사항 생성 시 키 검증을 위한 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 - 비동기 워크플로 중에 권장 사항 데이터를 암호화kms:GenerateDataKey하고 해독할 수 있는 kms:Decrypt 권한과 AgentCore 서비스 보안 주체를 부여합니다. 혼동된 대리자 공격을 방지하기 위해 소스 계정 및 소스 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.

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

권장 사항에 대한 KMS 사용량 모니터링

권장 KMS 작업에 대해 다음과 같은 CloudTrail 이벤트 이름이 나타납니다.

  • GenerateDataKey - 권장 사항을 시작할 때(암호화 구성) 및 권장 사항 워크플로가 완료될 때(결과 암호화). encryptionContext 필드에는가 포함됩니다aws:bedrock-agentcore:recommendationArn.

  • Decrypt - 권장 사항 워크플로가 구성을 처리하거나 권장 사항 결과를 검색할 때.

  • DescribeKey - 권장 사항 생성 시 키를 검증하는 경우.

키를 사용할 수 없게 될 때의 동작

권장 사항에서 사용하는 고객 관리형 KMS 키를 비활성화하거나 삭제하는 경우:

  • StartRecommendation -를 사용한 검증 시 실패합니다ValidationException.

  • GetRecommendation - KMS 키가 비활성화 또는 삭제되었음을 ValidationException 나타내는가 실패합니다.

  • ListRecommendations - 목록은 메타데이터만 반환하고 KMS 작업이 필요하지 않기 때문에 성공합니다.

  • DeleteRecommendation - 삭제 시 권장 사항 데이터를 해독할 필요가 없으므로 성공합니다.