mTLS 配置教程:Envoy 1.30 与 Spring Boot 3.2 双向认证落地与排错
mTLS 配置教程的核心是让服务端在 TLS 握手时主动发送 CertificateRequest 并校验客户端证书;Envoy 1.30 用 require_client_certificate: true,Spring Boot 3.2 用 server.ssl.client-auth=need,二者都需把 CA 证书放入 validation_context 或 truststore。 证书扩展要写对:客户端证书必须含 extendedKeyUsage=clientAuth,服务端证书含 serverAuth;SAN 建议用 URI:spiffe://acme.internal/payment 便于服务身份校验。 用 openssl s_client -connect host:8443 -cert client.crt -key client.key -CAfile ca.crt -tls1_3 验证,成功输出 Verification: OK 与 Protocol version: TLSv1.3;不带证书应看到 alert certificate required(TLS 1.3 alert 116)。 Envoy 侧看 /stats 中 listener.*.ssl.handshake 与 ssl.fail_verify_no_cert;Spring Boot 侧看 javax.net.ssl.SSLHandshakeException: Empty client certificate chain。 客户端证书有效期建议 90 天,RSA 3072 或 ECDSA P-256;轮换用双证书并行 7 天,避免一次性替换导致 5xx。
mTLS 配置教程先讲根因:单向 TLS 到底缺了哪一步,握手为什么会失败?
很多人第一次配 mTLS 会卡在同一个地方:证书都装好了,客户端一连就断。根因往往不是“没配证书”,而是单向 TLS 的握手里,服务端从来不发出那一条 CertificateRequest。据 RFC 8446 §4.4.2,TLS 1.3 中只有服务端显式请求客户端证书时,才会在 EncryptedExtensions 之后发送 CertificateRequest;客户端收到后才回送 Certificate 与 CertificateVerify。少了这一条消息,客户端证书永远不会出现在链路上。
| 握手消息(TLS 1.3) | 单向 TLS | mTLS |
|---|---|---|
| ClientHello / ServerHello | 发送 | 发送 |
| CertificateRequest | 不发送 | 服务端发送 |
| Certificate(服务端) | 发送 | 发送 |
| Certificate(客户端) | 无 | 回送完整链 |
| CertificateVerify(客户端) | 无 | 用私钥签名握手摘要 |
| Finished | 客户端直接发 | 双方互验通过后发 |
两个框架把这个“开关”默认关掉了:Envoy 1.30 的 DownstreamTlsContext.require_client_certificate 默认 false,Spring Boot 3.2 的 server.ssl.client-auth 默认 none。据 Envoy v3 API 文档,只有当它或 validation_context 存在时,下游监听器才会向客户端索要证书。
# Envoy 1.30 最小 mTLS 下游配置(片段,挂在 filter_chains[].transport_socket)
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true # 默认 false;不写这一行服务端不会发 CertificateRequest
common_tls_context:
tls_params:
tls_minimum_protocol_version: TLSv1_3
tls_certificates:
- certificate_chain: { filename: /etc/envoy/server.crt }
private_key: { filename: /etc/envoy/server.key }
validation_context:
trusted_ca: { filename: /etc/envoy/clients-ca-bundle.crt } # 必须是完整 CA 链,只有 leaf 会校验失败
match_typed_subject_alt_names:
- san_type: DNS
matcher: { exact: "svc-a.internal" } # SAN 不匹配同样握手失败
# Spring Boot 3.2 application.yml
server:
ssl:
enabled: true
client-auth: need # 默认 none;need=强制,want=请求但不强制(适合灰度期)
key-store: classpath:server.p12
key-store-password: changeit
key-store-type: PKCS12
trust-store: classpath:clients-truststore.p12 # 用于校验客户端证书链,缺省则校验必然失败
trust-store-password: changeit
trust-store-type: PKCS12
enabled-protocols: TLSv1.3
排错第一步是分清方向。客户端报 tlsv13 alert certificate required,说明服务端要了证书、客户端没发;服务端报 Empty client certificate chain,则是客户端发了空链,或 truststore 没加载成功。用下面两条命令即可复现并定位:
# 不带客户端证书:预期复现 certificate required
openssl s_client -connect api.example.com:8443 -servername api.example.com -tls1_3 </dev/null
# 带客户端证书与 CA 链:预期握手成功
openssl s_client -connect api.example.com:8443 -cert client.crt -key client.key
-CAfile ca-bundle.crt -tls1_3 </dev/null
# 检查 EKU:必须出现 TLS Web Client Authentication
openssl x509 -in client.crt -noout -text | grep -A1 "Extended Key Usage"
第二类高频坑是证书内容本身:extendedKeyUsage 缺 clientAuth(据 CA/Browser Forum 基线要求,服务端证书通常只签 serverAuth)、SAN 与服务端校验规则不一致、以及客户端只发 leaf 而未带中间 CA。mTLS 只解决传输层“你是谁”,不解决“你能做什么”——服务间调用仍应在证书身份之上叠加 RBAC 或 OPA 策略。它最适合 API 网关到后端、Kubernetes 集群外服务互调、IoT 设备接入和零信任内网;面向普通浏览器访客的站点通常不必强制客户端证书,否则用户体验与证书分发成本都会失控。
mTLS 配置教程的证书设计:根 CA、服务端证书、客户端证书各要哪些扩展?
证书设计决定 mTLS 能不能跑通。先把三张证书的扩展项定死,后面 Envoy 1.30 与 Spring Boot 3.2 的握手才不会在半夜报错。
根 CA:OpenSSL 3.0.13 生成,有效期 3650 天,私钥离线
# 1) 生成 CA 私钥(ECDSA P-256;若需兼容旧客户端可换 RSA 3072)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ca.key
chmod 600 ca.key # 仅属主可读,私钥永不进 Git/镜像
# 2) 自签根证书:CA:TRUE 与 keyCertSign/cRLSign 必须标 critical
openssl req -x509 -new -key ca.key -sha256 -days 3650 -out ca.crt
-subj "/C=CN/O=Acme/CN=Acme Internal Root CA"
-addext "basicConstraints=critical,CA:TRUE"
-addext "keyUsage=critical,keyCertSign,cRLSign"
-addext "subjectKeyIdentifier=hash"
openssl x509 -in ca.crt -noout -text | grep -A2 "Basic Constraints"
# 输出应含:CA:TRUE
据 OpenSSL 3.x 文档,-addext 自 1.1.1 起可用,3.0.13 行为一致;critical 缺失会让部分校验器忽略该扩展,等于把 CA 约束废掉。
服务端证书:必须有 serverAuth 与 SAN
# 关键配置片段 server.ext(其余字段略)
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=DNS:payment.internal,IP:10.20.30.40
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
openssl req -new -key server.key -out server.csr -subj "/CN=payment.internal"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial
-days 90 -sha256 -extfile server.ext -out server.crt
SAN 缺失是最高频故障。JDK 17 的 sun.security.util.HostnameChecker 会直接抛 SSLHandshakeException: No subject alternative names present,因为自 JDK 7 起 CN 已不再参与主机名校验(RFC 6125 第 6.4.4 节)。域名和实际访问用的 IP 都要写进 SAN,Envoy 上游用 IP 直连时同样校验 IP 条目。
客户端证书:clientAuth,授权看 SAN URI
# client.ext
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature
extendedKeyUsage=clientAuth
subjectAltName=URI:spiffe://acme.internal/payment,email:ops@acme.internal
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
CN 放服务名只是给人看;据 SPIFFE 规范,身份应以 URI SAN 表达,Spring Security 里用 X509Certificate.getSubjectAlternativeNames() 取类型 6(URI)做鉴权,比解析 CN 字符串可靠得多。
证书链与信任库的摆放
# 服务端链文件:leaf → intermediate,根 CA 绝不放入
cat server.crt intermediate.crt > server-chain.crt
# 客户端校验只带根 CA
curl --cert client.crt --key client.key --cacert ca.crt https://payment.internal:8443/health
# Spring Boot 3.2 truststore:根 CA + 中间 CA
keytool -importcert -alias root -file ca.crt -keystore trust.p12 -storetype PKCS12
keytool -importcert -alias inter -file intermediate.crt -keystore trust.p12 -storetype PKCS12
把根 CA 塞进服务端链会多发一个字节包并触发部分客户端的链构建告警,Envoy 的 tls_context(1.30 中为 DownstreamTlsContext)只应加载 leaf+intermediate。
算法与有效期怎么选
| 维度 | RSA 3072 | ECDSA P-256 |
|---|---|---|
| 安全强度 | 约 128 位 | 约 128 位 |
| 握手字节数 | 较大(证书约 1.2 KB) | 更小(证书约 0.6 KB) |
| TLS 1.3 套件 | tls13_aes_128_gcm_sha256 等 | 同上,签名算法为 ecdsa_secp256r1_sha256 |
| 兼容风险 | 几乎无 | 需确认 JDK 17 与 Envoy 1.30 均启用对应套件 |
| 有效期建议 | 服务端/客户端 90 天,CA 3650 天 | 同左 |
据 Let’s Encrypt 的实践,90 天短周期配合 7 天并行轮换窗口,比维护 CRL/OCSP 更易落地;Envoy 1.30 的 certificate_provider 支持热加载,Spring Boot 3.2 侧用 server.ssl.* 重启或 Actuator 刷新即可完成并行期切换。
mTLS 配置教程完整实操步骤:6 步从生成证书到 Envoy 与 Spring Boot 生效
下面这套 6 步流程假设你已经有一台能同时跑 Envoy 与 Spring Boot 的 Linux 主机,证书全部自签、内部使用。关键原则:私钥与 CA 私钥永不落到应用目录,因此第 1 步先分目录,后面每一步都按”产物落在哪个目录”推进。
步骤 1:先对齐版本,再建目录。版本不一致是后续 90% 报错的根因——比如 OpenSSL 3.0 之前不支持 -addext,Envoy 1.28 之前 DownstreamTlsContext 的字段路径有差异。先用表格核对,全部命中再继续。
| 组件 | 本节基准版本 | 校验命令 | 默认值 / 取值范围说明 |
|---|---|---|---|
| OpenSSL | 3.0.13(2024-01-30 发布) | openssl version |
3.0 起 -addext 与 genpkey 为标配 |
| Envoy | 1.30.1 | envoy --version |
默认 TLS 最低版本 TLSv1.2 |
| JDK | 17.0.11(LTS) | java -version |
Spring Boot 3.2 要求 JDK 17+ |
| Spring Boot | 3.2.x | ./mvnw -v |
server.ssl.client-auth 默认 none |
# 分目录,杜绝私钥混放;后续命令均以 /etc/mtls 为根
sudo mkdir -p /etc/mtls/{ca,server,client}
sudo chmod 700 /etc/mtls/ca # CA 私钥目录仅 root 可进
cd /etc/mtls
步骤 2:生成根 CA。RSA 3072 位是 NIST SP 800-57 建议的、在 2030 年前足够安全的最小档位。注意 basicConstraints 与 keyUsage 必须带 critical,这是 RFC 5280 第 4.2.1.9 节的硬性要求,缺了会让部分 TLS 实现对 CA 证书”视而不见”。
cd /etc/mtls/ca
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out ca.key
openssl req -x509 -new -key ca.key -sha256 -days 3650
-subj "/CN=Acme Internal Root CA/O=Acme"
-addext "basicConstraints=critical,CA:TRUE"
-addext "keyUsage=critical,keyCertSign,cRLSign"
-out ca.crt
openssl x509 -in ca.crt -noout -text | grep -A1 "Basic Constraints" # 应看到 CA:TRUE
步骤 3:签发服务端证书(90 天)。90 天与 Let’s Encrypt 的证书有效期策略一致,便于把”续期”变成肌肉记忆。据 Let’s Encrypt 文档,缩短有效期是行业方向,内部 CA 也建议照此节奏。SAN 必须写,因为 OpenSSL 3.x 与 Java 17 都已忽略 CN 做主机名校验。
cd /etc/mtls/server
cat > server-ext.cnf <<'EOF'
basicConstraints = critical,CA:FALSE
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = DNS:payment.internal
EOF
openssl req -new -newkey rsa:3072 -nodes -keyout server.key -out server.csr
-subj "/CN=payment.internal/O=Acme"
openssl x509 -req -in server.csr -CA ../ca/ca.crt -CAkey ../ca/ca.key
-CAcreateserial -out server.crt -days 90 -sha256 -extfile server-ext.cnf
步骤 4:签发客户端证书。EKU 必须是 clientAuth,否则 Envoy 会以 verify error:num=26:unsupported certificate purpose 拒掉握手。SAN 用 SPIFFE URI 是云原生主流做法(SPIFFE 规范 v1.0),为后续接入 SPIRE 留出扩展位。
cd /etc/mtls/client
cat > client-ext.cnf <<'EOF'
basicConstraints = critical,CA:FALSE
keyUsage = critical,digitalSignature
extendedKeyUsage = clientAuth
subjectAltName = URI:spiffe://acme.internal/payment
EOF
openssl req -new -newkey rsa:3072 -nodes -keyout client.key -out client.csr
-subj "/CN=payment-client/O=Acme"
openssl x509 -req -in client.csr -CA ../ca/ca.crt -CAkey ../ca/ca.key
-CAcreateserial -out client.crt -days 90 -sha256 -extfile client-ext.cnf
chmod 600 client.key # 私钥仅属主可读,避免被同机进程窃取
步骤 5:导入 truststore 并配置 Spring Boot 3.2。Java 不认 PEM 里的 CA 列表,必须转成 PKCS12。这一步就是让 mtls 配置教程里的”信任锚”真正落到 JVM 里。
cd /etc/mtls/ca
keytool -importcert -alias acme-ca -file ca.crt
-keystore truststore.p12 -storetype PKCS12 -storepass changeit -noprompt
# 产物放到 src/main/resources/truststore.p12
# application.yml —— Spring Boot 3.2
server:
port: 8443
ssl:
enabled: true
client-auth: need # none | want | need;need=强制双向
key-store: classpath:server.p12
key-store-password: changeit
key-store-type: PKCS12
trust-store: classpath:truststore.p12
trust-store-password: changeit
trust-store-type: PKCS12
enabled-protocols: TLSv1.3,TLSv1.2
步骤 6:配置 Envoy 1.30 并做正反向验证。核心是 require_client_certificate: true 与 validation_context.trusted_ca 同时存在——只写前者不写后者,Envoy 会拒绝启动并报 require_client_certificate set but no validation context configured。
# /etc/envoy/envoy.yaml(节选 filter_chains 部分)
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true
common_tls_context:
tls_params:
tls_minimum_protocol_version: TLSv1_2
tls_certificates:
- certificate_chain: { filename: /etc/envoy/server.crt }
private_key: { filename: /etc/envoy/server.key }
validation_context:
trusted_ca: { filename: /etc/envoy/ca.crt }
# 启动前静态校验,输出 configuration '/etc/envoy/envoy.yaml' OK 才继续
envoy --mode validate -c /etc/envoy/envoy.yaml
# 反向验证:不带客户端证书,必须被拒
openssl s_client -connect 127.0.0.1:8443 -CAfile /etc/mtls/ca/ca.crt -servername payment.internal
# 预期报错(TLS 1.3):tlsv13 alert certificate required
# 正向验证:带客户端证书,握手成功且 Verify return code: 0 (ok)
openssl s_client -connect 127.0.0.1:8443
-cert /etc/mtls/client/client.crt -key /etc/mtls/client/client.key
-CAfile /etc/mtls/ca/ca.crt -servername payment.internal -brief
排错提示:若 Spring Boot 侧日志出现
PKIX path building failed,八成是trust-store指向的 p12 没包含 CA,或trust-store-password与导入时不一致;若 Envoy 侧出现verify error:num=20:unable to get local issuer certificate,检查trusted_ca.filename是否指向完整链而非中间 CA 单独文件。
mTLS 配置教程配置示例:Envoy 1.30 与 Spring Boot 3.2 的关键参数怎么写?
先把两端的“信任锚”对齐,再谈参数。Envoy 1.30 的下游 TLS 配置写在 DownstreamTlsContext 里(字段定义见 Envoy v1.30 API reference 的 extensions.transport_sockets.tls.v3):
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true # 关键:不写这行时 Envoy 只“请求”证书,客户端可空手而来,等价 want
common_tls_context:
tls_certificates:
- certificate_chain: { filename: "/etc/envoy/server.crt" } # 必须是「叶证书 + 中间 CA」全链
private_key: { filename: "/etc/envoy/server.key" }
validation_context:
trusted_ca: { filename: "/etc/envoy/ca.crt" } # 签发客户端证书的 CA
match_typed_subject_alt_names: # 链校验之外的 SAN 白名单
- san_type: URI
matcher: { prefix: "spiffe://acme.internal/" } # 遵循 SPIFFE ID 规范
这段 match_typed_subject_alt_names 是 mTLS 配置教程里最容易被忽略的一行:trusted_ca 只证明“证书由我方 CA 签发”,不区分是哪个客户端;加上 URI 前缀匹配后,Envoy 会在握手阶段直接拒绝 SAN 不匹配的证书,等价于把授权前移到 TLS 层。不写 tls_params 时 Envoy 默认允许 TLS 1.2 与 1.3(RFC 8446),需要收紧可加 tls_maximum_protocol_version: TLSv1_3。
Spring Boot 3.2 侧对应配置(client-auth 取值 none|want|need,默认 none):
server:
port: 8443
http2:
enabled: true # 默认 false,不开则 curl 拿到 HTTP/1.1 200
ssl:
enabled: true
key-store: classpath:server.p12
key-store-password: ${KEYSTORE_PASS}
key-store-type: PKCS12
key-alias: server # 必须与 pkcs12 -name 完全一致
client-auth: need # need = 强制,want = 请求但可缺省
trust-store: classpath:truststore.p12
trust-store-password: ${TRUSTSTORE_PASS}
trust-store-type: PKCS12
enabled-protocols: TLSv1.3,TLSv1.2 # Spring Boot 3.x 默认即此值
| 语义 | Envoy 1.30 字段 | Spring Boot 3.2 属性 | 差异要点 |
|---|---|---|---|
| 强制客户端证书 | require_client_certificate: true |
server.ssl.client-auth: need |
Envoy 默认 false,Boot 默认 none,两端都必须显式打开 |
| 信任锚 | validation_context.trusted_ca |
trust-store |
Envoy 读 PEM 文件,Boot 读 PKCS12/JKS |
| 身份白名单 | match_typed_subject_alt_names |
无内置等价项 | Boot 只做链校验,SAN 校验需自定义 X509AuthenticationFilter |
| 协议版本 | tls_params.tls_maximum_protocol_version |
enabled-protocols |
两者默认均为 1.2/1.3 |
PEM 转 PKCS12 与 key-alias 的对应关系,是本节 mTLS 配置教程里报错率最高的一步:
openssl pkcs12 -export
-out server.p12
-inkey server.key -in server.crt -certfile ca.crt
-name server # 这个值必须等于 application.yml 的 key-alias
-passout pass:${KEYSTORE_PASS}
若 -name 写成 mycert 而 yml 里仍是 key-alias: server,启动会抛 java.io.IOException: Alias name [server] does not identify a key entry。据 Spring Boot 3.2 Reference 的 “SSL” 章节,3.1 起也支持直接挂 PEM(server.ssl.certificate / certificate-private-key / trust-certificate),可绕开 keystore 转换。
正向验证两条命令,先看 curl:
curl -v --cert client.crt --key client.key --cacert ca.crt
https://payment.internal:8443/healthz
# 期望:* SSL certificate verify ok.
# < HTTP/2 200
openssl s_client -connect payment.internal:8443 -servername payment.internal
-cert client.crt -key client.key -CAfile ca.crt -tls1_3 -brief
# 期望:Verification: OK
# Protocol version: TLSv1.3
# Cipher: TLS_AES_256_GCM_SHA384
Envoy 改完静态证书别直接重启,先校验再优雅退出:
envoy --mode validate -c /etc/envoy/envoy.yaml # 只校验不启动
envoy -c /etc/envoy/envoy.yaml --drain-time-s 30 --parent-shutdown-time-s 60
# drain-time-s 期间停止接受新连接,parent-shutdown-time-s 为进程总超时
恢复判定看统计项 listener.<address>.ssl.handshake(如 listener.0.0.0.0_8443.ssl.handshake)是否重新增长;若 ssl.fail_verify_error 上升,问题在客户端证书链,而非监听器本身。
mTLS 配置教程选型对比:Envoy、Spring Boot、HAProxy、Istio 怎么选?
如果你在搜索引擎里翻 mTLS 配置教程,最容易踩的坑不是”证书怎么签”,而是”选了不匹配的组件”:Envoy 能做 SPIFFE 级别的 SAN 精确匹配,Spring Boot 3.2 的 client-auth=need 却只校验到 CA 链为止,HAProxy 要在 ACL 里手写 DN 匹配,Istio 则把整套身份体系收进控制面。先把四者的能力边界摊开看:
| 方案 | 适用场景 | 开启客户端证书校验的参数 | SAN/SPIFFE 校验 | 证书热更新 |
|---|---|---|---|---|
| Envoy 1.30.1 | 边缘网关、服务入口、多租户前置代理 | require_client_certificate: true + validation_context.trusted_ca |
支持 match_typed_subject_alt_names(按 URI/DNS 精确匹配) |
SDS 热更新;静态 bootstrap 配置需重启进程 |
| Spring Boot 3.2.5 | Java 单体、内部服务、快速验证 | server.ssl.client-auth=need + server.ssl.trust-store |
无内置 SAN 策略,需自定义 X509TrustManager 或 Servlet 过滤器 |
默认需重启;SSL Bundle 可配合 Actuator 触发重载 |
| HAProxy 2.9.7 | TCP/HTTP 入口、传统 IDC 架构 | bind :8443 ssl crt server.pem ca-file ca.crt verify required |
需 ACL 匹配 ssl_c_s_dn / ssl_c_used |
reload -sf 平滑生效,连接不中断 |
| Istio 1.22 | Kubernetes 服务网格内东西向流量 | PeerAuthentication 的 mode: STRICT |
原生 SPIFFE 身份 spiffe://<trust-domain>/ns/<ns>/sa/<sa> |
自动轮换,istiod 默认 defaultCertTTL 约 24 小时 |
Envoy 的关键差异点在于”能校验到身份层”。据 Envoy 官方文档,CertificateValidationContext 的 match_typed_subject_alt_names 支持 exact/prefix/suffix/contains 四种匹配方式,这是 HAProxy 2.9 的 ssl_c_s_dn(仅 DN 字段)做不到的。最小片段如下,注意 require_client_certificate 默认为 false,漏写就等于只做了单向 TLS:
# envoy.yaml 片段(Envoy 1.30.1,DownstreamTlsContext)
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true # 默认 false,必须显式开启
common_tls_context:
tls_certificates:
- certificate_chain: { filename: /etc/certs/server.crt }
private_key: { filename: /etc/certs/server.key }
validation_context:
trusted_ca: { filename: /etc/certs/ca.crt }
match_typed_subject_alt_names:
- san_type: URI
matcher: { exact: "spiffe://cluster.local/ns/payment/sa/gateway" }
Spring Boot 3.2.5 的门槛最低但语义最弱。据 Spring Boot 官方文档,server.ssl.client-auth 只有 none/want/need 三值,need 表示握手阶段强制要求客户端证书,但校验终点是 trust-store 里的 CA 链——链对上就放行,不区分是哪个客户端。客户端没带证书时,服务端日志里会出现典型的 javax.net.ssl.SSLHandshakeException: PKIX path building failed(对端不受信)或 Received fatal alert: bad_certificate。
# application.yml(Spring Boot 3.2.5)
server:
port: 8443
ssl:
enabled: true
client-auth: need # none | want | need,默认 none
key-store: classpath:server.p12
key-store-password: changeit
key-store-type: PKCS12
trust-store: classpath:ca.p12 # 用于校验客户端证书的 CA
trust-store-password: changeit
trust-store-type: PKCS12
HAProxy 2.9.7 胜在运维友好。verify required 与 ca-file 绑定在 bind 行上,改证书只需 haproxy -c -f haproxy.cfg 校验后执行 reload -sf $(pidof haproxy),老进程在处理完存量连接后退出,不会掐断长连接。但要做身份白名单,就得在 http-request 里写 ACL,且只认 DN 字段:
# haproxy.cfg(HAProxy 2.9.7)
frontend mtls_in
bind :8443 ssl crt /etc/haproxy/server.pem ca-file /etc/haproxy/ca.crt verify required
acl is_partner ssl_c_s_dn(OU) -i partner
http-request deny unless is_partner # 无匹配 OU 直接 403
default_backend app
# 平滑生效(不断开存量连接)
# haproxy -c -f /etc/haproxy/haproxy.cfg && haproxy -f /etc/haproxy/haproxy.cfg -sf $(pidof haproxy)
Istio 1.22 把 mTLS 变成”默认态”而非”配置项”。据 Istio 官方文档,PeerAuthentication 的 STRICT 模式拒绝一切明文流量,证书由 istiod 通过 SDS 下发并自动轮换,你不需要持有任何私钥文件。代价是它只解决网格内部的东西向流量,南北向仍需 Gateway 承接——这也是”Envoy + Istio”常被组合使用的原因:同一套 xDS/SDS 心智模型,边缘和网格用同一份 validation_context 语义。
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
# peer-authentication.yaml(Istio 1.22,命名空间级 STRICT)
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: payment
spec:
mtls:
mode: STRICT # PERMISSIVE | STRICT | DISABLE,命名空间默认 PERMISSIVE
portLevelMtls:
"8080":
mode: DISABLE # 例外端口(如健康检查)单独放行
选型可以用一条判据收口:需要按客户端身份(而不只是”是否受信”)做授权时,Envoy 或 Istio 是唯一省事的选择;纯 Java 栈且客户端集合固定、规模在十几个以内,Spring Boot 3.2.5 的 client-auth=need 配合过滤器足够;已有 HAProxy 承载核心入口、不想引入数据平面新组件,就用 verify required + DN ACL,热更新成本最低。无论选哪个,CA 的 basicConstraints=CA:TRUE 与证书的 extendedKeyUsage=clientAuth 都必须正确——这是 RFC 5280 的硬性要求,也是绝大多数”握手失败”的真正根因,与代理软件无关。
mTLS 配置教程常见错误与排查:certificate required、unknown ca、空证书链怎么定位?
先把报错按”谁发的 alert”分三类:客户端发的(unknown ca、bad certificate)、服务端发的(certificate required、empty client certificate chain)、代理层转译的(Envoy 的 connection failure)。OpenSSL 3.x 的错误串里 0A00045C 中 0A 是库标识 SSL routines,据 OpenSSL 官方文档,它比错误文本更稳定,排错时优先看错误码。
| 报错原文 | 发出方 | 最可能根因 | 一条定位命令 |
|---|---|---|---|
tlsv13 alert certificate required |
服务端 | 客户端未带 --cert/--key,或只发了叶子证书 |
curl -v --cert client.crt --key client.key ... |
sslv3 alert bad certificate |
服务端 | 签发 CA 不在服务端信任列表,或中间 CA 缺失 | openssl verify -CAfile ca.crt -untrusted intermediate.crt client.crt |
tlsv1 alert unknown ca(curl 35) |
客户端 | --cacert 指错 CA,或服务端链缺中间 CA |
openssl s_client -connect host:443 -showcerts |
Empty client certificate chain |
Java 服务端 | client-auth=need 但 truststore 为空 |
keytool -list -v -keystore truststore.p12 |
Path does not chain with any of the trust anchors |
Java 服务端 | truststore 只导入了 leaf,缺根/中间 CA | 同上,看 Owner 是否为 CA |
reset before headers ... connection failure |
Envoy | DownstreamTlsContext 缺 validation_context |
envoy --mode validate -c envoy.yaml |
客户端侧先用 curl 复现,注意 TLS 1.3 下服务端索要证书发生在握手后段,-v 输出里能看到 Request CERT (13) 与 Server certificate Verify (15):
# 同时指定客户端证书与私钥,并用正确的根 CA 校验服务端
curl -v https://api.example.com/health
--cert client.crt --key client.key
--cacert ca.crt # 若报 unknown ca,先确认这个文件是签发服务端证书的根 CA
证书链问题用 openssl verify 逐段切断,比反复重启服务快得多(OpenSSL 3.0+ 均支持 -untrusted):
# 期望输出 client.crt: OK
# 报 "unable to get local issuer certificate" = 缺中间 CA,用 -untrusted 补上再验
openssl verify -CAfile ca.crt -untrusted intermediate.crt client.crt
# 直接观察握手是否真的发送了客户端证书
openssl s_client -connect api.example.com:443 -tls1_3
-cert client.crt -key client.key -CAfile ca.crt -servername api.example.com
Envoy 1.30 的坑在于:require_client_certificate: true 只表示”要求”,真正决定信任谁的是 validation_context;漏写它 Envoy 会接受 TLS 连接但在上游失败,日志只给你一句 connection failure。据 Envoy 1.30 文档,改动后务必先做静态校验(返回 configuration ... OK 才算过):
# DownstreamTlsContext 最小可用片段(Envoy 1.30)
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true # 等价 Spring 的 client-auth=need
common_tls_context:
tls_certificates:
- certificate_chain: { filename: /certs/server.crt }
private_key: { filename: /certs/server.key }
validation_context:
trusted_ca: { filename: /certs/ca.crt } # 路径写错 → reset before headers
envoy --mode validate -c /etc/envoy/envoy.yaml # 改完先跑这条
Spring Boot 3.2 侧,server.ssl.client-auth 默认值是 none,设成 need 才强制;但若 trust-store 指向空库,握手会以 Empty client certificate chain 或 CertPathValidatorException 结束。据 Spring Boot 3.2 参考文档,PKCS12 是默认 store 类型,导 CA 时别用 leaf 别名覆盖:
# 检查 truststore 里到底有几条、是不是 CA
keytool -list -v -keystore truststore.p12 -storetype PKCS12
| grep -E "Alias name|Entry type|Owner"
# 导入根 CA(-alias 必须唯一,重复会报 certificate not imported)
keytool -importcert -alias root-ca -file ca.crt
-keystore truststore.p12 -storetype PKCS12 -storepass changeit -noprompt
# application.yml
server:
ssl:
enabled: true
client-auth: need # none(默认) / want(请求但不强制) / need(强制)
trust-store: classpath:truststore.p12
trust-store-password: changeit
trust-store-type: PKCS12
还有一个容易被忽略的点:据 Let’s Encrypt 文档,服务端必须发送完整链(leaf + 中间 CA),根 CA 不进链;客户端 truststore 里则应放根 CA。服务端多发根、客户端少放中间,正是 unknown ca 与 Path does not chain 两类报错最常见的成因组合。
mTLS 配置教程效果验证:如何确认双向认证真的生效而不是“看起来生效”?
验证 mTLS 最容易踩的坑,是把”连接成功”当成”双向认证成功”。TLS 1.3(RFC 8446)把客户端证书请求放在握手后半段的加密记录里,明文抓包看不到,加上很多服务端配置成”请求但不强制”(Envoy 中 require_client_certificate 默认为 false),于是无证书连接照样返回 200。下面用五个互相独立的证据链交叉验证,任何一条不成立就说明 mTLS 没有真正落地。
1. 正向验证:带客户端证书握手
# -tls1_3 强制 TLS 1.3;-brief 只输出摘要;-servername 触发 SNI
# 证书与私钥必须匹配,ca.crt 用于校验服务端证书链
openssl s_client -connect payment.internal:8443
-servername payment.internal
-cert client.crt -key client.key
-CAfile ca.crt -tls1_3 -brief
# 期望输出(OpenSSL 3.x):
# CONNECTION ESTABLISHED
# Protocol version: TLSv1.3
# Cipher: TLS_AES_256_GCM_SHA384
# Verification: OK
注意 Verification: OK 只表示服务端证书链校验通过,不表示服务端接受了你的客户端证书。真正的确认在服务端日志或统计里(见第 4 条)。OpenSSL 1.1.1 及以上才完整支持 TLS 1.3,-brief 自 1.1.0 起可用。
2. 反向验证:故意不带证书
# 去掉 -cert/-key,其余参数不变
openssl s_client -connect payment.internal:8443
-servername payment.internal -CAfile ca.crt -tls1_3 -brief
# 期望(服务端强制 mTLS):
# 40B7...:error:...:tlsv1 alert certificate required:...
# alert 编号 116 = certificate_required(RFC 8446 §6.2)
如果这条命令仍能建立连接并返回 HTTP 200,说明服务端只是”请求”而非”强制”客户端证书。在 Envoy 中对应的开关是 DownstreamTlsContext.require_client_certificate(默认 false),必须显式设为 true,否则 require_client_certificate: false 下客户端不提供证书也能握手成功。
3. curl 的状态码语义区分
# 带证书:期望 HTTP/2 200
curl -sS -o /dev/null -w '%{http_code} %{http_version}n'
--cert client.crt --key client.key --cacert ca.crt
https://payment.internal:8443/health
# 不带证书:期望 curl: (56) ... tlsv1 alert certificate required
curl -sS -o /dev/null -w '%{http_code}n'
--cacert ca.crt https://payment.internal:8443/health
关键判据:无证书时应当是 curl 错误码 56(接收失败),而不是 401/403。401 意味着 TLS 层已放行、失败发生在应用层鉴权(Spring Security 的 X509AuthenticationFilter 未取到证书),这恰恰证明 mTLS 没生效。
4. Envoy 管理端口统计
# 9901 是 Envoy admin 默认端口(address 默认 127.0.0.1)
curl -s localhost:9901/stats | grep -E 'ssl.handshake|ssl.fail_verify_no_cert|ssl.connection_error'
# 期望:ssl.handshake 随每次请求递增
# ssl.fail_verify_no_cert 与 ssl.connection_error 保持 0
ssl.fail_verify_no_cert 增长说明有客户端未带证书却试图连接——这本身就是 mTLS 已强制的证据;若它恒为 0 而 ssl.handshake 也在涨,需回到第 2 条确认。
5. 抓包确认 CertificateRequest 确实发出
sudo tcpdump -i eth0 -nn -s0 -w mtls.pcap port 8443
# Wireshark 过滤:tls.handshake.type == 13
# 13 = CertificateRequest(RFC 8446 §4.3.2)
# 还需能看到 type == 11(Certificate)从客户端发往服务端
没有 type 13 记录,说明服务端根本没请求客户端证书,问题在 Envoy 的 DownstreamTlsContext 或 validation_context 未配置;有 13 但没有 11,说明客户端未发送证书。
| 现象 | 含义 | 定位方向 |
|---|---|---|
Verification: OK + TLSv1.3 |
TLS 层通过,证书未强制 | 查 require_client_certificate |
alert certificate required(116) |
服务端强制 mTLS 生效 | 符合预期 |
| 无证书返回 401/403 | TLS 通过,应用层拒绝 | Spring Security 证书映射 |
ssl.fail_verify_no_cert 增长 |
有客户端漏配证书 | 客户端证书分发 |
| 抓包无 type 13 | 服务端未请求证书 | Envoy TLS 上下文 |
据 Let’s Encrypt 与 Mozilla Server Side TLS 指南的建议,验证阶段应同时保留正向与反向两条命令作为回归用例;据 OpenSSL 文档,s_client 的 -brief 输出在 1.1.1 与 3.x 间格式略有差异,脚本断言时建议匹配 Protocol version 与 Verification 两个关键字而非整行。这套五步验证同样适用于其它 mTLS 场景(如 Istio、Nginx ssl_verify_client on),只是统计端点与配置项名称不同。
mTLS 配置教程上线建议:证书轮换、吊销与监控怎么做?
上线后最容易翻车的时刻不是首次握手,而是第 89 天和吊销之后。先说结论:客户端证书 90 天、CA 3650 天,到期前 14 天告警,轮换走”先加新、双信任 7 天、再摘旧”的三段式。这也是本 mTLS 配置教程里唯一一条”时间参数错了会直接断流”的规则,建议直接写进值班手册。
证书什么时候换、换的顺序是什么?按下表执行,注意双信任窗口必须有明确结束日期,否则 truststore 会越滚越大:
| 对象 | 有效期 | 告警提前量 | 轮换动作 |
|---|---|---|---|
| 客户端证书(业务侧) | 90 天(参考 Let’s Encrypt 短周期理念) | 到期前 14 天 | 新证书与旧证书并存下发,客户端优先用新证书 |
| 服务端 CA | 3650 天 | 到期前 180 天 | 新 CA 先进入 truststore,7 天双信任后再移除旧 CA |
| 服务端叶子证书 | 90 天 | 到期前 14 天 | 热更新(SDS / Actuator),无需重启监听 |
# 1) 核对现有客户端证书剩余寿命,notAfter 距今 < 14 天即触发轮换
openssl x509 -in client.crt -noout -subject -enddate
# notAfter=Apr 12 08:00:00 2025 GMT
# 2) 签发新客户端证书,-days 90 对应 90 天策略
openssl req -new -newkey rsa:2048 -nodes -keyout client-new.key
-out client-new.csr -subj "/CN=svc-order/O=example"
openssl x509 -req -in client-new.csr -CA ca.crt -CAkey ca.key
-CAcreateserial -days 90 -sha256 -out client-new.crt
Envoy 1.30 怎么改配置才不断流?静态配置走”校验 + 优雅重启”,先把新旧 CA 拼成一个 bundle(cat ca-old.crt ca-new.crt > ca-bundle.pem),让 validation_context.trusted_ca 同时信任两者:
# /etc/envoy/envoy.yaml 片段(Envoy 1.30,DownstreamTlsContext)
filter_chains:
- transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
require_client_certificate: true # 强制客户端证书,缺失时计入 ssl.fail_verify_no_cert
common_tls_context:
validation_context:
trusted_ca:
filename: /etc/certs/ca-bundle.pem # 7 天双信任窗口:新旧 CA 拼接
# crl: { filename: /etc/certs/ca.crl } # 需要 CRL 时启用,见下文
# 改完先校验,输出 "configuration '...' OK" 再重启
envoy --mode validate -c /etc/envoy/envoy.yaml
# 优雅退出:--drain-time-s 默认 600 秒,入口网关建议显式降到 30 秒
envoy -c /etc/envoy/envoy.yaml --drain-time-s 30 --drain-strategy gradual
如果已经在用 SDS(envoy.extensions.transport_sockets.tls.v3.Secret + xDS),证书下发与配置变更解耦,轮换完全不需要碰入口网关进程——这是把 90 天轮换做成常态化的前提。
Spring Boot 3.2 侧要不要重启?SSL bundle 支持热刷新,但 server.ssl.client-auth 属于启动期绑定,改了必须重启:
spring:
ssl:
bundle:
pem:
mtls-server:
keystore:
certificate: file:/etc/certs/server.crt
private-key: file:/etc/certs/server.key
truststore:
certificate: file:/etc/certs/ca-bundle.pem # 双信任窗口期间含新旧 CA
server:
ssl:
bundle: mtls-server
client-auth: need # 变更此项仍需重启
# 触发 bundle 重载(需 management.endpoints.web.exposure.include=refresh)
curl -X POST http://localhost:8080/actuator/refresh
滚动发布时保留旧实例 10 分钟,观察 5xx 与握手失败率是否回落,再摘除旧 Pod。这正是本 mTLS 配置教程强调”灰度窗口”而非”一次性全量”的原因:客户端缓存旧 CA 的时间往往比你想的久。
吊销:为什么优先靠短有效期而不是 CRL?RFC 5280 定义的 CRL 存在 nextUpdate 空窗期,CRL 拉取失败时多数实现是”放行”而非”拒绝”。Envoy 的 validation_context.crl.filename 只支持文件,意味着你要自己解决分发;Spring Boot 没有内置 CRL 开关,需自定义 X509TrustManager:
// 关键:CRL 过期或被吊销都必须抛异常,而不是静默放行
X509CRL crl = (X509CRL) CertificateFactory.getInstance("X.509")
.generateCRL(new FileInputStream("/etc/certs/ca.crl"));
if (crl.getNextUpdate().before(new Date()))
throw new CertificateException("CRL 已过期,拒绝握手");
if (crl.isRevoked(chain[0]))
throw new CertificateException("客户端证书已被吊销");
# 运维核对 CRL 新鲜度,重点看 Next Update
openssl crl -in ca.crl -noout -text | head -20
openssl crl -in ca.crl -noout -nextupdate
监控看哪几个数?阈值直接抄:
| 信号 | 采集位置 | 告警条件 | 首查方向 |
|---|---|---|---|
ssl.fail_verify_no_cert |
Envoy listener 统计 | > 5 次/分钟 | 客户端未带证书,或 truststore 漏了新 CA |
ssl.handshake |
Envoy listener 统计 | 环比下降 30% | 证书过期、CRL 拉取失败、SNI 错配 |
SSLHandshakeException |
Spring Boot 日志 | 连续出现 3 次 | 立即开工单,附 openssl s_client -connect host:8443 -cert client.crt -key client.key 结果 |
Envoy 的 TLS 统计默认开启,指标形如 listener.0.0.0.0_8443.ssl.handshake,抓取时按 listener 维度聚合即可;据 Envoy 官方文档,ssl.fail_verify_error、ssl.connection_error 也应一并纳入面板,才能区分”证书不对”和”TCP 就没通”。
mTLS 就是双向 TLS 认证,通常指服务端在握手时校验客户端证书。是否改代码取决于客户端类型:curl、openssl s_client、Envoy 只需加证书参数;Java HttpClient 需要构造 SSLContext 并加载 keystore/truststore。
可以共用同一个根 CA,但建议把客户端证书和服务端证书放在不同中间 CA 下,便于按用途吊销和限制信任范围。共用根 CA 时,服务端 truststore 只导入根 CA 或对应中间 CA,不要导入无关的业务 CA。
先确认 curl 同时带了 –cert 和 –key,且证书链文件包含 leaf 与中间 CA。若仍报错,检查 Envoy validation_context.trusted_ca 是否指向签发该客户端证书的 CA,以及客户端证书是否含 extendedKeyUsage=clientAuth。
mTLS 做传输层身份认证,JWT 做应用层授权,Istio STRICT 是网格内自动启用 mTLS 的方式。若服务在 Kubernetes 且已用 Istio,优先用 PeerAuthentication mode: STRICT;若不在网格内,用 Envoy 1.30 或 HAProxy 2.9 手工配置更直接。
健康检查客户端也要带客户端证书,或给健康检查单独开一个不强制 mTLS 的端口。不要为了健康检查把 client-auth 改成 want,否则未带证书的请求仍可能进入应用层,削弱 mTLS 的强制效果。
先签发新客户端证书,服务端 truststore 同时信任新旧证书 7 天;客户端切到新证书后观察 ssl.handshake 与 5xx 指标,再移除旧证书。Envoy 静态配置需重启,建议用 –drain-time-s 30 平滑退出。
mTLS 能证明调用方持有私钥,但无法表达细粒度权限;API Key 和 IP 白名单仍有防误用和限流价值。生产环境常见组合是 mTLS 做传输层身份,JWT/OPA 做应用层授权,IP 白名单只作为外围补充。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。