# 고객 관리형 KMS 키로 AgentCore 게이트웨이 암호화
기본적으로 Gateway는 서비스 관리형 AWS Key Management Service 키를 사용하여 저장 데이터를 암호화합니다. 그러나 다음과 같은 경우 저장 데이터를 암호화하기 위한 자체 고객 관리형 KMS 키를 선택적으로 제공할 수 있습니다.
+ 게이트웨이를 생성합니다.
+ 게이트웨이의 구성을 업데이트합니다.
고객 관리형 키를 사용하면 다음과 같은 기능을 포함하여 암호화 프로세스를 더 잘 제어할 수 있습니다.
+ 일정에 따라 키 교체
+ IAM 정책을 통해 키에 대한 액세스 제어
+ 더 이상 필요하지 않은 경우 키 비활성화 또는 삭제
+ CloudWatch 로그 및 AWS CloudTrail을 통한 키 사용량 감사
자세한 내용은 [AWS Key Management Service 개발자 안내서](https://docs.aws.amazon.com/kms/latest/developerguide/)를 참조하세요.
**참고**
고객 관리형 키를 사용하기로 선택한 경우 키와 해당 권한을 관리할 책임은 사용자에게 있습니다. 키가 비활성화되거나 삭제되거나 Gateway에서 키 사용 권한을 상실하면 암호화된 데이터에 대한 액세스 권한이 상실됩니다.
## AgentCore 게이트웨이 암호화를 위한 사전 조건
게이트웨이를 암호화하기 전에 다음 사전 조건을 충족했는지 확인합니다.
+ KMS 키에 액세스할 수 있습니다. KMS 키 생성에 대한 자세한 내용은 [KMS 키 생성을 참조하세요](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
+ KMS 키에는 다음 권한을 허용하는 키 정책이 연결되어 있습니다.
+ 게이트웨이 서비스 역할이 다음 작업을 수행할 수 있도록 허용하는 권한:
+ kms:CreateGrant
+ kms:DescribeKey
+ kms:Decrypt
+ kms:GenerateDataKey
+ (게이트웨이에 대해 CloudWatch Logs를 활성화한 경우) CloudWatch Logs 서비스가 키를 해독하도록 허용하는 권한입니다.
KMS 키에 대한 IAM 권한 제어에 대한 자세한 내용은 AWS Key Management Service 개발자 안내서의 [KMS 키 액세스 및 권한을](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) 참조하세요.
**예제 키 정책**
다음 예제 정책은 게이트웨이를 암호화하고 암호화된 게이트웨이를 사용하는 데 필요한 권한을 제공합니다. 네 번째 문은 암호화된 게이트웨이의 키 사용에 대한 CloudWatch Logs 로깅도 허용합니다. 정책에는 보안 모범 사례를 준수하는 조건 키가 포함되어 있습니다.
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowServiceRoleDescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": [
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
]
}
}
},
{
"Sid": "AllowServiceRoleDecryptKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
]
},
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
}
}
},
{
"Sid": "AllowServiceRoleCreateGrant",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": "kms:CreateGrant",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
],
"kms:GrantConstraintType": "EncryptionContextSubset"
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": [
"Decrypt",
"GenerateDataKey"
]
},
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
}
}
},
{
"Sid": "AllowKMSDecryptionLogging",
"Effect": "Allow",
"Principal": {
"Service": "delivery.logs.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:SourceArn": "arn:aws:logs:us-east-1:123456789012:*"
}
}
}
]
}
```
정책에는 다음 명령문이 포함되어 있습니다.
+ **AllowServiceRoleDescribeKKey** - AgentCore 서비스를 통해 요청이 이루어진 경우 지정된 보안 주체가 키를 설명할 수 있도록 허용합니다. 다음 필드의 값을 바꿉니다.
+ `Principal` - `AWS` 값을 게이트웨이 서비스 역할의 실제 ARN으로 바꿉니다.
+ `Condition` - `kms:ViaService` 배열에서 {{us-east-1}}을 키 설명을 허용할 실제 AWS 리전으로 바꿉니다.
+ **AllowServiceRoleDecryptKey** - 요청이 AgentCore 서비스를 통해 이루어지고 요청이 이루어진 게이트웨이의 ARN이 `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` 필드의 ARN과 일치하는 경우 지정된 보안 주체가 키를 복호화하도록 허용합니다. 다음 값을 교체합니다.
+ `Principal` - `AWS` 값을 게이트웨이 서비스 역할의 실제 ARN으로 바꿉니다.
+ `Condition` - 다음을 수행합니다.
+ `kms:ViaService` 배열에서 {{us-east-1}}을 키 복호화를 허용할 실제 AWS 리전으로 바꿉니다.
+ `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` 값을 게이트웨이의 실제 ARN으로 바꿉니다.
+ **AllowServiceRoleCreateGrant** – 요청이 AgentCore 서비스를 통해 이루어지고 요청이 이루어진 게이트웨이의 ARN이 `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` 필드의 ARN과 일치하는 경우 지정된 보안 주체가 키에 대한 권한 부여를 생성할 수 있도록 허용합니다. 다음 값을 교체합니다.
+ `Principal` - `AWS` 값을 게이트웨이 서비스 역할의 실제 ARN으로 바꿉니다.
+ `Condition` - 다음을 수행합니다.
+ `kms:ViaService` 배열에서 {{us-east-1}}을 키 복호화를 허용할 실제 AWS 리전으로 바꿉니다.
+ `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` 값을 게이트웨이의 실제 ARN으로 바꿉니다(허용하려는 경우).
+ **AllowKMSDecryptionLogging** - 지정된 보안 주체가 CloudWatch Logs를 통해 키 사용을 감사하기 위해 고객 관리형 KMS 키를 복호화하도록 허용합니다. `kms:EncryptionContext:SourceArn` 값에서 {{us-east-1}} 및 {{123456789012}} 값을 실제 AWS 리전 및 계정 ID로 바꿉니다.
**Example**
1. ====== 고객 관리형 KMS 키로 게이트웨이 암호화
1. [Amazon Bedrock AgentCore 게이트웨이 생성](gateway-create.md)의 **콘솔** 단계를 따르고 **KMS 키 - 선택 사항** 섹션을 확장합니다.
1. **암호화 설정 사용자 지정(고급)**을 선택합니다.
1. KMS 키를 선택하고 세부 정보를 확인합니다.
**참고**
KMS 키가 표시되지 않으면 [ AgentCore 게이트웨이 암호화를 위한 사전 요구 사항](#gateway-encryption-prereqs)으로 이동하여 권한이 제대로 구성되었는지 확인합니다.
1. 나머지 콘솔 단계를 계속 진행합니다.
1. AWS CLI를 사용하여 게이트웨이를 암호화하려면 [AgentCore 컨트롤 플레](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/)인 클라이언트를 통해 다음 요청 중 하나를 전송할 `kms-key-arn` 때를 포함합니다.
+ [create-gateway](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/create-gateway.html)
+ [update-gateway](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/update-gateway.html)
다음 예제에서는 `kms-key-arn` 인수를 사용하여 지정된 AWS KMS 키로 게이트웨이를 생성하기 위한 CLI 요청의 예를 보여줍니다.
```
aws bedrock-agentcore-control create-gateway \
--name "MyGateway" \
--role-arn "arn:aws:iam::123456789012:role/GatewayRole" \
--protocol-type "MCP" \
--kms-key-arn "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--authorizer-type "CUSTOM_JWT" \
--authorizer-configuration '{
"customJWTAuthorizer": {
"allowedAudience": ["myAudience"],
"discoveryUrl": "https://example.com/.well-known/openid-configuration"
}
}'
```
1. AWS Python SDK(Boto3)를 사용하여 게이트웨이를 암호화하려면 [AgentCore 컨트롤 플레](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)인 클라이언트를 통해 다음 요청 중 하나를 전송할 `kms-key-arn` 때를 포함합니다.
+ [create\_gateway](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/create_gateway.html)
+ [update\_gateway](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/update_gateway.html)
다음 예제에서는 `kmsKeyArn` 인수를 사용하여 지정된 AWS KMS 키로 게이트웨이를 생성하기 위한 Boto3 요청의 예를 보여줍니다.
```
import boto3
# Create client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create gateway and specify
gateway = agentcore_client.create_gateway(
name="MyGateway",
roleArn="arn:aws:iam::123456789012:role/GatewayRole",
protocolType="MCP",
kmsKeyArn="arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
authorizerType="CUSTOM_JWT",
authorizerConfiguration= {
"customJWTAuthorizer": {
"allowedAudience": ["myAudience"],
"discoveryUrl": "https://example.com/.well-known/openid-configuration"
}
}
)
```