TLS
Hertz 支持 TLS 安全传输,帮助用户实现了数据的保密性和完整性。
如果有 TLS 的需求,请使用 go net 网络库。netpoll 正在实现对 TLS 的支持。
在 tls.Config
中,服务端和客户端都可使用的参数如下:
参数名 | 介绍 |
---|---|
Certificates | 用于添加证书,可以配置多个证书。 两端自动选择第一个证书进行验证。 |
VerifyPeerCertificate | 用于验证对端证书。 在任意一端证书验证后调用。 |
VerifyConnection | 在两端证书均验证后,进行 TLS 连接验证。 |
NextProtos | 用于设置支持的应用层协议。 |
CipherSuites | 用于协商加密策略,支持 TLS 1.0-1.2。 |
MaxVersion | 用于设置 TLS 支持的最大版本,目前是 1.3。 |
服务端
Hertz 在 server
包提供了 WithTLS
Option 用于配置 TLS 服务。但是目前 Hertz 只有 标准网络库 支持 TLS,Netpoll 网络库的支持还在路上。
WithTLS
的 Transporter
默认设置为标准库的 Transporter
。
参数
在 tls.Config
中,除了上述基本参数,服务端可以配置的参数如下:
参数名 | 介绍 |
---|---|
GetCertificate | 基于客户端 SNI 信息或证书集为空时,返回证书。 |
GetClientCertificate | 用于服务端要求验证客户端证书时,返回客户端证书。 |
GetConfigForClient | 当服务端从客户端接收了 ClientHello 后,返回配置信息。 如果返回的是非空的配置信息,将会被用于这次 TLS 连接。 |
ClientAuth | 用于客户端验证策略设置,默认为 NoClientCert 。 |
ClientCAs | 当启用了 ClientAuth , 用于验证客户端证书的真实性。 |
服务器端 TLS 主要流程:
- 载入根证书,用于验证客户端的真实性。
- 载入服务器证书,用于发送给客户端以验证服务器真实性。
- 配置
tls.Config
。 - 使用
WithTLS
配置服务端 TLS,默认使用标准库的 Transporter。
示例代码
本次示例中的 ca.key
、ca.crt
、server.key
和 server.crt
均通过 openssl 生成。
首先生成 CA 的私钥和证书,命令如下:
通过 CA 签名,生成服务端的私钥和证书,命令如下:
服务端示例代码:
完整用法示例详见 example 。
客户端
参数
在 tls.Config
中,除了上述基本参数,客户端可以配置的参数如下:
参数名 | 介绍 |
---|---|
ServerName | 根据返回的证书信息验证主机名。 |
InsecureSkipVerify | 用于客户端是否开启服务端的证书验证。 |
RootCAs | 用于客户端验证服务端的证书。 |
客户端 TLS 主要流程:
- 载入根证书,用于验证服务器端的真实性。
- 载入客户证书,用于发送给服务器端以验证客户端的真实性。
- 配置
tls.Config
。 - 使用
WithTLS
配置客户端 TLS,默认使用标准库的 Dialer。
示例代码
通过 CA 签名,生成客户端的私钥和证书,命令如下:
客户端示例代码:
完整用法示例详见 example 。
Autotls 中间件
Hertz 提供了 autotls 扩展适配 Let’s Encrypt ,方便用户进行 TLS 服务自动配置。
安装
配置
NewTlsConfig
autotls
扩展提供了 NewTlsConfig
用于帮助用户使用一行代码支持 LetsEncrypt HTTPS servers。
NewTlsConfig 函数签名如下:
示例代码:
RunWithContext
autotls
扩展提供了 RunWithContext
用于帮助用户使用一行代码支持 LetsEncrypt HTTPS servers 的同时能够让服务优雅关机。
RunWithContext 函数签名如下:
示例代码:
NewServerWithManagerAndTlsConfig
autotls
扩展提供了 NewServerWithManagerAndTlsConfig
用于帮助用户自动证书管理和 TLS 配置。
NewServerWithManagerAndTlsConfig 函数签名如下:
示例代码:
完整用法示例详见 example 。
注意
Client 报错 not support tls
Hertz 默认使用了 netpoll
作为网络库并且目前 netpoll
不支持 TLS。使用 TLS 需要切换到标准网络库,代码如下: