Add example to enable mTlS for ssl listener in EMQX v5

Author: zmstone

en/202007/enable-two-way-ssl-for-emqx.md

@@ -1,4 +1,4 @@
-As a security protocol based on modern cryptographic public key algorithms, TLS/SSL can ensure the security of transmission in the computer communication network. EMQX has built-in support for TLS/SSL including one-way/two-ways authentication, the X.509 certificate, load balance SSL and many other security certifications. You can enable SSL/TLS for all protocols supported by EMQX, and can also configure HTTP API provided by EMQX to use TLS.
+As a security protocol based on modern cryptographic public key algorithms, TLS/SSL can ensure the security of transmission in the computer communication network. EMQX has built-in support for TLS/SSL including one-way/two-ways (mutual TLS, or mTLS) authentication, the X.509 certificate, load balance SSL and many other security certifications. You can enable SSL/TLS for all protocols supported by EMQX, and can also configure HTTP API provided by EMQX to use TLS.
 
 In the previous article, we've introduced how to [enable SSL/TLS one-way security connection for the EMQX](https://www.emqx.com/en/blog/emqx-server-ssl-tls-secure-connection-configuration-guide). This article will introduce how to enable SSL/TLS two-way security connection for [MQTT](https://www.emqx.com/en/mqtt-guide) in EMQX.
 
@@ -22,7 +22,7 @@ The following picture describes the process of the TLS/SSL handshake protocol. F
 
 
 
-## Why do we need SSL/TLS two-way certification
+## Why do we need SSL/TLS two-way (mTLS) certification
 
 The two-way certification is that a certificate is required for service and client during the connection authentication. Both parties need to perform authentication for ensuring that both sides involved in communication are trusted. Both parties share their public certificates, and then perform verification and confirmation based on the certificate. For some application scenarios that required high security, we need to enable two-way SSL/TLS authentication.
 
@@ -122,12 +122,35 @@ openssl x509 -req -days 3650 -in client.csr -CA ca.pem -CAkey ca.key -CAcreatese
 After preparing the server and client certificate, we can enable TLS/SSL two-way authentication in the EMQX.
 
 
-
 ## Enable and verify SSL/TLS two-way connection
 
-**In the EMQX, the default listening port of `mqtt:ssl` is 8883.**
+### EMQX v5 configuration
 
-### EMQX configuration
+```shell
+listeners.ssl.default {
+  bind = "0.0.0.0:8883"
+  ssl_options {
+    # PEM file containing the trusted CA (certificate authority) certificates that the listener uses to verify the authenticity of the client certificates.
+    # For one-way authentication, the file content can be empty.
+    cacertfile = "etc/certs/ca.pem"
+    # PEM file containing the SSL/TLS certificate chain for the listener.
+    # If the certificate is not directly issued by a root CA, the intermediate CA certificates should be appended after the listener certificate to form a chain.
+    certfile = "etc/certs/emqx.pem"
+    # PEM file containing the private key corresponding to the SSL/TLS certificate.
+    keyfile = "etc/certs/emqx.key"
+    # Set `verify_peer` to verify the authenticity of the client certificates. Must be set to 'verify_peer' for two-way authentication (mTLS).
+    # Set 'verify_none' to allow any client to connect, regardless of the client certificate.
+    verify = verify_peer
+    # If set to `true`, the handshake fails if the client does not have a certificate to send. Must be set to `true` for two-way authentication (mTLS).
+    # If set to `false`, it fails only if the client sends an invalid certificate (an empty certificate is considered valid). i.e. one-way authentication.
+    fail_if_no_peer_cert = true
+  }
+}
+```
+
+### EMQX v4 configuration
+
+**In the EMQX, the default listening port of `mqtt:ssl` is 8883.**
 
 Copy the file `emqx.pem`, `emqx.key` and `ca.pem` generated by OpenSSL tool into the directory `etc/certs/` of EMQX, and refer the following configuration to modify `emqx.conf`:
 
@@ -136,32 +159,23 @@ Copy the file `emqx.pem`, `emqx.key` and `ca.pem` generated by OpenSSL tool into
 ## Value: IP:Port | Port
 listener.ssl.external = 8883
 
-## Path to the file containing the user's private PEM-encoded key.
-## Value: File
+# PEM file containing the private key corresponding to the SSL/TLS certificate.
 listener.ssl.external.keyfile = etc/certs/emqx.key
 
-## NOTE: If emqx.pem is a certificate chain, please make sure the first certificate is the certificate for the server, but not a CA certificate.
-## Path to a file containing the user certificate.
-## Value: File
+# PEM file containing the SSL/TLS certificate chain for the listener.
+# If the certificate is not directly issued by a root CA, the intermediate CA certificates should be appended after the listener certificate to form a chain.
 listener.ssl.external.certfile = etc/certs/emqx.pem
 
-## Note: ca.pem is to hold the server's intermediate and root CA certificates. Other trusted CAs can be appended for client certificate validation.
-## Path to the file containing PEM-encoded CA certificates. The CA certificates
-## Value: File
+# PEM file containing the trusted CA (certificate authority) certificates that the listener uses to verify the authenticity of the client certificates.
+# For one-way authentication, the file content can be empty.
 listener.ssl.external.cacertfile = etc/certs/ca.pem
 
-## A server only does x509-path validation in mode verify_peer,
-## as it then sends a certificate request to the client (this
-## message is not sent if the verify option is verify_none).
-##
-## Value: verify_peer | verify_none
+# Set `verify_peer` to verify the authenticity of the client certificates.
+# Set `verify_none` to allow any client to connect, regardless of the client certificate.
 listener.ssl.external.verify = verify_peer
 
-## Used together with {verify, verify_peer} by an SSL server. If set to true,
-## the server fails if the client does not have a certificate to send, that is,
-## sends an empty certificate.
-##
-## Value: true | false
+# If set to `true`, the handshake fails if the client does not have a certificate to send. Must be set to `true` for two-way authentication (mTLS).
+# If set to `false`, it fails only if the client sends an invalid certificate (an empty certificate is considered valid). i.e. one-way authentication.
 listener.ssl.external.fail_if_no_peer_cert = true
 ```
 

zh/202007/enable-two-way-ssl-for-emqx.md

@@ -130,43 +130,56 @@ openssl x509 -req -days 3650 -in client.csr -CA ca.pem -CAkey ca.key -CAcreatese
 
 ## SSL/TLS 双向连接的启用及验证
 
-**在 EMQX 中 `mqtt:ssl` 的默认监听端口为 8883。**
+### EMQX v5 配置
+
+```shell
+listeners.ssl.default {
+  bind = "0.0.0.0:8883"
+  ssl_options {
+    # PEM 格式的文件，用于保存一个或多个用于签发客户端证书的根证书。TLS 握手阶段 EMQX 会使用这些证书来验证客户端证书。
+    # 如果不想要对客户端证书进行验证 （即：单向认证），则该文件内容可以为空。
+    cacertfile = "etc/certs/ca.pem"
+    # PEM 格式的服务端证书链文件。
+    # 如果证书链中包含中间 CA 证书，需要将中间 CA 证书附加到服务端证书后以形成证书链。
+    certfile = "etc/certs/emqx.pem"
+    # PEM 格式的服务端私钥文件。
+    keyfile = "etc/certs/emqx.key"
+    # 设置 `verify_peer` 以验证客户端证书。
+    # 设置 `verify_none` 允许任何客户端连接，无论客户端证书如何。
+    verify = verify_peer
+    # 如果设置为 `true`，则客户端未发送证书时，连接将失败，双向认证必选。
+    # 如果设置为 `false`，则仅在客户端发送无效证书时失败（空证书被视为有效），即：单向认证。
+    fail_if_no_peer_cert = true
+  }
+}
+
+
+### EMQX v4 配置
 
-### EMQX 配置
+**在 EMQX 中 `mqtt:ssl` 的默认监听端口为 8883。**
 
 将前文中通过 OpenSSL 工具生成的 `emqx.pem`、`emqx.key` 及 `ca.pem` 文件拷贝到 EMQX 的 `etc/certs/` 目录下，并参考如下配置修改 `emqx.conf`：
 
 ```shell
-## listener.ssl.$name is the IP address and port that the MQTT/SSL
-## Value: IP:Port | Port
 listener.ssl.external = 8883
 
-## Path to the file containing the user's private PEM-encoded key.
-## Value: File
+# PEM 格式的服务端私钥文件。
 listener.ssl.external.keyfile = etc/certs/emqx.key
 
-## 注意：如果 emqx.pem 是证书链，请确保第一个证书是服务器的证书，而不是 CA 证书。
-## Path to a file containing the user certificate.
-## Value: File
+# PEM 格式的服务端证书链文件。
+# 如果证书链中包含中间 CA 证书，需要将中间 CA 证书附加到服务端证书后以形成证书链。
 listener.ssl.external.certfile = etc/certs/emqx.pem
 
-## 注意：ca.pem 用于保存服务器的中间 CA 证书和根 CA 证书。可以附加其他受信任的 CA，用来进行客户端证书验证。
-## Path to the file containing PEM-encoded CA certificates. The CA certificates
-## Value: File
+# PEM 格式的文件，用于保存一个或多个用于签发客户端证书的根证书。TLS 握手阶段 EMQX 会使用这些证书来验证客户端证书。
+# 如果不想要对客户端证书进行验证 （即：单向认证），则该文件内容可以为空。
 listener.ssl.external.cacertfile = etc/certs/ca.pem
 
-## A server only does x509-path validation in mode verify_peer,
-## as it then sends a certificate request to the client (this
-## message is not sent if the verify option is verify_none).
-##
-## Value: verify_peer | verify_none
+# 设置 `verify_peer` 以验证客户端证书。
+# 设置 `verify_none` 允许任何客户端连接，无论客户端证书如何。
 listener.ssl.external.verify = verify_peer
 
-## Used together with {verify, verify_peer} by an SSL server. If set to true,
-## the server fails if the client does not have a certificate to send, that is,
-## sends an empty certificate.
-##
-## Value: true | false
+# 如果设置为 `true`，则客户端未发送证书时，连接将失败，双向认证必选。
+# 如果设置为 `false`，则仅在客户端发送无效证书时失败（空证书被视为有效），即：单向认证。
 listener.ssl.external.fail_if_no_peer_cert = true
 ```