Choose a security policy for your REST API custom domain in API Gateway

For greater security of your Amazon API Gateway custom domain, you can choose a security policy in the API Gateway console, the AWS CLI, or an AWS SDK.

A security policy is a predefined combination of minimum TLS version and cipher suites offered by API Gateway. You can choose either a TLS version 1.2 or TLS version 1.0 security policy. The TLS protocol addresses network security problems such as tampering and eavesdropping between a client and server. When your clients establish a TLS handshake to your API through the custom domain, the security policy enforces the TLS version and cipher suite options your clients can choose to use.

In custom domain settings, a security policy determines two settings:

• The minimum TLS version that API Gateway uses to communicate with API clients

• The cipher that API Gateway uses to encrypt the content that it returns to API clients

If you choose a TLS 1.0 security policy, the security policy accepts TLS 1.0, TLS 1.2, and TLS 1.3 traffic. If you choose a TLS 1.2 security policy, the security policy accepts TLS 1.2 and TLS 1.3 traffic and rejects TLS 1.0 traffic.

Note

You can only specify a security policy for a custom domain. For an API using a default endpoint, API Gateway uses the following security policy:

• For edge-optimized APIs: TLS-1-0

• For Regional APIs: TLS-1-0

• For private APIs: TLS-1-2

The ciphers for each security policy are described in the following tables on this page.

How to specify a security policy for custom domains

When you create a custom domain name, you specify the security policy for it. To learn how to create a custom domain, see Set up an edge-optimized custom domain name in API Gateway or Set up a Regional custom domain name in API Gateway.

To change the security policy of your custom domain name, update the custom domain settings. You can update your custom domain name settings using the AWS Management Console, the AWS CLI, or an AWS SDK.

When you use the API Gateway REST API or AWS CLI, specify the new TLS version, TLS_1_0 or TLS_1_2 in the securityPolicy parameter. For more information, see domainname:update in the Amazon API Gateway REST API Reference or update-domain-name in the AWS CLI Reference.

The update operation may take few minutes to complete.

Supported security policies, TLS protocol versions, and ciphers for edge-optimized custom domains

The following table describes the security policies that can be specified for edge-optimized custom domain names.

Security policy	TLS_1_0	TLS_1_2
TLS protocols
TLSv1.3	♦	♦
TLSv1.2	♦	♦
TLSv1.1	♦
TLSv1	♦
TLS ciphers
TLS_AES_128_GCM_SHA256	♦	♦
TLS_AES_256_GCM_SHA384	♦	♦
TLS_CHACHA20_POLY1305_SHA256	♦	♦
ECDHE-ECDSA-AES128-GCM-SHA256	♦	♦
ECDHE-ECDSA-AES128-SHA256	♦	♦
ECDHE-ECDSA-AES128-SHA	♦
ECDHE-ECDSA-AES256-GCM-SHA384	♦	♦
ECDHE-ECDSA-CHACHA20-POLY1305	♦	♦
ECDHE-ECDSA-AES256-SHA384	♦	♦
ECDHE-ECDSA-AES256-SHA	♦
ECDHE-RSA-AES128-GCM-SHA256	♦	♦
ECDHE-RSA-AES128-SHA256	♦	♦
ECDHE-RSA-AES128-SHA	♦
ECDHE-RSA-AES256-GCM-SHA384	♦	♦
ECDHE-RSA-CHACHA20-POLY1305	♦	♦
ECDHE-RSA-AES256-SHA384	♦	♦
ECDHE-RSA-AES256-SHA	♦
AES128-GCM-SHA256	♦
AES256-GCM-SHA384	♦	♦
AES128-SHA256	♦	♦
AES256-SHA	♦
AES128-SHA	♦
DES-CBC3-SHA	♦

Supported security policies, TLS protocol versions, and ciphers for Regional custom domains

The following table describes the security policies that can be specified for Regional custom domain names.

Security policy	TLS_1_0	TLS_1_2
TLS protocols
TLSv1.3	♦	♦
TLSv1.2	♦	♦
TLSv1.1	♦
TLSv1	♦
TLS ciphers
TLS_AES_128_GCM_SHA256	♦	♦
TLS_AES_256_GCM_SHA384	♦	♦
TLS_CHACHA20_POLY1305_SHA256	♦	♦
ECDHE-ECDSA-AES128-GCM-SHA256	♦	♦
ECDHE-RSA-AES128-GCM-SHA256	♦	♦
ECDHE-ECDSA-AES128-SHA256	♦	♦
ECDHE-RSA-AES128-SHA256	♦	♦
ECDHE-ECDSA-AES128-SHA	♦
ECDHE-RSA-AES128-SHA	♦
ECDHE-ECDSA-AES256-GCM-SHA384	♦	♦
ECDHE-RSA-AES256-GCM-SHA384	♦	♦
ECDHE-ECDSA-AES256-SHA384	♦	♦
ECDHE-RSA-AES256-SHA384	♦	♦
ECDHE-RSA-AES256-SHA	♦
ECDHE-ECDSA-AES256-SHA	♦
AES128-GCM-SHA256	♦	♦
AES128-SHA256	♦	♦
AES128-SHA	♦
AES256-GCM-SHA384	♦	♦
AES256-SHA256	♦	♦
AES256-SHA	♦

Supported TLS protocol versions and ciphers for private APIs

The following table describes the supported TLS protocol and ciphers for private APIs. Specifying a security policy for private APIs is not supported.

Security policy	TLS_1_2
TLS protocols
TLSv1.2	♦
TLS ciphers
ECDHE-ECDSA-AES128-GCM-SHA256	♦
ECDHE-RSA-AES128-GCM-SHA256	♦
ECDHE-ECDSA-AES128-SHA256	♦
ECDHE-RSA-AES128-SHA256	♦
ECDHE-ECDSA-AES256-GCM-SHA384	♦
ECDHE-RSA-AES256-GCM-SHA384	♦
ECDHE-ECDSA-AES256-SHA384	♦
ECDHE-RSA-AES256-SHA384	♦
AES128-GCM-SHA256	♦
AES128-SHA256	♦
AES256-GCM-SHA384	♦
AES256-SHA256	♦

OpenSSL and RFC cipher names

OpenSSL and IETF RFC 5246 use different names for the same ciphers. The following table maps the OpenSSL name to the RFC name for each cipher.

OpenSSL cipher name	RFC cipher name
TLS_AES_128_GCM_SHA256	TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384	TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256	TLS_CHACHA20_POLY1305_SHA256
ECDHE-RSA-AES128-GCM-SHA256	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ECDHE-RSA-AES128-SHA256	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
ECDHE-RSA-AES128-SHA	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
ECDHE-RSA-AES256-GCM-SHA384	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ECDHE-RSA-AES256-SHA384	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ECDHE-RSA-AES256-SHA	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
AES128-GCM-SHA256	TLS_RSA_WITH_AES_128_GCM_SHA256
AES256-GCM-SHA384	TLS_RSA_WITH_AES_256_GCM_SHA384
AES128-SHA256	TLS_RSA_WITH_AES_128_CBC_SHA256
AES256-SHA	TLS_RSA_WITH_AES_256_CBC_SHA
AES128-SHA	TLS_RSA_WITH_AES_128_CBC_SHA
DES-CBC3-SHA	TLS_RSA_WITH_3DES_EDE_CBC_SHA

Information about HTTP APIs and WebSocket APIs

For more information about HTTP APIs and WebSocket APIs, see Security policy for HTTP APIs in API Gateway and Security policy for WebSocket APIs in API Gateway.