企业官网建设流程全解析

• 后端
• 网络

本篇指南讲解如何在 cpp-httplib 的 mTLS（双向 TLS）服务中，于请求处理函数内通过req.peer_cert()读取客户端证书，提取 CN、签发者、序列号、有效期与 SAN 等字段，并基于证书信息实现路由级授权。读完本文，你将掌握tls::PeerCert的完整 API、证书字段的底层实现原理，以及结合set_pre_request_handler将鉴权逻辑集中到一处的工程实践。

前置条件：mTLS 已启用

req.peer_cert()只在mTLS 场景下才有实际意义。普通 TLS 只验证服务器证书，而 mTLS（mutual TLS）额外要求客户端也出示证书并由服务器验证——这正是零信任 API 到 API 调用、内部系统认证的常见做法。在 cpp-httplib 中启用 mTLS 的方式是把签发客户端证书的 CA 作为SSLServer构造函数的第三、四个参数传入：

httplib::SSLServer svr( "server-cert.pem", // 服务器证书 "server-key.pem", // 服务器私钥 "client-ca.pem", // 签发合法客户端证书的 CA nullptr // CA 目录（无） ); svr.Get("/", [](const httplib::Request &req, httplib::Response &res) { res.set_content("authenticated", "text/plain"); }); svr.listen("0.0.0.0", 443);

凡是客户端证书不是由client-ca.pem签发的连接，都会在 TLS 握手阶段被拒绝；等处理函数运行时，客户端已经通过了身份验证。完整的手握手配置（含PemMemory内存 PEM 方式与客户端侧SSLClient传证）见 T04. Configure mTLS。需要特别说明：本文所有能力都以CPPHTTPLIB_SSL_ENABLED编译开关为前提，非 SSL 构建下peer_cert()并不存在。

基本用法：在 handler 中读取对端证书

在任意路由处理函数中，通过req.peer_cert()即可拿到客户端证书的封装对象。返回类型是tls::PeerCert，它可以隐式转换为 bool，因此必须先做存在性检查再使用：

svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) { auto cert = req.peer_cert(); if (!cert) { res.status = 401; res.set_content("no client certificate", "text/plain"); return; } auto cn = cert.subject_cn(); res.set_content("hello, " + cn, "text/plain"); });

这段代码覆盖了两种常见场景：

• 未出示证书：cert为假值，直接以401 Unauthorized拒绝；
• 已出示证书：取出 CN（Common Name）作为用户标识，写入响应。

仓库测试 test/test.cc 中的ClientCertPresent用例完整验证了这一流程：服务端在/testhandler 内断言static_cast<bool>(cert)为真，并校验cert.subject_cn()等于测试证书的 CN 值"Common Name"；测试客户端使用SSLClient cli(HOST, PORT, client_cert_file, client_private_key_file)携带客户端证书发起请求。该测试还覆盖了加密私钥场景（ClientEncryptedCertPresent，私钥口令作为SSLClient第五个参数），以及 PemMemoryClientCertPresent 的内存 PEM 构造方式。

PeerCert 的底层设计与可用字段

从源码看，PeerCert定义在 httplib.h 的httplib::tls命名空间内，是一个基于 RAII 的证书封装：

• 构造函数私有，只能由库内部通过get_peer_cert_from_session()工厂创建；
• 拷贝构造与拷贝赋值被显式 delete，只能移动（move-only），因此不要试图把PeerCert存进容器或反复拷贝，拿到后应在当前作用域内消费；
• 析构时自动释放底层后端证书句柄（free_cert(cert_)），见 实现代码；
• explicit operator bool() const检查内部cert_指针是否非空，对应文档中"可转换为 bool"的说明。

Request::peer_cert()的实现非常简洁——它把请求关联的 TLS 会话交给get_peer_cert_from_session()取出证书：

// httplib.h L18921-L18923 inline tls::PeerCert Request::peer_cert() const { return tls::get_peer_cert_from_session(ssl); }

底层get_peer_cert()按 TLS 后端分派：OpenSSL 后端在 httplib.h 通过SSL_get1_peer_certificate获取，mbedTLS 后端在 httplib.h 通过mbedtls_ssl_get_peer_cert获取，因此同一套PeerCertAPI 对 OpenSSL 与 mbedTLS 两个后端行为一致。

从PeerCert实例可以读取以下字段（各方法均有对应后端实现，见 httplib.h）：

auto cert = req.peer_cert(); std::string cn = cert.subject_cn(); // 证书 CN（Common Name） std::string issuer = cert.issuer_name(); // 签发者名称 std::string serial = cert.serial(); // 序列号 time_t not_before, not_after; cert.validity(not_before, not_after); // 有效期起止（Unix 时间戳） auto sans = cert.sans(); // SAN 列表 for (const auto &san : sans) { std::cout << san.value << std::endl; }

各方法要点：

• subject_cn()：返回证书主体的 CN 字段，是 mTLS 场景下最常见的"用户身份"来源；
• issuer_name()：返回签发者名称，可用来校验证书是由内部 CA 还是第三方 CA 签发的；
• serial()：返回证书序列号字符串，适合作为精确的设备/用户指纹做白名单比对；
• validity(not_before, not_after)：以输出参数形式返回有效期起止时间，可自行判断证书是否过期（mTLS 握手阶段通常会做有效期校验，但业务层二次检查也常见）；
• sans()：返回std::vector<SanEntry>。SanEntry结构体定义在 httplib.h，包含SanType type（枚举取值DNS、IP、EMAIL、URI、OTHER）与std::string value，便于按类型区分证书里携带的 DNS 名、IP 地址或邮箱；
• 需要留意：PeerCert为空对象时，上述字段访问方法返回空字符串/空列表/false，不会崩溃——这正是bool检查之外的另一层安全兜底。

主机名匹配辅助：check_hostname

除字段读取外，PeerCert还提供主机名校验辅助方法，用于判断某个主机名是否被证书的 SAN 列表覆盖：

if (cert.check_hostname("alice.corp.example.com")) { // 匹配：该主机名在证书 SAN 覆盖范围内 }

底层调用verify_hostname()，同时支持精确匹配与通配符匹配。这一点在测试 TlsVerifyHostname 中有直接印证：测试用ctx.check_hostname("Common Name")对测试服务器证书 CN 返回匹配，而对"wronghost.example.com"返回不匹配。该函数对 OpenSSL 与 mbedTLS 两个后端都要求行为一致。在 mTLS 场景下，check_hostname特别适合"按域名签发证书、按请求 Host 校验"的细粒度访问控制。

基于证书的授权：用 pre-request handler 统一把关

PeerCert真正的工程价值在于把它放进预请求钩子，实现"一处鉴权、全局生效"。由于鉴权逻辑与具体业务 handler 解耦，所有证书检查集中在单个回调中，维护成本更低：

svr.set_pre_request_handler( [](const httplib::Request &req, httplib::Response &res) { auto cert = req.peer_cert(); if (!cert) { res.status = 401; return httplib::Server::HandlerResponse::Handled; } if (req.matched_route.rfind("/admin", 0) == 0) { auto cn = cert.subject_cn(); if (!is_admin_cn(cn)) { res.status = 403; return httplib::Server::HandlerResponse::Handled; } } return httplib::Server::HandlerResponse::Unhandled; });

这段代码体现了三个关键设计点：

1. 全局证书检查：任何请求只要拿不到客户端证书，一律401；
2. 路由级授权：通过req.matched_route判断路由是否以/admin开头，只对管理路由做 CN 白名单校验，普通路由放行；
3. 返回值语义：返回HandlerResponse::Handled表示"处理完成、跳过业务 handler"，Unhandled表示"继续执行路由 handler"。HandlerResponse与set_pre_request_handler的签名定义在 httplib.h 与 httplib.h。

pre-request与pre-routing的区别在这里至关重要：set_pre_routing_handler()在路由匹配之前运行，拿不到matched_route；而set_pre_request_handler()在路由匹配之后、业务 handler之前运行，req.matched_route中保存的是未展开路径参数的路由模式串（如/admin/users/:id），因此按路由模式前缀匹配即可精确控制鉴权范围，且此时请求体尚未被读取，被拒绝的请求不会消费潜在的巨大 body。完整的钩子语义对比与返回值说明见 S11. Authenticate Per Route with a Pre-Request Handler。

如果希望把解析出的证书信息（如 CN）传递给后续业务 handler，可在set_pre_request_handler中写入res.user_data，具体做法参考 S12. Pass Data Between Handlers。

关于 SNI 与 mTLS 的边界说明

文档对 SNI（Server Name Indication）给出了明确的定位：cpp-httplib 自动处理 SNI。当一个服务器托管多个域名时，SNI 在底层握手阶段由 TLS 栈透明完成，handler 通常无需关心。若确需在应用层读取客户端请求的 SNI 值（例如区分虚拟主机），源码提供了Request::sni()，实现位于 httplib.h，返回请求关联会话的 SNI 字符串；这与peer_cert()同属CPPHTTPLIB_SSL_ENABLED条件下的Request扩展能力。

最后必须强调一个容易踩坑的边界：

警告：req.peer_cert()只有在mTLS 已启用且客户端确实出示了证书时才返回有意义的PeerCert。对于普通 TLS（服务器单向验证），它返回一个空的PeerCert——bool 值为false。因此在任何场景下，使用证书字段前都应先做bool检查（if (!cert) { ... }）。

这条规则的背后是握手流程的客观约束：单向 TLS 下对端（客户端）根本没有提交证书，TLS 会话中自然取不到证书句柄，get_peer_cert()返回空指针。若想做到"客户端可选出示证书、出示则识别身份"的弹性策略，可以在 mTLS 配置下配合ssl_verifier（SSLServer构造的会话验证回调，类型定义见 httplib.h 的SSLVerifierResponse）灵活放行，但证书字段的空值检查仍然不可省略。

完整示例：从验证到识别的一条龙实践

将以上要素组合，一个"mTLS 认证 + 证书身份识别 + 路由级授权"的完整服务端骨架如下：

#include "httplib.h" int main() { // 1) mTLS：以 client-ca.pem 校验客户端证书 httplib::SSLServer svr("server-cert.pem", "server-key.pem", "client-ca.pem", nullptr); // 2) 统一鉴权：无证书一律 401，/admin 路由校验 CN 白名单 svr.set_pre_request_handler( [](const httplib::Request &req, httplib::Response &res) { auto cert = req.peer_cert(); if (!cert) { res.status = 401; res.set_content("client certificate required", "text/plain"); return httplib::Server::HandlerResponse::Handled; } if (req.matched_route.rfind("/admin", 0) == 0) { auto cn = cert.subject_cn(); if (cn != "admin-alice" && cn != "admin-bob") { res.status = 403; res.set_content("forbidden", "text/plain"); return httplib::Server::HandlerResponse::Handled; } } return httplib::Server::HandlerResponse::Unhandled; }); // 3) 业务 handler 内按需读取证书细节 svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) { auto cert = req.peer_cert(); std::string info = "cn=" + cert.subject_cn() + "; issuer=" + cert.issuer_name() + "; serial=" + cert.serial(); res.set_content(info, "text/plain"); }); svr.Get("/admin/stats", [](const httplib::Request &, httplib::Response &res) { res.set_content("top secret stats", "text/plain"); }); svr.listen("0.0.0.0", 443); }

配合仓库已有的测试基建（测试证书与 CA 由 test/gen-certs.sh 生成），可直接在本地复现：客户端用SSLClient携带自己的证书请求/me可读到 CN 回显，不带证书请求则收到401，非白名单证书请求/admin/stats收到403。

小结

• 服务端读取对端证书的唯一入口是req.peer_cert()，返回tls::PeerCert，使用前务必做 bool 检查；
• PeerCert提供subject_cn/issuer_name/serial/validity/sans/check_hostname六类信息，底层由 OpenSSL 与 mbedTLS 两个后端统一实现；
• 结合set_pre_request_handler与HandlerResponse，可在路由匹配之后、业务 handler 之前统一完成"有无证书 → 是否授权"的裁决，并把鉴权逻辑收敛到单一位置；
• mTLS 的完整启用方式（证书文件参数与PemMemory内存 PEM）见 T04. Configure mTLS；预请求钩子的路由匹配语义见 S11. Authenticate Per Route with a Pre-Request Handler。

• 后端
• 网络