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

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

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

有关更多信息，请参阅[AWS 密钥管理服务开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/)。

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

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

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

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

 **示例密钥政策** 

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

**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`时加上。 :
   +  [创建网关](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/create-gateway.html) 
   +  [更新网关](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`时加上。 :
   +  [创建网关](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) 

     以下示例显示了使用参数指定的 AWS KMS 密钥创建网关的 Boto3 请求示例：`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"
         }
       }
     )
     ```