运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载本篇技术指南围绕 Salt 仓库中 changelog/69441.added.md 记录的功能更新展开rest_cherrypy新增ssl_ca_certs与ssl_cert_reqs两个配置项为 salt-api 的 HTTPS 服务引入基于 TLS 握手阶段的客户端证书校验mutual TLS即 mTLS。读完本文你将掌握如何为 salt-api 配置双向 TLS、理解三个校验等级CERT_NONE/CERT_OPTIONAL/CERT_REQUIRED的区别并结合ssl_allowed_cn实现细粒度的客户端证书 CN 白名单控制。一、功能背景为什么 salt-api 需要 mTLSsalt-api 是 Salt 官方提供的 REST API 服务默认由rest_cherrypy模块承载WSGI 服务器基于 CherryPy 实现。在开启 HTTPS 后传统 TLS 只保证服务端身份可信客户端只要持有合法的 eauth 凭据用户名/密码或 token即可访问 API。这种模型存在一个隐患凭据一旦泄露任何持有凭据的人都可调用管理接口。该 changelog 记录的功能正是为了闭合这一缺口——在TLS 握手阶段就要求客户端出示由信任锚trust anchor签发的证书Addedssl_ca_certsandssl_cert_reqsoptions torest_cherrypyfor client-certificate validation on the TLS handshake (mutual TLS). When set, salt-api rejects connections without a peer cert signed by one of the configured trust anchors before any HTTP request is processed.即配置后任何未携带受信任客户端证书的连接在任何 HTTP 请求被处理之前就会被拒绝。这意味着即使攻击者窃取了 eauth 凭据只要没有合法的客户端证书依然无法建立 TLS 会话更无法触达/login、/run等任何业务端点。二、新增配置参数详解两个新参数均位于 master 配置文件的rest_cherrypy配置段下属于 CherryPy 内建 HTTPS 服务器的配置项不适用于 Apache/Nginx 等外部反向代理场景。参数说明与默认行为可对照 salt/netapi/rest_cherrypy/app.py 中的文档字符串。2.1ssl_ca_certs类型字符串路径默认值未设置作用指向一个 PEM 格式信任锚证书的文件路径或目录路径用于验证客户端证书。说明底层等价于 Pythonssl.SSLContext.load_verify_locations()可将 CA 证书直接指向文件或指向包含多个 CA 证书的目录。2.2ssl_cert_reqs类型字符串默认值未显式设置时不做客户端证书校验等价于CERT_NONE可选值CERT_NONE不要求客户端证书默认行为兼容旧配置CERT_OPTIONAL客户端若出示证书则进行校验未出示也可通过握手CERT_REQUIRED握手阶段强制校验未携带受信任证书的客户端直接连接失败。说明底层对应ssl.SSLContext.verify_mode。源码实现中对非法取值会记录错误日志并抛出ValueError合法取值仅限上述三者的 Python 常量名见 salt/netapi/rest_cherrypy/init.py。2.3 配套参数版本 3009.0 一同引入在同一个 3009.0 版本周期内还引入了以下与 mTLS 强相关的配套能力ssl_chain可选的证书链文件用于传递给load_verify_locations对应文档位于 app.py。ssl_allowed_cn可选的客户端证书 Subject CN 允许列表在 mTLS 校验通过后做应用层二次过滤详见本文第五节。disable_ssl是否关闭 SSL。必须强调的是关闭 SSL 意味着 Salt 的 eauth 认证凭据将以明文传输生产环境切勿关闭。三、完整配置示例以下为开启 mTLS 的rest_cherrypy最小可用配置配置在 Salt Master 配置文件中结合 app.py 中的 setup 说明整理rest_cherrypy: port: 8000 host: 0.0.0.0 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key # --- 以下为 mTLS 相关配置 --- ssl_ca_certs: /etc/salt/api_client_ca.pem ssl_cert_reqs: CERT_REQUIRED ssl_allowed_cn: - api-client-01 - api-client-02前置条件清单安装salt-api与 CherryPyCherryPy 需满足__init__.py中声明的版本要求cpy_min 3.2.2见 salt/netapi/rest_cherrypy/init.py准备好服务端证书与私钥。可用 Salt 自带的 TLS 模块快速生成自签名证书salt-call --local tls.create_self_signed_cert为客户端签发证书并将签发该证书的 CA 保存为ssl_ca_certs指向的 PEM 文件在 master 配置中配置至少一个 eauth 用户/组参照外部认证eauth文档重启salt-master随后启动salt-api。启动后可通过openssl s_client验证客户端校验是否生效# 不带客户端证书应握手失败 openssl s_client -connect localhost:8000 -servername localhost # 携带客户端证书与私钥应握手成功 openssl s_client -connect localhost:8000 \ -cert /path/to/client.crt \ -key /path/to/client.key \ -CAfile /etc/salt/api_client_ca.pem四、源码实现剖析握手阶段的校验流程mTLS 的实际实现位于 salt/netapi/rest_cherrypy/init.py 的start()函数中其关键流程如下通过apiopts.get(ssl_ca_certs)与apiopts.get(ssl_cert_reqs)读取配置只要二者任一被设置即进入客户端证书校验分支if ssl_ca_certs or ssl_cert_reqs:使用ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)创建默认上下文——注意用途是CLIENT_AUTH明确要求对端客户端提供证书调用_ctx.load_cert_chain(certfilessl_crt, keyfilessl_key)加载服务端证书链若配置了ssl_ca_certs调用_ctx.load_verify_locations(ssl_ca_certs)加载信任锚若配置了ssl_cert_reqs通过getattr(_ssl, ssl_cert_reqs)将字符串映射为CERT_NONE/CERT_OPTIONAL/CERT_REQUIRED常量并赋值给_ctx.verify_mode取值非法时抛出ValueError最后通过cherrypy.server.ssl_context _ctx将自定义上下文挂载到 CherryPy 服务器。值得注意的两个实现细节该分支独立于原有的cherrypy.server.ssl_module builtin方式默认路径仅配置ssl_certificate/ssl_private_key/ssl_certificate_chain而 mTLS 路径直接注入完整的SSLContext二者互斥且后者优先级更高。校验发生在CherryPy 服务器层面的 TLS 握手中早于任何 WSGI 应用代码执行因此能够做到 changelog 所描述的 before any HTTP request is processed任何 HTTP 请求被处理之前即拒绝。此外start()中还有一个verify_certs()辅助函数用于在启动阶段检查ssl_crt/ssl_key文件是否存在若缺失会直接给出使用tls.create_self_signed_cert生成证书的提示见init.py。五、证书 CN 白名单ssl_allowed_cn的应用层二次过滤mTLS 解决了证书是否由可信 CA 签发的问题但所有持有合法客户端证书的调用方仍彼此等价。rest_cherrypy在 3009.0 中同时提供的ssl_allowed_cn允许列表把控制粒度细化到证书 Subject CN。其实现为salt_ssl_cn_filter_tool()定义于 salt/netapi/rest_cherrypy/app.pydef salt_ssl_cn_filter_tool(): apiopts cherrypy.config.get(apiopts) or {} allowed apiopts.get(ssl_allowed_cn) if not allowed: return cn _client_cert_cn() if not cn or cn not in allowed: logger.error( ssl_allowed_cn: rejecting client with CN%r (not in allow list), cn, ) raise cherrypy.HTTPError(403, Client certificate CN not allowed)逻辑要点ssl_allowed_cn为空或未配置时该工具直接放行no-op不会影响既有部署配置后客户端 CN 不在允许列表内、或无法提取到 CN例如证书缺少 CN 字段时直接返回403 ForbiddenCN 的提取优先读取 WSGI 环境变量SSL_CLIENT_S_DN_CN当该变量未填充时典型场景为 CherryPy 内建 SSL 模块会回退解析SSL_CLIENT_CERT中的 PEM 证书内容提取 Subject CN保证兼容性。这一组合形成了完整的纵深防御TLS 握手层由ssl_ca_certsssl_cert_reqs把关证书是否可信应用层由ssl_allowed_cn把关调用方是否被授权。六、测试验证仓库中的单元测试证据仓库为该功能提供了专门的单元测试文件 tests/pytests/unit/netapi/cherrypy/test_ssl_cn_filter.py覆盖了以下关键行为可作为功能契约参考test_no_allow_list_is_noop未配置ssl_allowed_cn或配置为空列表时过滤器不做任何拦截test_allowed_cn_passesCN 在允许列表内时正常放行test_disallowed_cn_rejectedCN 不在列表内时抛出 403test_missing_cn_rejected即使证书由可信 CA 签发但缺失 CN 字段时同样被 403 拒绝test_pem_fallback_allowed_cn_passes与test_pem_fallback_disallowed_cn_rejected验证SSL_CLIENT_S_DN_CN未填充时从SSL_CLIENT_CERTPEM 回退提取 CN 的路径。上述测试通过MagicMock模拟 CherryPy 的 config/request 环境说明该过滤逻辑是纯 WSGI 层面的工具函数便于在非完整 CherryPy 环境下单测也从侧面印证了其可插拔的设计。七、安全实践与注意事项CERT_REQUIRED才是完整 mTLSCERT_OPTIONAL仅在校验客户端主动出示证书时生效若你的威胁模型要求无证书不可访问务必设置为CERT_REQUIRED。信任锚与客户端证书分离管理ssl_ca_certs只放客户端 CA避免与系统 CA 信任库混用客户端证书需独立签发并妥善保管私钥。务必同时配置 eauthmTLS 解决的是谁能建立 TLS 连接rest_cherrypy的认证仍依赖外部认证eauth体系__init__.py中__virtual__()只要求配置段存在且含port不会绕过认证两层缺一不可。Windows 平台限制rest_cherrypy在 Windows 上为实验性支持且不支持 SSL需disable_ssl: TruemTLS 相关配置主要面向 Linux/Unix 生产部署见 app.py。不要忘记 eauth 之外的兜底即使启用 mTLS密码/凭据类认证的账号安全策略如轮换、最小权限仍应继续执行证书是额外的信任边界而非替代品。八、小结ssl_ca_certs与ssl_cert_reqs的引入让 salt-api 的rest_cherrypy从仅服务端认证升级为完整的双向 TLS在握手阶段即可拒绝无合法客户端证书的连接有效缩小了凭据泄露带来的攻击面。配合同一版本引入的ssl_allowed_cnCN 白名单可以在不改变业务代码的前提下实现证书 CN eauth三层叠加的访问控制。相关配置说明、实现源码与单元测试分别位于 app.py、init.py 与 test_ssl_cn_filter.py读者可据此深入研读或参照落地。赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Traefik 双向 TLSmTLS客户端证书认证从 clientca 测试证书生成到 clientAuth 配置实战Traefik 双向 TLSmTLS客户端证书认证从 clientca 测试证书生成到 clientAuth 配置实战 本文以仓库 integration后端API网关负载均衡微服务网络云原生ingress-nginx 客户端证书认证mTLS实战基于 auth-tls 注解实现双向 TLS 身份验证ingress nginx 客户端证书认证mTLS实战基于 auth tls 注解实现双向 TLS 身份验证 导读 本文以 ingress nginx 官后端API网关负载均衡云原生如何永久保存微信聊天记录WeChatMsg完全免费备份终极指南如何永久保存微信聊天记录WeChatMsg完全免费备份终极指南 你是否曾因手机损坏而丢失珍贵的微信聊天记录或是担心更换设备时无法迁移多年的对话历史在数字时上一篇从30秒到3秒Sealos容器启动速度的10倍优化实战下一篇2025 MaterialDesignInXamlToolkit新范式从MD2到MD3的迁移指南与性能革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Salt rest_cherrypy 互信 TLS（mTLS）客户端证书校验：`ssl_ca_certs` 与 `ssl_cert_reqs` 配置实战
运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载本篇技术指南围绕 Salt 仓库中 changelog/69441.added.md 记录的功能更新展开rest_cherrypy新增ssl_ca_certs与ssl_cert_reqs两个配置项为 salt-api 的 HTTPS 服务引入基于 TLS 握手阶段的客户端证书校验mutual TLS即 mTLS。读完本文你将掌握如何为 salt-api 配置双向 TLS、理解三个校验等级CERT_NONE/CERT_OPTIONAL/CERT_REQUIRED的区别并结合ssl_allowed_cn实现细粒度的客户端证书 CN 白名单控制。一、功能背景为什么 salt-api 需要 mTLSsalt-api 是 Salt 官方提供的 REST API 服务默认由rest_cherrypy模块承载WSGI 服务器基于 CherryPy 实现。在开启 HTTPS 后传统 TLS 只保证服务端身份可信客户端只要持有合法的 eauth 凭据用户名/密码或 token即可访问 API。这种模型存在一个隐患凭据一旦泄露任何持有凭据的人都可调用管理接口。该 changelog 记录的功能正是为了闭合这一缺口——在TLS 握手阶段就要求客户端出示由信任锚trust anchor签发的证书Addedssl_ca_certsandssl_cert_reqsoptions torest_cherrypyfor client-certificate validation on the TLS handshake (mutual TLS). When set, salt-api rejects connections without a peer cert signed by one of the configured trust anchors before any HTTP request is processed.即配置后任何未携带受信任客户端证书的连接在任何 HTTP 请求被处理之前就会被拒绝。这意味着即使攻击者窃取了 eauth 凭据只要没有合法的客户端证书依然无法建立 TLS 会话更无法触达/login、/run等任何业务端点。二、新增配置参数详解两个新参数均位于 master 配置文件的rest_cherrypy配置段下属于 CherryPy 内建 HTTPS 服务器的配置项不适用于 Apache/Nginx 等外部反向代理场景。参数说明与默认行为可对照 salt/netapi/rest_cherrypy/app.py 中的文档字符串。2.1ssl_ca_certs类型字符串路径默认值未设置作用指向一个 PEM 格式信任锚证书的文件路径或目录路径用于验证客户端证书。说明底层等价于 Pythonssl.SSLContext.load_verify_locations()可将 CA 证书直接指向文件或指向包含多个 CA 证书的目录。2.2ssl_cert_reqs类型字符串默认值未显式设置时不做客户端证书校验等价于CERT_NONE可选值CERT_NONE不要求客户端证书默认行为兼容旧配置CERT_OPTIONAL客户端若出示证书则进行校验未出示也可通过握手CERT_REQUIRED握手阶段强制校验未携带受信任证书的客户端直接连接失败。说明底层对应ssl.SSLContext.verify_mode。源码实现中对非法取值会记录错误日志并抛出ValueError合法取值仅限上述三者的 Python 常量名见 salt/netapi/rest_cherrypy/init.py。2.3 配套参数版本 3009.0 一同引入在同一个 3009.0 版本周期内还引入了以下与 mTLS 强相关的配套能力ssl_chain可选的证书链文件用于传递给load_verify_locations对应文档位于 app.py。ssl_allowed_cn可选的客户端证书 Subject CN 允许列表在 mTLS 校验通过后做应用层二次过滤详见本文第五节。disable_ssl是否关闭 SSL。必须强调的是关闭 SSL 意味着 Salt 的 eauth 认证凭据将以明文传输生产环境切勿关闭。三、完整配置示例以下为开启 mTLS 的rest_cherrypy最小可用配置配置在 Salt Master 配置文件中结合 app.py 中的 setup 说明整理rest_cherrypy: port: 8000 host: 0.0.0.0 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key # --- 以下为 mTLS 相关配置 --- ssl_ca_certs: /etc/salt/api_client_ca.pem ssl_cert_reqs: CERT_REQUIRED ssl_allowed_cn: - api-client-01 - api-client-02前置条件清单安装salt-api与 CherryPyCherryPy 需满足__init__.py中声明的版本要求cpy_min 3.2.2见 salt/netapi/rest_cherrypy/init.py准备好服务端证书与私钥。可用 Salt 自带的 TLS 模块快速生成自签名证书salt-call --local tls.create_self_signed_cert为客户端签发证书并将签发该证书的 CA 保存为ssl_ca_certs指向的 PEM 文件在 master 配置中配置至少一个 eauth 用户/组参照外部认证eauth文档重启salt-master随后启动salt-api。启动后可通过openssl s_client验证客户端校验是否生效# 不带客户端证书应握手失败 openssl s_client -connect localhost:8000 -servername localhost # 携带客户端证书与私钥应握手成功 openssl s_client -connect localhost:8000 \ -cert /path/to/client.crt \ -key /path/to/client.key \ -CAfile /etc/salt/api_client_ca.pem四、源码实现剖析握手阶段的校验流程mTLS 的实际实现位于 salt/netapi/rest_cherrypy/init.py 的start()函数中其关键流程如下通过apiopts.get(ssl_ca_certs)与apiopts.get(ssl_cert_reqs)读取配置只要二者任一被设置即进入客户端证书校验分支if ssl_ca_certs or ssl_cert_reqs:使用ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)创建默认上下文——注意用途是CLIENT_AUTH明确要求对端客户端提供证书调用_ctx.load_cert_chain(certfilessl_crt, keyfilessl_key)加载服务端证书链若配置了ssl_ca_certs调用_ctx.load_verify_locations(ssl_ca_certs)加载信任锚若配置了ssl_cert_reqs通过getattr(_ssl, ssl_cert_reqs)将字符串映射为CERT_NONE/CERT_OPTIONAL/CERT_REQUIRED常量并赋值给_ctx.verify_mode取值非法时抛出ValueError最后通过cherrypy.server.ssl_context _ctx将自定义上下文挂载到 CherryPy 服务器。值得注意的两个实现细节该分支独立于原有的cherrypy.server.ssl_module builtin方式默认路径仅配置ssl_certificate/ssl_private_key/ssl_certificate_chain而 mTLS 路径直接注入完整的SSLContext二者互斥且后者优先级更高。校验发生在CherryPy 服务器层面的 TLS 握手中早于任何 WSGI 应用代码执行因此能够做到 changelog 所描述的 before any HTTP request is processed任何 HTTP 请求被处理之前即拒绝。此外start()中还有一个verify_certs()辅助函数用于在启动阶段检查ssl_crt/ssl_key文件是否存在若缺失会直接给出使用tls.create_self_signed_cert生成证书的提示见init.py。五、证书 CN 白名单ssl_allowed_cn的应用层二次过滤mTLS 解决了证书是否由可信 CA 签发的问题但所有持有合法客户端证书的调用方仍彼此等价。rest_cherrypy在 3009.0 中同时提供的ssl_allowed_cn允许列表把控制粒度细化到证书 Subject CN。其实现为salt_ssl_cn_filter_tool()定义于 salt/netapi/rest_cherrypy/app.pydef salt_ssl_cn_filter_tool(): apiopts cherrypy.config.get(apiopts) or {} allowed apiopts.get(ssl_allowed_cn) if not allowed: return cn _client_cert_cn() if not cn or cn not in allowed: logger.error( ssl_allowed_cn: rejecting client with CN%r (not in allow list), cn, ) raise cherrypy.HTTPError(403, Client certificate CN not allowed)逻辑要点ssl_allowed_cn为空或未配置时该工具直接放行no-op不会影响既有部署配置后客户端 CN 不在允许列表内、或无法提取到 CN例如证书缺少 CN 字段时直接返回403 ForbiddenCN 的提取优先读取 WSGI 环境变量SSL_CLIENT_S_DN_CN当该变量未填充时典型场景为 CherryPy 内建 SSL 模块会回退解析SSL_CLIENT_CERT中的 PEM 证书内容提取 Subject CN保证兼容性。这一组合形成了完整的纵深防御TLS 握手层由ssl_ca_certsssl_cert_reqs把关证书是否可信应用层由ssl_allowed_cn把关调用方是否被授权。六、测试验证仓库中的单元测试证据仓库为该功能提供了专门的单元测试文件 tests/pytests/unit/netapi/cherrypy/test_ssl_cn_filter.py覆盖了以下关键行为可作为功能契约参考test_no_allow_list_is_noop未配置ssl_allowed_cn或配置为空列表时过滤器不做任何拦截test_allowed_cn_passesCN 在允许列表内时正常放行test_disallowed_cn_rejectedCN 不在列表内时抛出 403test_missing_cn_rejected即使证书由可信 CA 签发但缺失 CN 字段时同样被 403 拒绝test_pem_fallback_allowed_cn_passes与test_pem_fallback_disallowed_cn_rejected验证SSL_CLIENT_S_DN_CN未填充时从SSL_CLIENT_CERTPEM 回退提取 CN 的路径。上述测试通过MagicMock模拟 CherryPy 的 config/request 环境说明该过滤逻辑是纯 WSGI 层面的工具函数便于在非完整 CherryPy 环境下单测也从侧面印证了其可插拔的设计。七、安全实践与注意事项CERT_REQUIRED才是完整 mTLSCERT_OPTIONAL仅在校验客户端主动出示证书时生效若你的威胁模型要求无证书不可访问务必设置为CERT_REQUIRED。信任锚与客户端证书分离管理ssl_ca_certs只放客户端 CA避免与系统 CA 信任库混用客户端证书需独立签发并妥善保管私钥。务必同时配置 eauthmTLS 解决的是谁能建立 TLS 连接rest_cherrypy的认证仍依赖外部认证eauth体系__init__.py中__virtual__()只要求配置段存在且含port不会绕过认证两层缺一不可。Windows 平台限制rest_cherrypy在 Windows 上为实验性支持且不支持 SSL需disable_ssl: TruemTLS 相关配置主要面向 Linux/Unix 生产部署见 app.py。不要忘记 eauth 之外的兜底即使启用 mTLS密码/凭据类认证的账号安全策略如轮换、最小权限仍应继续执行证书是额外的信任边界而非替代品。八、小结ssl_ca_certs与ssl_cert_reqs的引入让 salt-api 的rest_cherrypy从仅服务端认证升级为完整的双向 TLS在握手阶段即可拒绝无合法客户端证书的连接有效缩小了凭据泄露带来的攻击面。配合同一版本引入的ssl_allowed_cnCN 白名单可以在不改变业务代码的前提下实现证书 CN eauth三层叠加的访问控制。相关配置说明、实现源码与单元测试分别位于 app.py、init.py 与 test_ssl_cn_filter.py读者可据此深入研读或参照落地。赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Traefik 双向 TLSmTLS客户端证书认证从 clientca 测试证书生成到 clientAuth 配置实战Traefik 双向 TLSmTLS客户端证书认证从 clientca 测试证书生成到 clientAuth 配置实战 本文以仓库 integration后端API网关负载均衡微服务网络云原生ingress-nginx 客户端证书认证mTLS实战基于 auth-tls 注解实现双向 TLS 身份验证ingress nginx 客户端证书认证mTLS实战基于 auth tls 注解实现双向 TLS 身份验证 导读 本文以 ingress nginx 官后端API网关负载均衡云原生如何永久保存微信聊天记录WeChatMsg完全免费备份终极指南如何永久保存微信聊天记录WeChatMsg完全免费备份终极指南 你是否曾因手机损坏而丢失珍贵的微信聊天记录或是担心更换设备时无法迁移多年的对话历史在数字时上一篇从30秒到3秒Sealos容器启动速度的10倍优化实战下一篇2025 MaterialDesignInXamlToolkit新范式从MD2到MD3的迁移指南与性能革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考