Configure the TLS version

Prerequisites

RAM users must have the following permissions: oss:PutTLSVersion and oss:GetTLSVersion. For more information, see Grant a custom policy to a RAM user.

TLS versions

TLS supports four versions: 1.0, 1.1, 1.2, and 1.3. The following table describes the use cases and supported browsers for each version.

Protocol	Description	Use cases	Supported browsers
TLS 1.0	This version uses encryption algorithms such as RSA, DES, and 3DES. TLS 1.0 has known security vulnerabilities and is susceptible to attacks such as BEAST and POODLE. It no longer provides adequate protection for modern network connections and does not meet PCI DSS compliance standards.	Due to its security vulnerabilities, TLS 1.0 is no longer widely recommended. In most cases, we recommend that you upgrade to a more secure TLS version.	IE 6+ Chrome 1+ Firefox 2+
TLS 1.1	This version improves security by addressing some known vulnerabilities and adding support for stronger encryption algorithms, such as AES, RSA, and SHA-256.	Suitable for environments that require a relatively high level of security but do not require the latest TLS features.	IE 11+ Chrome 22+ Firefox 24+ Safari 7+
TLS 1.2	This version further enhances security and adds new features, such as Server Name Indication (SNI) and the extended handshake protocol. Supported encryption algorithms include AES-GCM, AES-CBC, and ECDHE.	Suitable for most common secure communication scenarios, including web applications, e-commerce websites, email, and virtual private networks (VPNs).	IE 11+ Chrome 30+ Firefox 27+ Safari 7+
TLS 1.3	This version introduces significant improvements in security, performance, and privacy. It removes insecure cryptographic algorithms, adds more robust key exchange and encryption algorithms, reduces handshake latency, and provides better forward secrecy and authentication mechanisms.	Suitable for scenarios that have strict security requirements and require better performance and privacy, such as financial institutions, large internet companies, and government agencies.	Chrome 70+ Firefox 63+

Usage notes

Avoid configuring a bucket to allow only TLS 1.0 or TLS 1.1. At a minimum, your configuration should include the mainstream version, TLS 1.2.
If TLS Version Management is not enabled, TLS 1.0, 1.1, and 1.2 are supported by default, but TLS 1.3 is not. After you enable TLS Version Management, you can select from TLS 1.0, 1.1, 1.2, and 1.3. The first time you configure the TLS version in the OSS console, TLS 1.2 is selected by default as the mainstream version. If TLS 1.2 is not selected, some mainstream clients may fail to access OSS.
Downgrading the TLS version (for example, from TLS 1.2 to TLS 1.1 or TLS 1.0) or disabling TLS Version Management may introduce security and compliance risks. Proceed with caution.
Before you disable a TLS version, verify that no clients rely exclusively on that version for connections.

Procedure

OSS console

Log on to the OSS console.
In the left-side navigation pane, click Buckets, and then click the name of the target bucket.
In the left-side navigation pane, choose Content Security > TLS Version Management.

On the TLS Version Management page, configure the following parameters.

Parameter	Description
TLS Version Management	Enable TLS Version Management.
TLS Cipher Suite	A cipher suite is a specific combination of cryptographic algorithms for data encryption, identity authentication, and integrity protection. Each cipher suite typically includes a key exchange algorithm (such as RSA or ECDHE), an authentication algorithm (such as ECDSA), a symmetric encryption algorithm (such as AES), and a message authentication code algorithm (such as SHA256). OSS supports the following three types of cipher suites: All Cipher Suites (Default): Offers high compatibility but lower security. Strong Cipher Suite: Offers higher security but lower compatibility. List of strong cipher suites ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-RSA-CHACHA20-POLY1305 ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-CCM8 ECDHE-ECDSA-AES128-CCM ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-CCM8 ECDHE-ECDSA-AES256-CCM ECDHE-ECDSA-ARIA256-GCM-SHA384 ECDHE-ARIA256-GCM-SHA384 ECDHE-ECDSA-ARIA128-GCM-SHA256 ECDHE-ARIA128-GCM-SHA256 TLS_AES_256_GCM_SHA384 TLS_AES_128_GCM_SHA256 TLS_CHACHA20_POLY1305_SHA256 Custom Cipher Suite: Allows for high customization, enabling you to select the most suitable algorithm combination based on your specific security policy. For example, you can choose stronger encryption algorithms (such as AES-256 instead of AES-128) or more secure key exchange mechanisms (such as ECDHE instead of RSA). You can set a custom cipher suite only if the TLS version is set to 1.2 or 1.3. Custom cipher suites for TLS 1.2 ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-RSA-CHACHA20-POLY1305 ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-CCM8 ECDHE-ECDSA-AES128-CCM ECDHE-ECDSA-AES128-SHA256 ECDHE-RSA-AES128-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-CCM8 ECDHE-ECDSA-AES256-CCM ECDHE-ECDSA-AES256-SHA384 ECDHE-RSA-AES256-SHA384 ECDHE-ECDSA-ARIA256-GCM-SHA384 ECDHE-ARIA256-GCM-SHA384 ECDHE-ECDSA-ARIA128-GCM-SHA256 ECDHE-ARIA128-GCM-SHA256 ECDHE-ECDSA-CAMELLIA256-SHA384 ECDHE-RSA-CAMELLIA256-SHA384 ECDHE-ECDSA-CAMELLIA128-SHA256 ECDHE-RSA-CAMELLIA128-SHA256 AES256-GCM-SHA384 AES256-CCM8 AES256-CCM ARIA256-GCM-SHA384 AES128-GCM-SHA256 AES128-CCM8 AES128-CCM ARIA128-GCM-SHA256 Custom cipher suites for TLS 1.3 TLS_AES_256_GCM_SHA384 TLS_AES_128_GCM_SHA256 TLS_CHACHA20_POLY1305_SHA256
Allowed TLS Version	Select the TLS versions to allow. For more information about the use cases and descriptions for each TLS version, see TLS versions.

Click Save, and then click OK in the confirmation dialog box.

The configuration takes effect within 30 minutes.

ossutil CLI

Use the ossutil command-line tool to enable or disable TLS Version Management. For information about how to install ossutil, see Install ossutil.

The following example shows how to enable TLS Version Management for the bucket examplebucket and set the TLS versions to TLSv1.2 and TLSv1.3.
```
ossutil api put-bucket-https-config --bucket examplebucket --https-configuration "{\"TLS\":{\"Enable\":\"true\",\"TLSVersion\":[\"TLSv1.2\",\"TLSv1.3\"]}}"
```
For more information about this command, see put-bucket-https-config.
The following example shows how to obtain the TLS version settings for the bucket examplebucket.
```
ossutil api get-bucket-https-config --bucket examplebucket
```
For more information about this command, see get-bucket-https-config.

API reference

These operations use REST APIs. For highly customized applications, you can make REST API requests directly, which requires you to write the signature calculation code manually. For more information, see PutBucketHttpsConfig and GetBucketHttpsConfig.

FAQ

Check current TLS version

If the client does not specify a TLS version, run the following command to determine the version negotiated between the client and server.

openssl s_client -connect <bucket>.<endpoint>:443 -servername <bucket>.<endpoint>

The following table describes the parameters in the command.

Parameter	Description
bucket	The name of your OSS bucket.
endpoint	The public endpoint, internal endpoint, or custom domain name.

You can find the TLS version in the command output.

The value of the Protocol field in the response is the current TLS version. The following is a sample response:

New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES128-GCM-SHA256
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES128-GCxxx
    Session-ID: DF6AF8834A5BE3E9EDCxxx
    Session-ID-ctx:
    Master-Key: 0C25A19D6E9E3BDEC86B417125AEC1FFA85xxx
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    TLS session ticket lifetime hint: 300 (seconds)
    TLS session ticket:

Verify TLS configuration

To verify that your bucket is correctly configured to allow only TLS 1.2, check for the following behaviors:

A client can access the server when the client explicitly uses TLS 1.2.

openssl s_client -connect <bucket>.<endpoint>:443 -servername <bucket>.<endpoint> -tls1_2

The following table describes the parameters in the command.

Parameter	Description
bucket	The name of your OSS bucket.
endpoint	The public endpoint, internal endpoint, or custom domain name.

Sample response:

SSL handshake has read 5779 bytes and written 470 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES128-GCM-SHA256
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES128-Gxxx
    Session-ID: 6F487389CA287BAFD2xxx
    Session-ID-ctx:
    Master-Key: 620777CB36570132F9xxx
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    TLS session ticket lifetime hint: 300 (seconds)

A client can access the server when the client does not specify a TLS version (but the client supports TLS 1.2).

openssl s_client -connect <bucket>.<endpoint>:443 -servername <bucket>.<endpoint>

Sample response:

SSL handshake has read 5779 bytes and written 470 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES128-GCM-SHA256
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES128-Gxxx
    Session-ID: 6F487389CA287BAFD2xxx
    Session-ID-ctx:
    Master-Key: 620777CB36570132F9xxx
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    TLS session ticket lifetime hint: 300 (seconds)

The server rejects connections from clients that specify a TLS version other than TLS 1.2 (for example, TLS 1.1).

openssl s_client -connect <bucket>.<endpoint>:443 -servername <bucket>.<endpoint> -tls1_1

Sample response:

[root@i-xxx xxx ~]# openssl s_client -connect xxx.oss-cn-hangzhou.aliyuncs.com:443 -servername xxx.oss-cn-hangzhou.aliyuncs.com -tls1_1
CONNECTED(00000003)
140293333579664:error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version:s3_pkt.c:1493:SSL alert number 70
140293333579664:error:1409E0E5:SSL routines:ssl3_write_bytes:ssl handshake failure:s3_pkt.c:659:
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 0 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.1
    Cipher    : 0000
    Session-ID:
    Session-ID-ctx:
    Master-Key:
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    Start Time: 1692262610
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
---