# SSL/TLS
当接收 MQTT 客户端连接或连接到外部资源时,EMQX 支持以 SSL/TLS 的方式 建立安全的连接。
# MQTT SSL 监听器
# TLS 双向认证
如果要为 MQTT 客户端添加 TLS 认证,仅需要添加一个 ssl
类型的监听器,并设置 其 ssl_options.verify = verify_peer
来验证客户端证书。
默认的 ssl
MQTT 监听器运行在 8883 端口:
listeners.ssl.default {
bind = "0.0.0.0:8883"
access_rules = [
"allow all"
]
proxy_protocol = false
proxy_protocol_timeout = 3s
ssl_options.keyfile = "etc/certs/key.pem"
ssl_options.certfile = "etc/certs/cert.pem"
ssl_options.cacertfile = "etc/certs/cacert.pem"
# to verify client certs
ssl_options.verify = verify_peer
ssl_options.versions = ["tlsv1.3", "tlsv1.2", "tlsv1.1", "tlsv1"]
tcp.backlog = 1024
tcp.buffer = 4KB
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
提示
key.pem
,cert.pem
和 cacert.pem
是由 EMQX Broker 生成的自签名证书。 因此,如果需支持 SSL 双向认证,需要把 etc/certs/cacert.pem
配置到 MQTT 客户端上。
注意
生产环境请替换默认证书以确保安全。
# PSK 认证
除常规的 SSL 配置外,EMQX 还提供了对 PSK (Pre-Shared-Key) (opens new window) 的支持。
为开启 PSK 认证,需要先在 psk_authentication
中预先配置密钥:
psk_authentication {
## Whether to enable the PSK feature.
enable = true
## If init file is specified, emqx will import PSKs from the file
## into the built-in database at startup for use by the runtime.
##
## The file has to be structured line-by-line, each line must be in
## the format: <PSKIdentity>:<SharedSecret>
init_file = "data/init.psk"
## Specifies the separator for PSKIdentity and SharedSecret in the init file.
## The default is colon (:)
separator = ":"
## The size of each chunk used to import to the built-in database from psk file
## chunk_size = 50
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
以上的配置,表明预设密钥存放在 data/init.psk
文件里,其格式为:
myclient1:8c701116e9127c57a99d5563709af3deaca75563e2c4dd0865701ae839fb6d79
myclient2:d1e617d3b963757bfc21dad3fea169716c3a2f053f23decaea5cdfaabd04bfc4
2
然后,需要将 ssl
监听器的 cipher
修改为支持 PSK 的加密套件:
listeners.ssl.default {
...
ssl_options.versions = ["tlsv1.2"]
ssl_options.ciphers = "RSA-PSK-AES256-CBC-SHA384,RSA-PSK-AES128-GCM-SHA256,RSA-PSK-AES128-CBC-SHA256,RSA-PSK-AES256-CBC-SHA,RSA-PSK-AES128-CBC-SHA,RSA-PSK-RC4-SHA,RSA-PSK-DES-CBC3-SHA"
...
}
2
3
4
5
6
提示
PSK 仅支持 tlsv1.2 及以下的版本。
# 使用 SSL 连接外部资源
除了允许接收一个双向 SSL 的 MQTT 客户端,EMQX 还提供了以 SSL 的方式访问外部资源。 例如,通过 HTTPS 的方式访问一个 Web 服务器:
在创建任何对外部资源的连接时,可以选择启用 TLS 并配置其 SSL 客户端证书。其中:
- 当启用 验证服务证书 后,必须填写 CA Cert 字段来验证服务器证书的合法性。
- 当服务器需要验证客户端证书时,则必须填写 TLS Cert 和 TLS Key。
- SNI 即 Server Name Indication,表示是否验证服务器域名和证书是否一致;为空时表示不验证。
此外,在 emqx.conf
配置文件中同样完成该配置:
authentication {
url = "https://127.0.0.1:8080"
backend = "http"
...
ssl {
enable = true
cacertfile = "etc/certs/cacert.pem"
certfile = "etc/certs/cert.pem"
keyfile = "etc/certs/key.pem"
## verify_peer 表示,开启验证服务器证书
verify = verify_peer
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# SSL 配置项
完整的 SSL 监听器配置参考:broker:listener_ssl_opts
SSL 客户端配置参考:broker:ssl_client_opts
# Ciphers
无论是 SSL 监听器或 SSL 客户端,它们可配置的 ciphers
为:
# TLS 1.3:
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_CCM_SHA256
TLS_AES_128_CCM_8_SHA256
# TLS 1.2 and below:
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384
ECDH-ECDSA-AES256-GCM-SHA384
ECDH-RSA-AES256-GCM-SHA384
ECDH-ECDSA-AES256-SHA384
ECDH-RSA-AES256-SHA384
DHE-DSS-AES256-GCM-SHA384
DHE-DSS-AES256-SHA256
AES256-GCM-SHA384
AES256-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
ECDH-ECDSA-AES128-GCM-SHA256
ECDH-RSA-AES128-GCM-SHA256
ECDH-ECDSA-AES128-SHA256
ECDH-RSA-AES128-SHA256
DHE-DSS-AES128-GCM-SHA256
DHE-DSS-AES128-SHA256
AES128-GCM-SHA256
AES128-SHA256
ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES256-SHA
DHE-DSS-AES256-SHA
ECDH-ECDSA-AES256-SHA
ECDH-RSA-AES256-SHA
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
DHE-DSS-AES128-SHA
ECDH-ECDSA-AES128-SHA
ECDH-RSA-AES128-SHA
# PSK ciphers:
RSA-PSK-AES256-GCM-SHA384
RSA-PSK-AES256-CBC-SHA384
RSA-PSK-AES128-GCM-SHA256
RSA-PSK-AES128-CBC-SHA256
RSA-PSK-AES256-CBC-SHA
RSA-PSK-AES128-CBC-SHA
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
← 黑名单 Prometheus →