Apache APISIX中实现mTLS请求的Lua插件开发指南

背景介绍

在微服务架构中，mTLS（双向TLS认证）是一种重要的安全机制，它要求通信双方都验证对方的证书，确保端到端的安全性。Apache APISIX作为云原生API网关，提供了强大的插件扩展能力，开发者可以通过Lua插件实现各种定制化功能。

问题现象

开发者在尝试通过APISIX的Lua插件发起mTLS请求时遇到了证书验证失败的问题。具体表现为：

1. 使用TLS 1.3时出现"certificate required"错误
2. 使用TLS 1.2时出现"bad certificate"错误
3. 通过Wireshark抓包确认客户端证书未被发送

根本原因分析

经过深入排查，发现问题的根源在于APISIX使用的api7-lua-resty-http库与上游的lua-resty-http库存在API差异：

1. 上游库使用ssl_client_cert和ssl_client_priv_key参数
2. APISIX的fork版本使用ssl_cert和ssl_key参数

这种API差异导致开发者按照常规方式配置时，客户端证书无法正确加载和发送。

解决方案

在APISIX插件中正确发起mTLS请求的方法如下：

local httpc = require("resty.http").new()
local ok, err = httpc:connect {
    scheme = "https",
    host = "target.server",
    port = 443,
    ssl_verify = true,
    ssl_cert = cert_in_pem_format,  -- 客户端证书(PEM格式)
    ssl_key = key_in_pem_format    -- 客户端私钥(PEM格式)
}

关键点说明：

1. 必须使用PEM格式的证书和私钥
2. 参数名必须使用ssl_cert和ssl_key而非其他变体
3. 建议启用ssl_verify以验证服务端证书

最佳实践建议

1. 证书管理：

   • 将证书和私钥存储在APISIX的机密存储中
   • 避免在代码中硬证书内容
   • 定期轮换证书

2. 错误处理：

   • 捕获并记录连接错误
   • 实现适当的重试机制
   • 监控mTLS连接成功率

3. 性能优化：

   • 复用HTTP连接
   • 考虑使用连接池
   • 评估证书加载开销

4. 兼容性考虑：

   • 明确指定TLS版本
   • 测试不同TLS版本的兼容性
   • 考虑密码套件配置

总结

在APISIX插件开发中实现mTLS功能时，开发者需要特别注意APISIX定制版本的HTTP库与上游库的API差异。正确使用ssl_cert和ssl_key参数是确保mTLS功能正常工作的关键。通过遵循本文提供的解决方案和最佳实践，开发者可以构建安全可靠的mTLS通信功能。