Android 11中WiFiEnterpriseConfig如何添加根CA证书实现EAP分流

算力阿峰

2026-8-26

问题原因

Android 11（API 级别 30）起，系统框架对所有基于TLS的EAP企业级WiFi网络建议（EAP-TLS、EAP-TTLS、EAP-PEAP）强制启用安全校验，未同时配置根CA证书、RADIUS服务器域名匹配规则的配置，在调用addNetworkSuggestions提交时会直接返回STATUS_NETWORK_SUGGESTIONS_ERROR_ADD_NOT_ALLOWED错误，该限制无公开绕过方式，必须按系统要求构建合规配置。

实现步骤

前置准备：将RADIUS服务器使用的根CA证书文件放置到应用res/raw目录下，不要使用系统用户凭据池中的第三方CA证书，不要使用自生成的空证书/信任所有证书的配置。
构建合规配置：核心是补全两个强制校验字段，以下是可直接复用的实现代码（以EAP-PEAP认证为例）：

import android.net.wifi.WifiEnterpriseConfig
import android.net.wifi.WifiManager
import android.net.wifi.WifiNetworkSuggestion
import java.security.cert.CertificateFactory
import java.security.cert.X509Certificate

// 加载本地存储的根CA证书
val certFactory = CertificateFactory.getInstance("X.509")
val rootCaCert: X509Certificate = resources.openRawResource(R.raw.radius_root_ca).use { inputStream ->
    certFactory.generateCertificate(inputStream) as X509Certificate
}

// 配置EAP认证参数
val enterpriseConfig = WifiEnterpriseConfig().apply {
    // 按实际认证类型选择EAP方法：EAP.TLS / EAP.TTLS / EAP.PEAP
    eapMethod = WifiEnterpriseConfig.EAP.PEAP
    // 按实际阶段2认证方式配置：MSCHAPV2 / GTC等
    phase2Method = WifiEnterpriseConfig.Phase2.MSCHAPV2
    identity = "your_auth_account"
    password = "your_auth_password"

    // 强制必填项1：传入根CA证书
    caCertificate = rootCaCert
    // 强制必填项2：传入RADIUS服务器域名，需和服务器证书的SAN（主题备用名称）字段完全一致
    altSubjectMatch = "radius.your-service-domain.com"
}

// 构建WiFi网络建议
val eapWifiSuggestion = WifiNetworkSuggestion.Builder()
    .setSsid("YOUR_EAP_WIFI_SSID")
    .setWpa2Enterprise() // WPA3网络替换为setWpa3Enterprise()
    .setWifiEnterpriseConfig(enterpriseConfig)
    .build()

// 提交配置
val wifiManager = getSystemService(WifiManager::class.java)
val submitResult = wifiManager.addNetworkSuggestions(listOf(eapWifiSuggestion))
// submitResult为STATUS_NETWORK_SUGGESTIONS_SUCCESS即提交成功

常见踩坑说明

禁止调用setHasCaCertificate(false)尝试跳过证书校验，该配置在Android 11及以上版本的EAP-TLS类场景下会被直接拦截
服务器域名参数不要使用已废弃的setDomainSuffixMatch接口，必须使用altSubjectMatch配置精确匹配RADIUS服务器证书的SAN值，否则即使配置提交成功，实际连接时也会因证书校验失败无法联网
EAP-TLS认证场景除上述两个必填项外，还需通过setClientKeyEntry传入客户端认证私钥和客户端证书，否则同样会触发提交错误
配置提交成功后，基于该网络的分流逻辑和普通WiFi网络建议完全一致，可直接通过ConnectivityManager的网络请求API配置业务路由规则即可。

内容的提问来源于stack exchange，提问作者Amol Desai