Amazon API Gateway
Developer Guide

Choose a Minimum TLS Version for a Custom Domain in API Gateway

For greater security, you can choose a minimum Transport Layer Security (TLS) protocol version to be enforced for your Amazon API Gateway custom domain by setting a security policy in the API Gateway console, AWS CLI, or AWS SDKs.

A security policy is a predefined combination of minimum TLS version and cipher suite offered by Amazon 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

How to Specify a Minimum TLS Protocol Version for Custom Domains in API Gateway

When you create a custom domain, you specify the security policy for it. For more information about security policies, see the tables in the following sections.

The following sections describe how to create a custom domain name, including specifying the minimum TLS version in the API Gateway console and CLI:

You can change the security policy by updating the domain name settings. To change the minimum TLS version, use one of the following commands, specifying the new TLS version (TLS_1_0 or TLS_1_2) in the securityPolicy parameter. Allow up to 60 minutes for the update to be completed.

Supported Security Policies, TLS Protocol Versions, and Ciphers for Edge-Optimized API Endpoints in API Gateway

The following table lists the protocols and ciphers that API Gateway can use for each security policy for edge-optimized APIs.

Security Policy
TLS-1-0 TLS-1-2
SSL/TLS Protocols Supported
TLSv1.2
TLSv1.1
TLSv1
SSLv3
Ciphers Supported
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
ECDHE-RSA-AES128-SHA
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA
AES128-GCM-SHA256
AES256-GCM-SHA384
AES128-SHA256
AES256-SHA
AES128-SHA
DES-CBC3-SHA
RC4-MD5

Supported SSL/TLS Protocols and Ciphers for Regional, Private, and WebSocket API Endpoints in API Gateway

The following table describes the security policies that can be specified for regional, private, and WebSocket API endpoints.

Note

For private and WebSocket APIs, only TLS-1-2 can be specified.

Security Policy TLS-1-0 TLS-1-2
TLS Protocols

Protocol-TLSv1

Protocol-TLSv1.1

Protocol-TLSv1.2

TLS Ciphers

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

DES-CBC3-SHA

OpenSSL and RFC Cipher Names

OpenSSL and IETF RFC 5246, The Transport Layer Security (TLS) Protocol Version 1.2, 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

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

RC4-MD5

TLS_RSA_WITH_RC4_128_MD5