Android 浏览器死活不弹证书框的那天，我用 .NET MAUI 给 WebView 写了一个 mTLS 拦截器

给自建服务套上 mTLS（双向 TLS 认证）是很多人保护公网管理面板的最后一道墙：Nginx 只放行持有合法客户端证书的设备，扫描器、爆破脚本连 TLS 握手都过不去。

问题出在手机上。公众号「dotNET跨平台」刊发的一篇实战文章里，作者在给 OpenClaw 控制台配好 mTLS 网关之后发现，自己也被挡在了墙外：证书装进了 Android 系统，系统浏览器、Chrome、Firefox 却都不弹证书选择框。他的解法是用 .NET MAUI 写一个专用的“套壳浏览器” StealthClaw：App 自己读取 .pfx 证书，在 WebView 底层回调里直接把证书交给服务器。

这个思路很实用，但源文里有一处写法和“零信任”是矛盾的。本文先把它的核心实现讲清楚，再把这处安全缺口补上，最后用一个本地脚本把 mTLS 和证书指纹固定的效果完整跑一遍。

一、为什么系统浏览器不弹证书框

Android 上浏览器使用客户端证书，要经过系统 KeyChain：浏览器收到服务器的证书请求后，调用系统接口让用户从已安装的证书里挑一个。这条链路上有几个常见的断点：

证书装错了类别：Android 的证书安装界面区分“CA 证书”和“VPN 和应用用户证书”，客户端证书必须装成后者，并且 .pfx 里要带私钥；
服务端声明的 CA 列表不匹配：Nginx 在握手时会把 ssl_client_certificate 中的 CA 名称发给客户端，浏览器通常只列出由这些 CA 签发的证书。中间 CA、证书链不完整都可能导致“一个可选证书都没有”，于是看起来就像没弹框；
浏览器自身支持有限：不同浏览器、不同版本对系统客户端证书的支持程度不一样，有的使用自己的证书库。

逐个排查当然可以，但如果这个面板只给自己用，与其和系统规则较劲，不如写一个只做一件事的 App：证书由 App 自己保管，握手时由 App 自己交出去。

二、核心思路：在 WebViewClient 里接管证书请求

套壳浏览器的两个回调

Android 的 WebView 把 TLS 相关的关键时刻暴露为 WebViewClient 的两个回调：

OnReceivedClientCertRequest：服务器要求客户端证书时触发。调用 request.Proceed(privateKey, chain) 交出证书，request.Ignore() 表示不提供证书继续，request.Cancel() 取消请求；
OnReceivedSslError：服务端证书未通过系统校验时触发（比如自签证书），由 App 决定是继续还是取消。

MAUI 的 WebView 在 Android 上就是原生 WebView，通过 Handler 的 Mapper 就能替换成自定义的 WebViewClient。整体结构如下：

Mermaid Diagram

三、交出客户端证书：JavaCast 是绕不过去的坑

源文的拦截器做了三件事：从私有目录读取 .pfx 并用密码加载成 PKCS12 类型的 KeyStore；遍历别名，找到第一个带私钥的条目（IsKeyEntry）；取出私钥和证书链交给 request.Proceed。

其中最容易踩的坑是类型转换。KeyStore.GetKey 返回的是 Java 对象的 C# 包装，直接用 C# 的强制转换会抛出 Specified cast is not valid，必须用 Android.Runtime 提供的 JavaCast<T>() 走 JNI 做类型映射：

var rawKey = keyStore.GetKey(alias, password.ToCharArray());
var privateKey = rawKey.JavaCast<IPrivateKey>();

var chain = keyStore.GetCertificateChain(alias);
var x509Chain = new Java.Security.Cert.X509Certificate[chain.Length];
for (int i = 0; i < chain.Length; i++)
{
    x509Chain[i] = chain[i].JavaCast<Java.Security.Cert.X509Certificate>();
}
request.Proceed(privateKey, x509Chain);

在源文代码的基础上，有两处值得改进：

不要在回调里同步等待 SecureStorage：源文用 SecureStorage.Default.GetAsync(...).GetAwaiter().GetResult() 读取密码，而这个回调运行在 UI 线程，同步阻塞异步方法有卡顿甚至死锁的风险。更稳妥的做法是在 App 启动或设置页解锁时把 KeyStore 加载好，把私钥和证书链缓存在内存里，回调中直接使用；
知道 WebView 会记住你的选择：对同一个主机和端口，WebView 会缓存 Proceed 或 Ignore 的结果，后续请求不再触发回调。更换证书后要调用 WebView.ClearClientCertPreferences 清掉缓存，否则会出现“换了证书却不生效”的怪现象。

四、补上安全缺口：不要无条件信任服务端证书

源文为了支持自签的服务端证书，在 OnReceivedSslError 里直接写了 handler.Proceed()。这意味着：无论对面是谁、证书是什么，一律放行。

这和零信任恰好相反。mTLS 保证的是“服务器确认客户端是谁”，而客户端确认服务器是谁，靠的正是对服务端证书的校验。一旦无条件放行，任何能劫持网络的人（公共 Wi-Fi、被篡改的 DNS）都可以拿一张自签证书冒充你的面板。客户端证书的私钥不会泄露，冒充者也无法用它去连接真正的网关；但 WebView 里的一切都会交给冒充者——你输入的登录密码、面板的 Token、页面上的操作，全部暴露。Google Play 也会把无条件调用 proceed() 的 onReceivedSslError 实现视为不安全的写法。

既然服务端证书是自己签的，最直接的修复是证书指纹固定：把服务端证书的 SHA-256 指纹写进 App，只有指纹一致才放行。

public override void OnReceivedSslError(global::Android.Webkit.WebView view,
    SslErrorHandler handler, Android.Net.Http.SslError error)
{
    // SslCertificate.X509Certificate 需要 Android 10（API 29）及以上
    var cert = error.Certificate?.X509Certificate;
    if (cert != null)
    {
        var digest = Java.Security.MessageDigest.GetInstance("SHA-256")!.Digest(cert.GetEncoded()!);
        if (string.Equals(Convert.ToHexString(digest), PinnedSha256, StringComparison.OrdinalIgnoreCase))
        {
            handler.Proceed();
            return;
        }
    }
    handler.Cancel();
}

服务端证书的指纹可以用 OpenSSL 取得，去掉冒号后填入 PinnedSha256：

openssl x509 -in server.crt -noout -fingerprint -sha256

需要注意，这个回调只在服务端证书未通过系统校验时才触发。如果你给面板换成了公网 CA 签发的证书，系统校验会直接通过，指纹比对也就不会执行。这种情况下浏览器本身的校验已经足够，不需要再额外处理。

更换服务端证书时，要同步发布新版 App 更新指纹。也可以在 App 里同时保存新旧两个指纹作为过渡。

五、治理白屏：SPA 面板需要的几个开关

不少管理面板是 Vue 或 React 写的单页应用（SPA）。Android WebView 默认关闭了一些能力，加载 HTML 后可能直接白屏。源文在 MauiProgram.cs 中通过 Mapper 统一配置：

Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("mTLS_Setup", (handler, view) =>
{
#if ANDROID
    handler.PlatformView.SetWebViewClient(new StealthClaw.Platforms.Android.MTlsWebViewClient());
    handler.PlatformView.SetWebChromeClient(new global::Android.Webkit.WebChromeClient());
    handler.PlatformView.Settings.JavaScriptEnabled = true;
    handler.PlatformView.Settings.DomStorageEnabled = true;
#if DEBUG
    global::Android.Webkit.WebView.SetWebContentsDebuggingEnabled(true);
#endif
#endif
});

DomStorageEnabled 打开 localStorage，SPA 的状态管理和登录态几乎都依赖它；WebChromeClient 负责弹窗、控制台消息等浏览器级能力。远程调试（通过电脑上的 Chrome chrome://inspect 排查前端报错）很方便，但建议像上面这样只在 Debug 构建中打开，正式包里关闭。

六、服务端这一侧：Nginx 的 mTLS 配置要点

客户端改好了，服务端配置也要和它对得上。Nginx 开启客户端证书校验的核心指令只有三条：

server {
    listen 443 ssl;
    ssl_certificate         /etc/nginx/certs/server.crt;
    ssl_certificate_key     /etc/nginx/certs/server.key;

    ssl_client_certificate  /etc/nginx/certs/ca.crt;
    ssl_verify_client       on;
    ssl_verify_depth        2;
}

ssl_client_certificate 指定签发客户端证书的 CA，ssl_verify_client on 强制校验。如果想让验证失败时返回友好的错误页而不是直接断开连接，可以改成 optional，再在 location 里判断 $ssl_client_verify 是否为 SUCCESS。给每台设备签发独立的客户端证书，丢失时配合 ssl_crl 吊销列表单独作废，而不必整体换 CA。

七、动手实验：在本机复现“冒充者”场景

配套脚本 practice/demo_mtls_pinning.py 用 OpenSSL 生成一套私有 CA、服务端证书、客户端证书（打包成带密码的 .pfx），以及一张冒充者自签的服务端证书；再用 Python 起两个本地 HTTPS 服务：一个是要求客户端证书的“真实网关”，另一个是只想骗取数据的“冒充者”。

客户端部分模拟套壳浏览器的行为：从 .pfx 中取出带私钥的条目和证书链（对应 C# 遍历 KeyStore 别名），然后分别以三种策略访问：

按私有 CA 校验服务端证书；
只比对服务端证书的 SHA-256 指纹（对应上一节的修复）；
无条件放行（对应源文的 handler.Proceed()）。

运行结果：

$ python3 demo_mtls_pinning.py
[0] 证书目录 /tmp/mtls_demo_46yy9j6p，PFX 解析出带私钥条目 CN=phone-01，证书链 2 张
[1] 不带客户端证书访问网关        → 失败：ConnectionResetError [Errno 104] Connection reset by peer
[2] 带证书 + 按私有 CA 校验服务端 → 成功：真实网关 OK, 客户端证书 CN=phone-01
[3] 带证书 + 指纹固定             → 成功：真实网关 OK, 客户端证书 CN=phone-01
[4] 无条件放行（Proceed）连冒充者 → 成功：冒充者 OK, 客户端证书 CN=无
    冒充者截获的 Authorization： ['Bearer demo-session-token']
[5] 指纹固定连冒充者              → 拒绝：服务端证书指纹 c9193bbb011368dc… 与固定值不符，未发送任何数据
全部校验通过：mTLS 挡住了无证书客户端，指纹固定挡住了冒充的服务端

第 1 步失败的具体报错与 TLS 1.3 的握手时序有关，可能是证书缺失告警，也可能是连接被重置，两者都说明网关拒绝了没有证书的客户端。第 4 步最值得看：冒充者根本不需要你的客户端证书，只要你的 App 无条件放行，请求里的会话令牌就原样送到了它手上。第 5 步换成指纹固定后，客户端在发送任何数据之前就断开了连接。