本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用客户管理的 KMS 密钥加密您的 AgentCore 网关
<a name="gateway-encryption"></a>

默认情况下，Gateway 使用服务管理的 Amazon 密钥管理服务密钥对您的静态数据进行加密。但是，在以下情况下，您可以选择提供自己的客户管理的 KMS 密钥来加密静态数据：
+ 创建网关。
+ 更新网关的配置。

使用客户管理的密钥可以让你更好地控制加密过程，包括：
+ 按自己的时间表轮换密钥
+ 通过 IAM 策略控制对密钥的访问权限
+ 不再需要密钥时将其禁用或删除
+ 通过 CloudWatch 日志和日志审核密钥使用情况 Amazon CloudTrail

有关更多信息，请参阅[Amazon 密钥管理服务开发者指南](https://docs.amazonaws.cn/kms/latest/developerguide/)。

**注意**  
如果您选择使用客户管理的密钥，则有责任管理该密钥及其权限。如果密钥被禁用或删除，或者 Gateway 失去了使用该密钥的权限，您将无法访问加密数据。

## 加密网关的先决条件 AgentCore
<a name="gateway-encryption-prereqs"></a>

在加密网关之前，请确保您已满足以下先决条件：
+ 您可以访问 KMS 密钥。有关创建 KMS 密钥的信息，请参阅[创建 KMS 密钥](https://docs.amazonaws.cn/kms/latest/developerguide/create-keys.html)。
+ KMS 密钥附加了允许以下权限的密钥策略：
  + 允许网关服务角色执行以下操作的权限：
    + kms: CreateGrant
    + kms: DescribeKey
    + kms:Decrypt
    + kms: GenerateDataKey
  + （如果您为网关启用 CloudWatch 日志）允许 CloudWatch 日志服务解密密钥的权限。

    有关控制 KMS 密钥的 IAM 权限的更多信息，请参阅密[钥管理服务开发人员指南](https://docs.amazonaws.cn/kms/latest/developerguide/control-access.html)中的 KMS Amazon 密钥访问和权限。

 **示例密钥政策** 

以下示例策略提供了加密网关和使用加密网关所需的权限。第四条语句还允许 CloudWatch 记录加密网关的密钥使用情况。该策略包含符合安全最佳实践的条件密钥。

```
{
"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}}替换为要允许描述密钥的实际 Amazon 区域。
+  **AllowServiceRoleDecryptKey**— 如果请求是通过 AgentCore 服务发出的，并且请求所针对的网关的 ARN 与字段中的 ARN 相匹配，则允许指定的主体解密密钥。`kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn`替换以下值：
  +  `Principal`— 将该`AWS`值替换为您的网关服务角色的实际 ARN。
  +  `Condition`— 执行以下操作：
    + 在`kms:ViaService`数组中，{{us-east-1}}替换为要允许解密密钥的实际 Amazon 区域。
    + 将该`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}}替换为要允许解密密钥的实际 Amazon 区域。
    + 将该`kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn`值替换为网关的实际 ARN（如果您想允许）。
+  **AllowKMSDecryptionLogging**— 允许指定的委托人解密客户管理的 KMS 密钥，以通过 CloudWatch 日志审核密钥的使用情况。在`kms:EncryptionContext:SourceArn`值中，将{{us-east-1}}和{{123456789012}}值替换为您的实际 Amazon 地区和账户 ID。

**Example**  

1. ===== 使用客户管理的 KMS 密钥加密您的网关

1. 按照[创建亚马逊 Bedrock AgentCore 网关中的**控制台**步骤](gateway-create.md)并展开 ** KMS 密钥-可选**部分。

1. 选择 “**自定义加密设置（高级）” **。

1. 选择 KMS 密钥并确认其详细信息。
**注意**  
如果您没有看到 KMS 密钥，请查看加密 AgentCore 网关的[先决条件](#gateway-encryption-prereqs)并检查权限配置是否正确。

1. 继续完成剩余的控制台步骤。

1. 要使用 Amazon CLI 对网关进行加密，请在通过[AgentCore 控制平面](https://docs.amazonaws.cn/cli/latest/reference/bedrock-agentcore-control/)客户端发送以下任一请求`kms-key-arn`时加入。:
   +  [创建网关 ](https://docs.amazonaws.cn/cli/latest/reference/bedrock-agentcore-control/create-gateway.html) 
   +  [更新网关 ](https://docs.amazonaws.cn/cli/latest/reference/bedrock-agentcore-control/update-gateway.html) 

     以下示例显示了使用`kms-key-arn`参数指定 Amazon 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. 要使用 Amazon Python SDK (Boto3) 对网关进行加密，请在通过[AgentCore 控制平面](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)客户端发送以下任一请求`kms-key-arn`时加入。:
   +  [创建\_网关 ](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/create_gateway.html) 
   +  [更新网关 ](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/update_gateway.html) 

     以下示例显示了一个示例 Boto3 请求，该请求使用使用参数指定的 Amazon KMS 密钥创建网关：`kmsKeyArn`

     ```
     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"
         }
       }
     )
     ```