# API Gateway 中的 REST API 安全策略
<a name="apigateway-security-policies"></a>

*安全策略* 是 API Gateway 提供的最低 TLS 版本和密码套件的预定义组合。当您的客户端与您的 API 或自定义域名建立 TLS 握手时，安全策略会强制实施 API Gateway 接受的 TLS 版本和密码套件。安全策略会保护您的 API 和自定义域名免受网络安全问题的侵扰，例如客户端和服务器之间的篡改和侦听。

API Gateway 支持传统安全策略和增强型安全策略。`TLS_1_0` 和 `TLS_1_2` 是传统安全策略。使用这些安全策略是为了实现向后兼容性。任何以 `SecurityPolicy_` 开头的策略都是增强型安全策略。可将这些策略用于受监管的工作负载、高级治理或后量子密码术。使用增强型安全策略时，还必须设置端点访问模式以进行更多治理。有关更多信息，请参阅 [端点访问模式](#apigateway-security-policies-endpoint-access-mode)。

## API Gateway 如何应用安全策略
<a name="apigateway-security-policies-understanding"></a>

以下示例以 `SecurityPolicy_TLS13_1_3_2025_09` 安全策略为例，显示 API Gateway 如何应用安全策略。

`SecurityPolicy_TLS13_1_3_2025_09` 安全策略接受 TLS 1.3 流量并拒绝 TLS 1.2 和 TLS 1.0 流量。对于 TLS 1.3 流量，该安全策略接受以下密码套件：
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`

API Gateway 不接受任何其他密码套件。例如，该安全策略将拒绝使用 `AES128-SHA` 密码套件的任何 TLS 1.3 流量。有关受支持的 TLS 版本和密码的更多信息，请参阅[支持的安全策略](apigateway-security-policies-list.md)。

要监控客户端使用哪些 TLS 协议和密码来访问您的 API Gateway，您可以在访问日志中使用 `$context.tlsVersion` 和 `$context.cipherSuite` 上下文变量。有关更多信息，请参阅 [监控 API Gateway 中的 REST API](rest-api-monitor.md)。

## 端点访问模式
<a name="apigateway-security-policies-endpoint-access-mode"></a>

端点访问模式是一个附加参数，对于任何使用以 `SecurityPolicy_` 开头的增强型安全策略的 REST API 或自定义域名，您必须指定该参数。当您创建资源或将安全策略从传统策略更改为增强型策略时，您就会这样做。

将端点访问模式设置为 `STRICT` 时，对您的 REST API 或自定义域名的任何请求都必须通过以下检查：
+ 请求必须源自与您的资源相同的 API Gateway 端点类型。这可能来自区域端点、边缘优化型端点或私有端点。
+ 如果您使用区域或私有端点，API Gateway 将使用 SNI 主机匹配。如果您使用边缘优化型端点，API Gateway 将遵循 CloudFront 的域名前置防护机制。有关更多信息，请参阅[域名前置](https://docs.amazonaws.cn/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions)。

如果不满足这两个条件中的任何一个，API Gateway 将会拒绝该请求。建议您尽可能使用 `STRICT` 端点访问模式。

要将现有 API 或域名改为使用严格端点访问模式，请先将您的安全策略更新为增强型安全策略，并将端点访问模式设置为 `BASIC`。验证流量和访问日志后，将端点访问模式设置为 `STRICT`。当您将端点访问模式从 `STRICT` 改为 `BASIC` 时，在传播更改期间，您的端点将在大约 15 分钟内不可用。

对于某些应用程序架构，您不应将端点访问模式设置为 `STRICT`，而应设置为 `BASIC`。下表显示了一些应用程序架构和建议，以便您的 REST API 或自定义域名可以使用 `STRICT` 端点访问模式。


| 架构 | 建议的迁移 | 
| --- | --- | 
| 使用 VPC 端点访问公有自定义域名。 | 此架构使用跨端点类型的流量。建议您迁移到 [API Gateway 中私有 API 的自定义域名](apigateway-private-custom-domains.md)。 | 
|  使用任何方法调用不使用自定义域名或私有 DNS 名称的私有 API。 | 此架构会导致主机标头与 TLS 握手中使用的 SNI 不匹配，并且无法通过 CloudFront 的域名前置限制。建议您将 VPC 迁移到使用私有 DNS。 | 
| 使用域分片将内容分发到多个域或子域。 | 此架构会导致主机标头与 TLS 握手中使用的 SNI 不匹配，并且无法通过 CloudFront 的域名前置限制。建议您使用 `HTTP/2` 并摒弃这种反模式。 | 

以下是使用端点访问模式时的注意事项：
+ 如果 API 或域名的端点访问模式为 `STRICT`，则无法更改端点类型。要更改端点类型，请先将端点访问模式更改为 `BASIC`。
+ 将端点访问模式从 `BASIC` 更改为 `STRICT` 后，API Gateway 会延迟 15 分钟才能强制执行严格的端点访问模式。
+ 当您将安全策略从以 `SecurityPolicy_` 开头的策略更改为传统策略时，必须将端点访问模式取消设置为 `""`。

## 注意事项
<a name="apigateway-security-policies-considerations"></a>

以下是 API Gateway 中针对 REST API 的安全策略的注意事项：
+ 您可以在 OpenAPI 定义文件中导入安全策略。有关更多信息，请参阅 [x-amazon-apigateway-endpoint-access-modex-amazon-apigateway-security-policy](openapi-extensions-security-policy.md)。
+ 您的 API 可以映射到与 API 具有不同安全策略的自定义域名。当您调用该自定义域名时，API Gateway 会使用 API 的安全策略来协商 TLS 握手。如果您禁用默认 API 端点，则这可能会影响调用方调用 API 的方式。
+ 如果您更改安全策略，大约需要 15 分钟才能完成更新。您可以监控您的 API 的 `apiStatus`。当您的 API 更新时，`apiStatus` 为 `UPDATING`，更新完成后，它将变为 `AVAILABLE`。当您的 API 状态为 `UPDATING` 时，您仍然可以调用它。
+ API Gateway 支持对所有 API 应用安全策略。但是，您只能为 REST API 选择安全策略。对于 HTTP 或 WebSocket API，API Gateway 仅支持 `TLS_1_2` 安全策略。
+ 您无法将 API 的安全策略从 `TLS_1_0` 更新为 `TLS_1_2`。
+ 某些安全策略同时支持 ECDSA 和 RSA 密码套件。如果您将此类策略与自定义域名结合使用，则密码套件与客户提供的证书密钥类型（RSA 或 ECDSA）相匹配。如果您将此类策略与 REST API 结合使用，则密码套件将匹配与 RSA 证书类型兼容的密码套件。