View a markdown version of this page

구성 번들 암호화 - Amazon Bedrock AgentCore
작동 방식구성 번들의 KMS 사용량 모니터링키를 사용할 수 없게 될 때의 동작

구성 번들 암호화

구성 번들kmsKeyArn에서를 지정하면 서비스는 봉투 암호화를 사용하여 구성 요소 구성(시스템 프롬프트, 도구 설명 및 기타 구성 콘텐츠)을 암호화합니다. 다른 모든 번들 메타데이터(이름, 설명, 버전 IDs, 타임스탬프)는 AWS 소유 키로 암호화된 상태로 유지됩니다.

작동 방식

구성 번들 암호화는 호출자 자격 증명과 함께 봉투 암호화를 사용합니다. 를 사용하여 번들을 생성하거나 업데이트하면 kmsKeyArn서비스는 (포워드 액세스 세션을 통해) 자격 증명을 사용하여 KMS에서 데이터 암호화 키(DEK)를 생성합니다. 서비스는 해당 DEK와 함께 AES-GCM을 사용하여 구성 요소 구성을 로컬로 암호화한 다음 암호화된 DEK를 번들과 함께 저장합니다. 번들을 검색하면 서비스가 자격 증명을 사용하여 DEK를 복호화하고 구성 요소를 복호화합니다.

호출자는 키에 대한 kms:GenerateDataKey, kms:Decryptkms:DescribeKey, 및 kms:ReEncrypt* 권한이 있어야 합니다.

AgentCore 최적화는 대칭 암호화 KMS 키만 지원합니다. KMS 키는 구성 번들과 동일한 AWS 리전에 있어야 합니다.

고객 관리형 KMS 키를 사용하도록 권한 구성

다음 키 정책은 구성 번들 암호화에 필요한 최소 권한을 제공합니다. 이 정책에는 두 명령문이 있습니다:

  • AllowCallerAccess - IAM 사용자 또는 역할이를 통해 키를 검증할 수 있도록 허용합니다DescribeKey.

  • AllowCallerCryptoOps - IAM 사용자 또는 역할이 데이터 키를 생성하고, 복호화하고, 암호화 컨텍스트에 따라 범위가 지정된 (키 교체를 위해) 다시 암호화할 수 있도록 허용합니다.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyConfigBundleRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt",
        "kms:ReEncrypt*"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*"
        }
      }
    }
  ]
}

정책에는 다음 명령문이 포함되어 있습니다.

  • AllowCallerAccess - 번들 생성 또는 업데이트 시 키 검증을 위한 IAM 역할 kms:DescribeKey 권한을 부여합니다. 111122223333을 계정 ID로 바꾸고 MyConfigBundleRole을 구성 번들을 관리하는 IAM 역할 또는 사용자로 바꿉니다.

  • AllowCallerCryptoOps - aws:bedrock-agentcore:configurationBundleArn 암호화 컨텍스트에 따라 범위가 지정된 IAM 역할 kms:GenerateDataKeykms:Decrypt, 및 kms:ReEncrypt* 권한을 부여합니다. 키 교체(기존 번들에서 KMS 키 변경)에는 kms:ReEncrypt* 권한이 필요합니다. 111122223333, MyConfigBundleRole 및 us-east-1을 값으로 바꿉니다. 계정의 모든 구성 번들에 대한 액세스를 허용하려면 StringLike와 함께 와일드카드를 사용합니다arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/*.

고객 관리형 KMS 키에 대한 액세스 범위 축소

암호화 컨텍스트를 사용하여 고객 관리형 키에 대한 액세스 범위를 좁힐 수 있습니다. AgentCore 최적화에는 모든 KMS 작업에 다음과 같은 암호화 컨텍스트가 포함됩니다.

{
  "aws:bedrock-agentcore:configurationBundleArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:configuration-bundle/bundle-id"
}

위의 예제 키 정책의 AllowCallerCryptoOps 문과 같이 키 정책 조건에서이 암호화 컨텍스트를 사용하여 KMS 작업을 특정 구성 번들로 제한할 수 있습니다.

고객 관리형 KMS 키를 사용하여 구성 번들 생성

구성 번들을 암호화하려면 CreateConfigurationBundle을 호출할 때 kmsKeyArn 파라미터를 지정합니다.

예
AWS CLI
aws bedrock-agentcore-control create-configuration-bundle \
  --bundle-name "MyEncryptedBundle" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --components '{
    "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent": {
      "configuration": {
        "systemPrompt": "You are a helpful assistant.",
        "modelId": "anthropic.claude-3-sonnet"
      }
    }
  }'
Python (Boto3)
import boto3

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

response = client.create_configuration_bundle(
    bundleName='MyEncryptedBundle',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    components={
        'arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent': {
            'configuration': {
                'systemPrompt': 'You are a helpful assistant.',
                'modelId': 'anthropic.claude-3-sonnet'
            }
        }
    }
)

print(f"Bundle ID: {response['bundleId']}")

기존 번들에서 암호화 구성 변경

UpdateConfigurationBundle을 사용하여 기존 번들의 암호화 구성을 변경할 수 있습니다.

  • 암호화 추가 - 번들 없이 생성된 번들kmsKeyArn에서를 지정합니다. 서비스는 새 DEK를 생성하고 구성 요소 구성을 암호화합니다.

  • 키 교체 - 다른를 지정합니다kmsKeyArn. 서비스는를 사용하여 기존 DEK를 이전 키에서 새 키로 다시 래핑합니다kms:ReEncrypt. 호출자는 두 키 모두에 대한 권한이 있어야 합니다. 이전 키를 사용할 수 없는 경우(비활성화, 삭제 또는 누락된 권한) 업데이트가 실패합니다.

참고

구성 번들이 추가된 후에는 구성 번들에서 고객 관리형 키 암호화를 제거할 수 없습니다.

구성 번들의 KMS 사용량 모니터링

구성 번들 KMS 작업에 대해 다음과 같은 CloudTrail 이벤트 이름이 나타납니다.

  • GenerateDataKey - 고객 관리형 키로 번들을 생성하거나 기존 번들에 암호화를 추가하는 경우. encryptionContext 필드에는가 포함됩니다aws:bedrock-agentcore:configurationBundleArn.

  • Decrypt - 번들 콘텐츠(GetConfigurationBundle, GetConfigurationBundleVersion)를 검색하거나 암호화된 번들을 업데이트할 때.

  • ReEncrypt - UpdateConfigurationBundle을 통해 기존 번들에서 KMS 키를 교체하는 경우.

  • DescribeKey - 번들 생성 또는 업데이트 시 키를 검증하는 경우.

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

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

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

  • UpdateConfigurationBundle - 서비스가 새 구성 요소를 다시 암호화하기 위해 기존 DEK를 복호화할 수 없기 때문에 실패합니다. 이전 키를 다시 래핑할 수 없으므로 키 교체도 실패합니다.

  • GetConfigurationBundle / GetConfigurationBundleVersion - 서비스가 DEK 또는 구성 요소 구성을 해독할 수 없기 때문에 실패합니다.

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

  • DeleteConfigurationBundle - 삭제 시 번들 데이터를 해독할 필요가 없으므로 성공합니다.

액세스를 복원하려면 키를 다시 활성화하거나 키 정책을 업데이트하여 필요한 권한을 부여합니다.