Skip to content

update(network): Add session_tickets for TLS 1.3 (6.1.1) #3328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Meggielqk wants to merge 1 commit into
base: release-6.1
Choose a base branch
from
Open

update(network): Add session_tickets for TLS 1.3 (6.1.1) #3328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions en_US/network/emqx-mqtt-tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,20 @@ Choose the method that best fits your deployment and operational model.

- **Force Verify Peer Certificate**: Only applicable when **Verify Peer** is enabled. For one-way authentication, this option should remain disabled.

- **Session Tickets**: Enable TLS 1.3 session resumption. Clients can reuse a previously established TLS session during reconnection by presenting encrypted session tickets issued by the server, avoiding a full TLS handshake and reducing latency and CPU usage.

- **`disabled`**: Disable session tickets (default). A full TLS handshake is performed for every connection.
- **`stateless`**: Enable stateless session tickets. The server does not store session state, improving reconnection performance. TLS client certificate information is not available after session resumption, making this option suitable when certificate-based authentication or authorization is not required.
- **`stateless_with_cert`**: Enable stateless session tickets with certificate information included. Certificate information remains available after session resumption, suitable for certificate-based authentication (such as mTLS), but with slightly increased network bandwidth usage.

::: tip Note

Session tickets are supported only with TLS 1.3 and only in stateless mode to ensure scalability in clustered environments. EMQX does not support stateful session resumption for TLS 1.2.

EMQX also does not support client early data (0-RTT). Clients must wait until the TLS handshake is complete before sending MQTT data.

:::

- **Certificate Source**: Choose how server certificates are provided:

- **Enter Manually**: Use traditional path-based certificates. Configure the following fields:
Expand All @@ -81,11 +95,17 @@ Choose the method that best fits your deployment and operational model.
When multiple certificates are configured, EMQX selects the certificate dynamically based on the client’s SNI. If no SNI matches, the first certificate in the list is used as the default.

- **SSL Versions**: All TLS/DTLS versions are supported. The default values are `tlsv1.3` and `tlsv1.2`. If PSK cipher suites are used for PSK authentication, make sure to configure `tlsv1.2` , `tlsv1.1` and `tlsv1` here. For more information on PSK authentication, see [Enable PSK Authentication](./psk-authentication.md).

- **Cipher Suites**: Optional. Specify allowed cipher suites if required.

- **CACert Depth**: The maximum allowed depth of the certificate chain. Default value: `10`.

- **Key File Passphrase**: Password for the private key file, if encrypted.

- **Enable OCSP Stapling**: Disabled by default. Enable this option if you need to check certificate revocation status via OCSP. See [OCSP Stapling](./ocsp.md).

- **Enable CRL Check**: Disabled by default. Enable this option to verify whether certificates have been revoked. See [CRL Check](./crl.md).

4. After completing the configuration, click **Update** to apply the changes.

### Enable via Configuration File
Expand Down
22 changes: 21 additions & 1 deletion zh_CN/network/emqx-mqtt-tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,23 @@ EMQX 同时支持传统的基于文件路径的证书管理方式，以及托管
3. 配置以下 SSL/TLS 相关选项：

- **双向认证**：默认关闭（单向认证）。关闭时，EMQX 不会校验客户端证书。

- **强制验证对端证书**：仅在开启**双向认证**时生效。对于单向认证场景，该选项应保持关闭。

- **会话票据**：用于启用 TLS 1.3 的会话恢复功能。启用后，客户端可在重连时使用服务器签发的加密会话票据恢复之前的 TLS 会话，从而避免完整握手，降低连接延迟和 CPU 开销。

- `disabled`：禁用（默认值）。每次客户端连接或重连时都会执行完整的 TLS 握手。
- `stateless`：启用无状态会话票据。客户端可使用会话票据恢复 TLS 会话，服务器无需保存会话状态，可提升重连性能。但会话恢复后无法获取 TLS 客户端证书信息，适用于不依赖证书进行认证或授权的场景。
- `stateless_with_cert`：启用携带证书信息的无状态会话票据。会话恢复后仍可获取证书信息。适用于基于证书进行认证或访问控制（如 mTLS）的场景，但会略微增加网络带宽开销。

::: tip 注意

会话票据仅适用于 TLS 1.3，且仅支持无状态（stateless）机制，以保证在集群环境中的可扩展性。EMQX 不支持 TLS 1.2 的有状态会话恢复。

此外，EMQX 不支持客户端早期数据（0-RTT），客户端必须在 TLS 握手完成后才能发送 MQTT 数据。

:::

- **证书来源**：选择服务器证书的提供方式：
- **手动输入**：使用传统的基于路径的证书文件。需要配置以下字段：

Expand All @@ -81,12 +96,17 @@ EMQX 同时支持传统的基于文件路径的证书管理方式，以及托管

- EMQX 会根据客户端发送的 SNI 动态选择证书。
- 若未匹配到 SNI，则使用列表中的第一个证书作为默认证书。

- **SSL 版本**：支持所有 TLS/DTLS 版本。默认设置为 `tlsv1.3` 和 `tlsv1.2`。如果 PSK 验证中使用了 PSK 密码套件，确保在此处设置 `tlsv1.2` ， `tlsv1.1` 和 `tlsv1`。更多关于 PSK 的内容请参阅 [PSK 认证](./psk-authentication.md)。

- **加密套件**：用于指定允许使用的加密套件。

- **CA 证书深度**：证书链允许的最大深度，默认值为 `10`。

- **密钥文件密码**：如果密钥文件由密码保护，则需要输入密码。

- **启用 OCSP Stapling**: 默认为不启用；如需获取 X.509 数字证书的撤销状态，可以点击切换开关。具体可参阅 [OCSP Stapling](./ocsp.md)。

- **启用 CRL 检查**：默认为不启用；如需设置证书吊销列表（CRL）检查功能，可以点击切换开关。具体可参阅 [CRL 检查](./crl.md)。

4. 配置完成后，点击**更新**以应用更改。
Expand Down