区块链密码学【免费下载链接】fabricHyperledger Fabric is an enterprise-grade permissioned distributed ledger framework for developing solutions and applications. Its modular and versatile design satisfies a broad range of industry use cases. It offers a unique approach to consensus that enables performance at scale while preserving privacy.项目地址https://gitcode.com/gh_mirrors/fabr/fabric点击查看免费下载导读Hyperledger Fabric 是一个面向企业级场景的许可制permissioned分布式账本框架节点之间的通信安全是生产部署的第一道防线。本文以官方文档 docs/source/enable_tls.rst 为骨架系统讲解如何为 Fabric 的 peer 节点、orderer 节点以及 peer CLI 启用 TLSTransport Layer Security涵盖单向仅服务器认证与双向mutual TLS服务器与客户端互相认证两种模式。读完本文你将掌握core.yaml、orderer.yaml中全部 TLS 配置项的语义与默认值会用环境变量、命令行参数正确配置 TLS理解 Subject Alternative NamesSAN对证书校验的关键作用并能根据常见报错信息快速定位 TLS 问题。文中所有配置项、默认值与行为均对照本仓库GitHub 加速计划 / fabr / fabric的实际配置文件与源码逐一核实。TLS 在 Fabric 中的角色单向认证与双向认证Fabric 使用 TLS 保护节点间、节点与客户端应用、CLI之间的所有 gRPC 通信。TLS 提供两类能力单向认证one-wayTLS 服务器出示证书客户端验证服务器身份确认服务器证书由受信任的 CA 签发随后建立加密通道。连接是否建立由客户端单方面信任决定。双向认证two-way / mutual TLS服务器不仅出示自己的证书还要求客户端在握手阶段出示证书并验证其合法性。双方互相验证身份安全性更高通常用于企业网络内部节点互连。在 Fabric 的默认设计中peer 节点和 orderer 节点在启用 TLS 时默认不要求客户端认证即单向模式peer.tls.clientAuthRequired/General.TLS.ClientAuthRequired默认均为false。是否开启双向认证取决于你对网络安全边界的诉求。Peer 是双重角色一个 peer 节点同时扮演两种 TLS 角色作为 TLS 服务器当其他 peer 节点、应用程序或 CLI 向它发起连接时它验证对方或仅向对方出示自己的证书。作为 TLS 客户端当它主动连接其他 peer 节点或 orderer 节点时例如通过 gossip 同步区块、向 orderer 拉取区块。这种双重角色意味着 peer 同时需要服务器证书/私钥和可选客户端证书/私钥两组密钥材料。从源码看peer 的 gRPC 服务器配置在 core/peer/config.go 中根据peer.tls.*系列配置构造serverConfig.SecOpts而作为客户端时的证书则通过GetClientCertificate()core/peer/config.go加载。为 Peer 节点配置 TLS配置文件方式core.yamlpeer 节点的所有 TLS 设置位于 sampleconfig/core.yaml 的peer.tls小节。启用 TLS 需要设置以下三个核心属性配置项默认值sampleconfig说明peer.tls.enabledfalse是否启用服务器端 TLSpeer.tls.cert.filetls/server.crtTLS 服务器证书文件的完整路径peer.tls.key.filetls/server.keyTLS 服务器私钥文件的完整路径示例配置peer: tls: # Require server-side TLS enabled: true # Require client certificates / mutual TLS for inbound connections. # Note that clients that are not configured to use a certificate will # fail to connect to the peer. clientAuthRequired: false # X.509 certificate used for TLS server cert: file: /path/to/peer/tls/server.crt # Private key used for TLS server key: file: /path/to/peer/tls/server.key启用双向认证客户端认证默认情况下即使启用了 TLSpeer 也不会验证客户端的证书。要开启 TLS 客户端认证mTLS需额外设置配置项说明peer.tls.clientAuthRequired设为true时要求入站连接携带客户端证书peer.tls.clientRootCAs.files包含签发你组织客户端 TLS 证书的 CA 证书链文件列表对应 sampleconfig 中的默认结构sampleconfig/core.yaml# If mutual TLS is enabled, clientRootCAs.files contains a list of additional root certificates # used for verifying certificates of client connections. # It augments the set of TLS CA certificates available from the MSPs of each channels configuration. # Minimally, set your organizations TLS CA root certificate so that the peer can receive join channel requests. clientRootCAs: files: - /path/to/tls/ca.crt注意clientRootCAs.files的注释提醒即使 peer 尚未加入任何通道也需要至少配置组织自己的 TLS CA 根证书否则 peer 无法正常接收加入通道join channel请求。为客户端角色使用独立的证书默认情况下peer 在作为 TLS 服务器和作为 TLS 客户端时复用同一对证书/私钥。如果需要区分例如客户端证书由不同的 CA 签发或者出于证书轮换的考虑可设置配置项说明peer.tls.clientCert.file作为客户端连接时使用的 X.509 证书peer.tls.clientKey.file作为客户端连接时使用的私钥sampleconfig 中的注释明确了回退逻辑sampleconfig/core.yaml如果未设置则clientKey回退使用peer.tls.key.fileclientCert回退使用peer.tls.cert.file。源码侧的逻辑与此一致在 core/peer/config.go 的GetClientCertificate()中若peer.tls.clientKey.file与peer.tls.clientCert.file两个都为空则复用服务器密钥对若只设置其中一个而未设置另一个会直接返回错误peer.tls.clientKey.file and peer.tls.clientCert.file must both be set or must both be empty。这提醒我们客户端证书与客户端私钥必须成对配置不能只配其一。环境变量方式peer 节点的 TLS 配置同样可以通过环境变量注入这些环境变量是 viper 对peer.tls.*的映射遵循CORE_前缀 大写 点号转下划线的规则环境变量对应配置项值CORE_PEER_TLS_ENABLEDpeer.tls.enabledtrueCORE_PEER_TLS_CERT_FILEpeer.tls.cert.file服务器证书的完整路径CORE_PEER_TLS_KEY_FILEpeer.tls.key.file服务器私钥的完整路径CORE_PEER_TLS_CLIENTAUTHREQUIREDpeer.tls.clientAuthRequiredtrueCORE_PEER_TLS_CLIENTROOTCAS_FILESpeer.tls.clientRootCAs.filesCA 证书链文件的完整路径CORE_PEER_TLS_CLIENTCERT_FILEpeer.tls.clientCert.file客户端证书的完整路径CORE_PEER_TLS_CLIENTKEY_FILEpeer.tls.clientKey.file客户端私钥的完整路径示例export CORE_PEER_TLS_ENABLEDtrue export CORE_PEER_TLS_CERT_FILE/path/to/peer/tls/server.crt export CORE_PEER_TLS_KEY_FILE/path/to/peer/tls/server.key export CORE_PEER_TLS_CLIENTAUTHREQUIREDtrue export CORE_PEER_TLS_CLIENTROOTCAS_FILES/path/to/tls/ca.crt export CORE_PEER_TLS_CLIENTCERT_FILE/path/to/peer/tls/client.crt export CORE_PEER_TLS_CLIENTKEY_FILE/path/to/peer/tls/client.key关键行为当 peer 启用了客户端认证后任何客户端在 TLS 握手时必须出示证书如果客户端没有发送证书握手将失败peer 会直接关闭连接。这是生产环境中最常见的客户端连不上的原因之一。通道成员根 CA 的自动加载当 peer 加入某个通道时会从该通道的配置块config block中读取所有通道成员的根 CA 证书链并加入其 TLS 服务器端和客户端根 CA 数据结构。这意味着在大多数正常组网场景下peer 与 peer、peer 与 orderer 之间的 TLS 通信可以开箱即用无需手工配置对方的根证书。如果需要扩充额外的受信任根证书可通过peer.tls.rootcert.file用于验证出站连接中其他节点的证书和peer.tls.clientRootCAs.files用于验证入站客户端连接补充。rootcert在 sampleconfig 中默认为tls/ca.crt注释说明其作用是在出站连接中验证其他节点证书且并非必填——因为通道 MSP 已提供大部分根证书sampleconfig/core.yaml。为 Orderer 节点配置 TLS配置文件方式orderer.yamlorderer 节点的 TLS 配置位于 sampleconfig/orderer.yaml 的General.TLS小节General: # TLS: TLS settings for the GRPC server. TLS: # Require server-side TLS Enabled: false # PrivateKey governs the file location of the private key of the TLS certificate. PrivateKey: tls/server.key # Certificate governs the file location of the server TLS certificate. Certificate: tls/server.crt # RootCAs contains a list of additional root certificates used for verifying certificates # of other orderer nodes during outbound connections. # It is not required to be set, but can be used to augment the set of TLS CA certificates # available from the MSPs of each channels configuration. RootCAs: - tls/ca.crt # Require client certificates / mutual TLS for inbound connections. ClientAuthRequired: false # If mutual TLS is enabled, ClientRootCAs contains a list of additional root certificates # used for verifying certificates of client connections. # It is not required to be set, but can be used to augment the set of TLS CA certificates # available from the MSPs of each channels configuration. ClientRootCAs:启用 TLS 的核心配置项配置项默认值sampleconfig说明General.TLS.Enabledfalse是否启用服务器端 TLSGeneral.TLS.PrivateKeytls/server.key服务器私钥文件的完整路径General.TLS.Certificatetls/server.crt服务器证书文件的完整路径General.TLS.RootCAs[tls/ca.crt]出站连接中验证其他 orderer 节点的额外根证书列表General.TLS.ClientAuthRequiredfalse是否要求入站连接的客户端证书mTLSGeneral.TLS.ClientRootCAs空开启 mTLS 后用于验证客户端证书的额外根证书列表与 peer 一样orderer 默认关闭客户端认证要启用双向认证将General.TLS.ClientAuthRequired设为true。环境变量方式orderer 对应的环境变量规则为ORDERER_前缀对应General点号转下划线环境变量对应配置项ORDERER_GENERAL_TLS_ENABLEDGeneral.TLS.EnabledORDERER_GENERAL_TLS_PRIVATEKEYGeneral.TLS.PrivateKeyORDERER_GENERAL_TLS_CERTIFICATEGeneral.TLS.CertificateORDERER_GENERAL_TLS_CLIENTAUTHREQUIREDGeneral.TLS.ClientAuthRequired示例export ORDERER_GENERAL_TLS_ENABLEDtrue export ORDERER_GENERAL_TLS_PRIVATEKEY/path/to/orderer/tls/server.key export ORDERER_GENERAL_TLS_CERTIFICATE/path/to/orderer/tls/server.crt export ORDERER_GENERAL_TLS_CLIENTAUTHREQUIREDtrueorderer 的 TLS 配置在 orderer/common/server/main.go 中被读取UseTLS、RequireClientCert取自General.TLS随后通过os.ReadFile加载证书、私钥并将RootCAs、ClientRootCAs解析进安全选项最终构造 gRPC 服务器。同样地orderer 加入通道后也会从通道配置块中加载成员根 CA 到服务器/客户端根 CA 数据结构因此 orderer 与 orderer 之间的通信通常无需手工配根证书需要扩充时使用General.TLS.RootCAs与General.TLS.ClientRootCAs。补充集群内部与运维端点的 TLS如果你的 orderer 使用 Raftetcdraft或 BFT 共识orderer 节点之间还会建立集群内部intra-cluster连接这部分 TLS 由General.Cluster小节控制sampleconfig/orderer.yamlGeneral.Cluster.ClientCertificate/General.Cluster.ClientPrivateKeyorderer 作为客户端与其他 orderer 建立 mTLS 连接时使用的证书与私钥未设置时复用General.TLS.Certificate/General.TLS.PrivateKey。General.Cluster.ServerCertificate/General.Cluster.ServerPrivateKey仅当同时设置了ListenPort与ListenAddress即使用独立监听器处理集群内部通信时生效用于为集群内部监听器提供独立的服务器证书。此外operations 服务端点Operations.TLS与 admin 服务端点Admin.TLS也有独立的 TLS 配置sampleconfig/orderer.yaml。注意当 admin 端点启用 TLS 时强制要求 mTLS且所有资源都必须通过 TLS 层的客户端认证才能访问这是 channel participation API 的安全前提。配置 Peer CLI 使用 TLS当使用 peer CLI 连接启用了 TLS 的 peer 节点时必须设置以下环境变量环境变量说明CORE_PEER_TLS_ENABLED必须为trueCORE_PEER_TLS_ROOTCERT_FILE签发 TLS 服务器证书的 CA 证书链文件的完整路径示例export CORE_PEER_TLS_ENABLEDtrue export CORE_PEER_TLS_ROOTCERT_FILE/path/to/peer-ca-chain.pem注意区分CLI 需要的是CORE_PEER_TLS_ROOTCERT_FILE用于验证服务器证书而 peer 服务端配置验证客户端证书用的是peer.tls.clientRootCAs.files。两者方向相反不要混淆。当服务器启用了 mTLS 时如果远程 peer或 orderer同时启用了客户端认证CLI 还必须额外设置export CORE_PEER_TLS_CLIENTAUTHREQUIREDtrue export CORE_PEER_TLS_CLIENTCERT_FILE/path/to/client.crt export CORE_PEER_TLS_CLIENTKEY_FILE/path/to/client.keyCLI 侧的实际加载逻辑可参考 internal/peer/common/peerclient.go 与 internal/peer/common/common.go客户端连接通过 viper 读取peer.tls.clientAuthRequired等配置这些环境变量与 peer 节点自身的peer.tls.*配置共用一套 viper 键从而决定是否在 gRPC 连接中附加客户端证书。连接 orderer 服务的命令行参数当执行与 orderer 服务交互的命令如peer channel create|update|fetch、peer chaincode invoke时如果 orderer 启用了 TLS还必须附加以下命令行参数参数说明--tls启用与 orderer 的 TLS 连接--cafile pathorderer CA 证书链文件的完整路径如果 orderer 启用了客户端认证还需附加参数说明--clientauth启用客户端认证--keyfile path客户端私钥的完整路径--certfile path客户端证书的完整路径这些参数在 internal/peer/common/ordererenv.go 中定义并绑定到 viper 的orderer.tls.*配置--tls对应orderer.tls.enabled--cafile对应orderer.tls.rootcert.file--clientauth对应orderer.tls.clientAuthRequired--keyfile/--certfile对应orderer.tls.clientKey.file/orderer.tls.clientCert.file。其测试用例internal/peer/common/ordererenv_test.go验证了这些参数会被正确写入 viper 配置。与代理服务器Proxy共存必须 TLS Passthrough由于 Fabric 的各组件之间通过 TLS 互相验证身份服务器证书由客户端校验、客户端证书由服务器校验因此如果网络前方部署了代理服务器代理必须配置为 TLS passthrough透传不终止 TLS模式将加密的流量原样转发给 Fabric 组件。任何在代理层终止 TLS、重新加密或解密的方案都会破坏端到端的证书校验链导致握手失败。这一点对任何中间件负载均衡器、反向代理、API 网关同样适用。Subject Alternative NamesSAN服务器证书的关键要素每个 TLS 服务器证书必须包含一个或多个 Subject Alternative NameSANSAN 指定了该服务器的域名或 IP 地址。TLS 客户端连接服务器时会校验服务器证书中的某个 SAN 是否与它正在连接的地址匹配不匹配则拒绝连接。这是 X.509 证书在现代 TLS 实现中的强制要求Go 的crypto/tls在验证时仅信任 SAN不再信任 CN 字段。因此创建 TLS 证书时必须显式指定 SAN使用 Fabric CA 签发 TLS 证书在fabric-ca-client enroll命令中通过--csr.hosts参数以逗号分隔列表指定 SAN。例如fabric-ca-client enroll -u https://admin:adminpwca.example.com:7054 \ --csr.hosts peer0.org1.example.com,peer0.org1,127.0.0.1 \ --enrollment.profile tls使用 cryptogen 生成 TLS 证书在 cryptogen 的配置 YAML 中通过节点的SANS元素以列表形式指定。本仓库 cmd/cryptogen/main.go 的内置模板对SANS的说明如下SANS可选指定要写入生成证书中的一个或多个 Subject Alternative Name支持模板变量{{.Hostname}}、{{.Domain}}、{{.CommonName}}。此处提供的 IP 地址会被正确识别为 IP SAN其他值将被视为 DNS 名称。注意系统会自动为你隐式创建两个条目{{.CommonName}}和{{.Hostname}}。一个实际示例来自 cryptogen 模板对应 cmd/cryptogen/main.goSpecs: - Hostname: foo # implicitly foo.org1.example.com CommonName: foo27.org5.example.com # overrides Hostname-based FQDN set above SANS: - bar.{{.Domain}} - altfoo.{{.Domain}} - {{.Hostname}}.org6.net - 172.16.10.31 PublicKeyAlgorithm: ecdsa - Hostname: bar - Hostname: baz如果使用Template方式批量生成节点同样可以为每个模板节点配置SANS列表cmd/cryptogen/main.go。源码中 cmd/cryptogen/main.go 展示了生成流程先写入 CN 与 Hostname 两个隐式 SAN再把用户显式配置的 SANS 逐一追加进去测试用例 internal/cryptogen/ca/ca_test.go 也验证了 SAN 会被正确写入证书。在 Kubernetes 等容器化环境中SAN 必须同时包含 service 名称、pod 名称以及 nodePort/Ingress 地址在本地开发或 Docker 网络中运行 peer/orderer 时通常需要把127.0.0.1、localhost以及容器网络中的主机名一并加入 SAN。排查 TLS 常见问题错误一服务器侧报remote error: tls: bad certificate如果错误出现在服务器侧例如 peer 节点或 orderer 节点上当客户端发起请求时通常意味着客户端不信任服务器 TLS 证书的签发者。请检查客户端侧的信任配置连接 peer 节点时检查客户端的CORE_PEER_TLS_ROOTCERT_FILE是否正确指向签发 peer 服务器证书的 CA 链连接 orderer 节点时检查命令行参数--cafile是否指向签发 orderer 服务器证书的 CA 链。对应的客户端侧错误通常是握手失败x509: certificate signed by unknown authority最终连接报context deadline exceeded。错误二SAN 不匹配如果问题出在 Subject Alternative Name 上客户端侧的握手错误会是tls: failed to verify certificate: x509: certificate is valid for configured_SAN, not attempted_address这表示你连接时使用的地址attempted_address不在服务器证书的 SAN 列表中。解决方法是重新签发证书把实际访问地址加入 SAN或改用证书中已有的 SAN 地址去连接。错误三客户端侧报remote error: tls: bad certificate如果错误出现在客户端侧通常意味着服务器启用了客户端认证mTLS而客户端未发送证书或发送的证书不被服务器信任。请确认客户端是否配置并发送了证书peer CLI 的CORE_PEER_TLS_CLIENTCERT_FILE、CORE_PEER_TLS_CLIENTKEY_FILE或连接 orderer 时的--clientauth --certfile --keyfile客户端证书是否由服务器所信任的某个 CA 签发服务器的peer.tls.clientRootCAs.files/General.TLS.ClientRootCAs列表中应包含该 CA。开启 gRPC debug 日志要获得更详细的握手诊断信息可以在 TLS 客户端和服务器两侧同时启用 gRPC 的 DEBUG 日志设置环境变量FABRIC_LOGGING_SPEC使其包含grpcdebug。例如将默认日志级别设为INFO、gRPC 日志级别设为DEBUGexport FABRIC_LOGGING_SPECgrpcdebug:info使用 openssl 验证证书链还可以使用openssl verify命令将 TLS 证书与受信任的 CA 证书对照检查# 验证服务器证书是否由指定 CA 签发且链完整 openssl verify -CAfile /path/to/ca-chain.pem -verbose /path/to/server.crt该命令能快速确认证书链完整性、过期时间等问题是 TLS 排障的第一步。总结配置清单速查角色单向 TLS 最小配置mTLS 追加配置peer 节点core.yamlpeer.tls.enabled: true、peer.tls.cert.file、peer.tls.key.filepeer.tls.clientAuthRequired: true、peer.tls.clientRootCAs.files、可选peer.tls.clientCert.file/clientKey.fileorderer 节点orderer.yamlGeneral.TLS.Enabled: true、General.TLS.Certificate、General.TLS.PrivateKeyGeneral.TLS.ClientAuthRequired: true、可选General.TLS.ClientRootCAspeer CLI连 peerCORE_PEER_TLS_ENABLEDtrue、CORE_PEER_TLS_ROOTCERT_FILECORE_PEER_TLS_CLIENTAUTHREQUIREDtrue、CORE_PEER_TLS_CLIENTCERT_FILE、CORE_PEER_TLS_CLIENTKEY_FILEpeer CLI连 orderer--tls、--cafile--clientauth、--certfile、--keyfile三个容易踩坑的要点再强调一遍证书与私钥必须成对配置clientCert.file/clientKey.file只配其一会被源码直接拒绝core/peer/config.go。SAN 决定一切服务器证书的 SAN 必须覆盖客户端实际访问的域名/IP否则握手必然失败。根证书信任方向要分清验证出站连接对方用rootcert/RootCAs/CORE_PEER_TLS_ROOTCERT_FILE验证入站客户端用clientRootCAs/ClientRootCAs两者方向相反配置错误时表现出的错误信息也不同。本文所有配置项默认值均来自仓库 sampleconfig/core.yaml 与 sampleconfig/orderer.yaml行为逻辑来自 core/peer/config.go、orderer/common/server/main.go、internal/peer/common/ordererenv.go 等源码实现可放心作为生产部署与排障的参考。赞分享区块链密码学【免费下载链接】fabricHyperledger Fabric is an enterprise-grade permissioned distributed ledger framework for developing solutions and applications. Its modular and versatile design satisfies a broad range of industry use cases. It offers a unique approach to consensus that enables performance at scale while preserving privacy.项目地址https://gitcode.com/gh_mirrors/fabr/fabric点击查看免费下载相关推荐如何将grande.js无缝集成到React/Vue项目打造Medium风格的富文本编辑器如何将grande.js无缝集成到React/Vue项目打造Medium风格的富文本编辑器 grande.js是一个轻量级的JavaScript库专门为现代前端UI库/组件Flink SSL/TLS 安全配置完全指南内部连接与 REST 端点的双向认证实战Flink SSL/TLS 安全配置完全指南内部连接与 REST 端点的双向认证实战 Apache Flink 默认不启用任何传输层加密。当集群跨越不可信网络大数据流处理批处理数据工程如何在嵌入式设备上使用RKNN Model Zoo实现语音识别如何在嵌入式设备上使用RKNN Model Zoo实现语音识别 RKNN Model Zoo是一个强大的开源项目专为在瑞芯微Rockchip嵌入式设备上部示例工程人工智能嵌入式上一篇解决Prisma PostgreSQL适配器未定义属性问题的完整指南下一篇Alertmanager存储机制终极指南深入理解nflog与silence的持久化实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考