# 구성 번들 암호화
구성 번들`kmsKeyArn`에서를 지정하면 서비스는 봉투 암호화를 사용하여 **구성 요소 구성**(시스템 프롬프트, 도구 설명 및 기타 구성 콘텐츠)을 암호화합니다. 다른 모든 번들 메타데이터(이름, 설명, 버전 IDs, 타임스탬프)는 AWS 소유 키로 암호화된 상태로 유지됩니다.
## 작동 방식
구성 번들 암호화는 호출자 자격 증명과 함께 봉투 암호화를 사용합니다. 를 사용하여 번들을 생성하거나 업데이트하면 `kmsKeyArn`서비스는 ([포워드 액세스 세션을](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#fas) 통해) 자격 증명을 사용하여 KMS에서 데이터 암호화 키(DEK)를 생성합니다. 서비스는 해당 DEK와 함께 AES-GCM을 사용하여 구성 요소 구성을 로컬로 암호화한 다음 암호화된 DEK를 번들과 함께 저장합니다. 번들을 검색하면 서비스가 자격 증명을 사용하여 DEK를 복호화하고 구성 요소를 복호화합니다.
호출자는 키에 대한 `kms:GenerateDataKey`, `kms:Decrypt``kms: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:GenerateDataKey``kms: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](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateConfigurationBundle.html)을 호출할 때 `kmsKeyArn` 파라미터를 지정합니다.
**Example**
```
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"
}
}
}'
```
```
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](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateConfigurationBundle.html)을 사용하여 기존 번들의 암호화 구성을 변경할 수 있습니다.
+ **암호화 추가** - 번들 없이 생성된 번들`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** - 삭제 시 번들 데이터를 해독할 필요가 없으므로 성공합니다.
액세스를 복원하려면 키를 다시 활성화하거나 키 정책을 업데이트하여 필요한 권한을 부여합니다.