remoteValidation 一设上,系统证书校验就下线了:API 26 自定义校验回调的四个默认值缺口与一份可落地的复刻清单
remoteValidation 一设上,系统证书校验就下线了:API 26 自定义校验回调的四个默认值缺口与一份可落地的复刻清单
前言
证书锁定(Certificate Pinning)、自建 CA、私有协议双向认证,这三类需求在 To B 的鸿蒙应用里几乎是标配。过去做这些事只有两条路:一条是把 CA 塞进 caPath,另一条是用 certificatePinning(API 12 起)钉公钥指纹。两条路都有个共同的别扭之处——它们都是"在系统校验之上做加法",你没法控制链构建过程,也没法在「证书链过了但吊销状态未知」这种边界状态上做业务决策。
API 26 给了第三条路:HttpRequestOptions.remoteValidation 可以接收一个 ValidationCallback,把服务端身份校验整个交给应用。这条路很强大,也很危险——它不是"多校验一次",而是"从此以后只剩你校验"。官方文档在 RemoteValidation 类型说明里写得很清楚:'system' 表示使用系统 CA 验证远端服务器身份,是未配置时的默认值;'skip' 表示跳过验证;而 ValidationCallback 则是"使用自定义验证方式验证远端服务器身份"。三个取值是三选一的枚举关系,不是叠加关系。
线上最常见的翻车姿势是这样的:为了支持一张内网自签证书,开发者在请求里挂了回调,回调里 return true 图省事;或者认真写了校验,但 catch 到异常后为了"不让业务挂掉"也 return true。前者等于把所有 HTTPS 请求降级成 HTTP 明文,后者等于只在证书"看起来正常"时才校验。这类问题在测试环境完全看不出来,因为测试环境本来就是对的证书。
本文不复述"要小心"这种废话,而是把 remoteValidation 接管之后,从"系统校验"切到"自己校验"必然踩到的四个默认值缺口逐个拆开,给出可直接粘贴运行的 ArkTS 实现,以及一张把错误码映射到业务动作的对照表。
问题描述
一个典型的接入片段:
import { http } from '@kit.NetworkKit';
import { cert } from '@kit.DeviceCertificateKit';
// 需求:只信任公司自建 CA 签发的服务端证书
const req = http.createHttp();
req.request('https://api.corp.example.com/v1/orders', {
method: http.RequestMethod.GET,
remoteValidation: (context: http.ValidationContext) => {
// 看起来"校验了证书链"——实际上这里把信任锚换成了自建根证书,
// 但主机名没校验、吊销没查、有效期以外的约束全丢了
return context.x509Certs.length >= 2;
}
} as http.HttpRequestOptions);
这段代码能跑通,请求能成功,日志也很干净。但只要做三个实验就会发现问题:
- 用
openssl生成一张域名不匹配的证书(SAN 写evil.example.com),换到测试域名上——请求照样成功。因为回调里根本没有"主机名"这个概念。 - 用一张已过期的证书——照样成功。回调只看证书个数。
- 更隐蔽的一种:证书链里只有终端证书、缺中间证书——
x509Certs.length变成 1,代码返回false,请求失败。开发者以为是"校验太严",于是把条件改成>= 1,结果把所有链不完整的请求都放行了。
第三个实验揭示了这套 API 的真正难点:ValidationContext 给你的是一堆原材料(PEM 原文、X509 对象、目标 host、实际连接 IP),不是结论。链构建、信任锚比对、有效期、SAN/CN 匹配、吊销查询,这五件事全部要你自己做,而且系统只告诉你"回调返回了什么",不会告诉你"你漏了什么"。
另一个高频误解是版本。remoteValidation 字段本身是 API 18 起就有的(元服务也是 18 起),但它的回调形态 ValidationCallback 是 26.0.0 起才支持的,ValidationContext、ValidationCallback、X509Cert 这几个类型以及整条 cert.CertValidationParams / validateCert 复刻链路,官方标注的起始版本同样是 26.0.0,并且限定 Stage 模型。所以在 API 18~25 的设备上,你能写的只有 'system' 和 'skip'——这一点如果没在需求评审时对齐,兼容性方案会整个返工。
细节解析
缺口一:信任锚——trustSystemCa 默认是 false
复刻链路的入口是:
validateCert(cert: X509Cert, params: CertValidationParams): Promise<CertValidationResult>
CertValidationParams 里与信任锚相关的两个字段,默认值组合起来非常容易出事:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
trustedCerts | Array<X509Cert> | 无 | 信任的根证书或中间 CA,最大 100 条 |
trustSystemCa | boolean | false | true 时使用系统预置 CA 库作为信任锚 |
untrustedCerts | Array<X509Cert> | 无 | 仅用于构建链的中间证书,不作为信任锚,最大 100 条 |
官方原文:「验证时,证书链须追溯至信任证书,必须设置此参数或将 trustSystemCa 设为 true」。也就是说,两个都不给,校验一定失败。这段文字很短,但它同时点了两个坑:
- 坑 A:
trustSystemCa默认关闭。从内置链路切到自定义回调的人,潜意识里以为"系统 CA 还在",其实没有。 - 坑 B:中间证书放错桶。中间证书必须进
untrustedCerts,如果塞进trustedCerts,它会变成信任锚——于是任何用这张中间 CA 签发的证书都能通过校验,包括攻击者自己签的。这在渗透测试里是被直接判定为高危的。
还有一个 partialChain,默认 false。含义是"构建证书链时必须追溯到根证书"。把它改成 true,则"允许使用信任证书中的任意证书作为信任锚"。很多教程为了让自签证书一次跑通就开了它,代价是把信任边界从"根"缩到"链上任何一张"。如果你只是想让内网自签根证书生效,正确做法是把根证书放进 trustedCerts,而不是开 partialChain。
缺口二:链构建——allowDownloadIntermediateCa 默认 false
真实世界的证书链经常不完整:服务端下发的只有终端证书,中间证书要客户端自己用 AIA 扩展去补。内置链路会帮你补,复刻链路不会——allowDownloadIntermediateCa 默认 false,打开后才会"尝试使用证书 AIA 扩展中颁发者地址下载颁发者证书",且下载地址仅支持 HTTP、必须申请 ohos.permission.INTERNET。
这就是"本地测试全绿、外网灰度大面积 19030005(无法获取证书的颁发者)"的典型成因。
官方把链构建规则写成了四步,这段值得逐字读:
- 可信锚点源:始终用
trustedCerts作为信任锚点源,仅当trustSystemCa为true时预置证书才被用作信任锚源; - 颁发者搜索顺序:先在信任锚源里搜颁发者,找不到才去
untrustedCerts里搜;在线下载的中间 CA 也算untrustedCerts; - 信任锚锁定:一旦在信任锚源里找到了颁发者,后续查找不会回溯到
untrustedCerts; - 构建完成条件:
partialChain为false(默认)时必须找到根证书;为true时首次在信任锚源中找到颁发者即完成。
第 3 条是很有信息量的:它说明链构建是有方向的贪心,一旦锚定就不回头。所以如果证书链里同一个 subject 存在两张不同的中间证书(轮换期很常见),你给的 untrustedCerts 顺序会直接影响结果。
缺口三:主机名——hostnames 不传,等于不校验
这一条是四道缺口里最致命的。CertValidationParams.hostnames 的说明是:
验证证书的主体备用名(SAN)或通用名(CN)是否包含指定的主机名。最大数量:100,每个主机名最大长度:128。用于 HTTPS 等场景。只要匹配其中一个主机名即校验成功。
关键在"可选"二字。不传 hostnames,这套校验里就不存在主机名验证环节——链是对的、日期是有效的,一张 *.attacker.com 的合法证书配上 api.corp.example.com 的请求,也能过。必须显式传:
hostnames: [context.host] // 不是 context.ip
ValidationContext 同时给了 host(本次请求的目标主机名)和 ip(实际连接的 IP)。传 ip 是错的:hostnames 比对的是 SAN 的 dNSName 条目和 CN,IP 是要看 SAN 的 iPAddress 条目,两者不通用。用 ip 填 hostnames,正常证书反而会稳定报 19030012。
顺带说下 emailAddresses 和 keyUsage:前者最大 1 条,后者最大 9 条且必须全部包含才通过(与 hostnames 的"任一匹配"语义相反,这一点极易记反)。
缺口四:吊销——revokedParams 不传,整个吊销检查不存在
官方对 revokedParams(X509CertRevokedParams)的定义是"证书吊销检查参数,用于检查证书是否被吊销"。它整体可选,不传就完全不做吊销检查。传了之后还要注意 revocationFlags 是必填项,数量范围 [1, 4],且必须包含 CERT_REVOCATION_CRL_CHECK 或 CERT_REVOCATION_OCSP_CHECK 之一,否则没有任何检查手段。
CertRevocationFlag 四个值,语义细节比名字复杂得多:
| 枚举 | 值 | 官方语义要点 |
|---|---|---|
CERT_REVOCATION_PREFER_OCSP | 0 | 仅在同时设置 CRL_CHECK 与 OCSP_CHECK 时生效;设置后先 OCSP、失败回退 CRL;不设置则先 CRL、失败回退 OCSP |
CERT_REVOCATION_CRL_CHECK | 1 | 先用 crls 参数匹配,未匹配且 allowDownloadCrl 为 true 才走 CDP 下载 |
CERT_REVOCATION_OCSP_CHECK | 2 | 先用 ocspResponses 匹配,未匹配且 allowOcspCheckOnline 为 true 才走 AIA 在线查询 |
CERT_REVOCATION_CHECK_ALL_CERT | 3 | 对链上所有证书做吊销检查(跳过自签名证书);不设置则只检查链上第一张,即终端证书 |
这里藏着两个非常容易漏的点。
第一,allowDownloadCrl 和 allowOcspCheckOnline 默认都是 false。只写 revocationFlags 不写这两个开关,效果是"只在我预置的 CRL/OCSP 数据里查",一旦没预置就直接报 19030015(无法获取证书吊销列表)或 19030020(无法获取 OCSP 响应)。这也是为什么很多人"明明开了吊销检查,却从来没真正联网查过"。
第二,CHECK_ALL_CERT 默认不开,意味着默认只查终端证书。中间 CA 被吊销、但终端证书还在有效期内的情况,默认策略漏判。而 CRL 与 OCSP 的语义又不一样:官方明确 OCSP 响应"始终使用系统当前时间校验有效期,并允许前后 5 分钟的时间容差",“允许 ocsp 响应缺少 nonce 和 nextUpdate”——这些宽容处理只对 OCSP 生效,CRL 侧对应的是 19030016(尚未生效)/19030017(已过期)两个硬错误。
还有一条国密专属的坑:userId 用于 SM2 验签,设置 userId 后不支持证书吊销检查。国密双证书场景要么放弃吊销检查,要么自己在外层用 CRL 单独做。
缺口五(附加):validateDate 与两个名字很像的参数类型
validateDate 默认 true,会同时校验证书和 CRL 的有效期;date 字段格式是 YYMMDDHHMMSSZ 或 YYYYMMDDHHMMSSZ,默认取当前系统时间。这两个不要动,除非你在做历史签名离线验证。
真正要小心的是类型名撞车:
cert.CertValidationParams——validateCert的参数,26.0.0 起;cert.CertChainValidationParameters—— 是buildCertChain的CertChainBuildParameters.validationParameters字段类型,12 起就有。
论坛里很多"参数不生效"的案例,是把后者当成了前者传进 validateCert,编译期一过就变成运行期静默忽略。
错误码到业务动作的映射
validateCert 抛出的错误码集中在 1903xxxx 段,官方文档里 24 个码的分工非常清楚。生产代码里至少要按这张表分流:
| 错误码 | 含义 | 正确处理 |
|---|---|---|
19030003 | 证书尚未生效 | 拒绝,通常是设备时间被改 |
19030004 | 证书过期 | 拒绝,同时上报服务端证书轮换 |
19030005 | 无法获取证书的颁发者 | 拒绝;若确认服务端链不完整,开 allowDownloadIntermediateCa 并补 INTERNET 权限 |
19030009 | 证书不受信任 | 拒绝;检查 trustedCerts / trustSystemCa 是否漏配 |
19030010 | 证书已被吊销 | 拒绝,且应作为安全事件上报 |
19030011 | 未知的关键扩展 | 可按 X.509 规范用 ignoreErrs 忽略(ignoreErrs 最多 8 条) |
19030012 | 主机名不匹配 | 拒绝;检查是否错误地传了 context.ip |
19030015 / 19030017 | 无法获取 CRL / CRL 已过期 | 不要用 ignoreErrs 吞掉,这等于关掉吊销检查 |
19030020 / 19030024 | 无法获取 OCSP 响应 / 网络超时 | 拒绝并重试一次;仍失败则按可配置策略降级到 CRL,但绝不"降级到放行" |
ignoreErrs 的可忽略集合是官方枚举好的:ERR_CERT_NOT_YET_VALID、ERR_CERT_HAS_EXPIRED、ERR_UNKNOWN_CRITICAL_EXTENSION、ERR_CRL_NOT_FOUND、ERR_CRL_NOT_YET_VALID、ERR_CRL_HAS_EXPIRED、ERR_OCSP_RESPONSE_NOT_FOUND、ERR_NETWORK_TIMEOUT。注意这份清单里没有 ERR_CERT_HAS_BEEN_REVOKED,也没有主机名不匹配——所以"吊销"和"主机名"这两类错误在设计上就不允许被忽略,这是官方用 API 形状强制的一件事。
示例代码
1. 反例:三种看起来"有校验"的写法
import { http } from '@kit.NetworkKit';
// 反例一:无条件放行(等于全局降级成明文)
const bad1: http.ValidationCallback = () => true;
// 反例二:只数证书个数(不校验主机名/有效期/吊销)
const bad2: http.ValidationCallback = (ctx: http.ValidationContext) => ctx.x509Certs.length > 0;
// 反例三:校验失败也放行(最常见,危害最大)
const bad3: http.ValidationCallback = async (ctx: http.ValidationContext) => {
try {
return await doSomething(ctx);
} catch (e) {
return true; // ← 错误在这一行:失败即放行,攻击面 100%
}
};
2. 完整实现:把系统校验的四件事补齐
import { cert } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN = 0x0001;
const TAG = 'RemoteValidation';
/** 自定义校验失败时抛出,携带原始证书错误码,供上层分流 */
export class CertValidateError extends Error {
code: number;
constructor(code: number, msg: string) {
super(msg);
this.code = code;
}
}
/**
* 复刻系统 CA 校验:信任锚 + 链构建 + 有效期 + 主机名 + 吊销。
* 任何一个环节失败都抛错,绝不返回 true。
*/
export async function validateRemoteServer(ctx: http.ValidationContext): Promise<boolean> {
if (!ctx.x509Certs || ctx.x509Certs.length === 0) {
throw new CertValidateError(-1, 'empty x509Certs');
}
// 顺序约定:第一个是终端实体证书,其余为中间证书(官方示例同此约定)
const endEntity: cert.X509Cert = ctx.x509Certs[0];
const intermediates: cert.X509Cert[] = ctx.x509Certs.slice(1);
const params: cert.CertValidationParams = {
// 缺口一:信任锚。用系统 CA 作为根,内网场景换成 trustedCerts: [corpRootCa]
trustSystemCa: true,
// 缺口二:中间证书只能放这里,放 trustedCerts 会被当成锚点
untrustedCerts: intermediates,
// 缺口二补:服务端链不完整时允许按 AIA 下载(需 INTERNET 权限)
allowDownloadIntermediateCa: true,
// 缺口三:不传等于不校验;必须用 host,不能用 ip
hostnames: [ctx.host],
// 有效期校验,保持默认开
validateDate: true,
// 缺口四:吊销检查必须显式构造 flags
revokedParams: {
revocationFlags: [
cert.CertRevocationFlag.CERT_REVOCATION_CRL_CHECK,
cert.CertRevocationFlag.CERT_REVOCATION_OCSP_CHECK,
cert.CertRevocationFlag.CERT_REVOCATION_PREFER_OCSP,
cert.CertRevocationFlag.CERT_REVOCATION_CHECK_ALL_CERT
],
allowDownloadCrl: true, // 默认 false,不打开就只查预置 CRL
allowOcspCheckOnline: true, // 默认 false,不打开就只查预置 OCSP 响应
ocspDigest: cert.OcspDigest.SHA256 // 默认即 SHA256,显式写出便于审计
}
};
try {
const validator = cert.createCertChainValidator('PKIX');
const result = await validator.validateCert(endEntity, params);
hilog.info(DOMAIN, TAG, 'cert ok, chainLength=%{public}d', result.certChain.length);
return true;
} catch (err) {
const e = err as BusinessError;
hilog.error(DOMAIN, TAG, 'cert fail code=%{public}d msg=%{public}s', e.code, e.message);
throw new CertValidateError(e.code, e.message);
}
}
3. 挂到 HTTP 请求上,并按错误码分流
import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
const REVOKED = 19030010;
const EXPIRED = 19030004;
const HOSTNAME_MISMATCH = 19030012;
const UNTRUSTED = 19030009;
export async function requestOrder(): Promise<string> {
const req = http.createHttp();
const options: http.HttpRequestOptions = {
method: http.RequestMethod.GET,
connectTimeout: 10000,
readTimeout: 15000,
remoteValidation: validateRemoteServer // 直接传函数,支持返回 Promise<boolean>
};
try {
const resp = await req.request('https://api.corp.example.com/v1/orders', options);
return resp.result as string;
} catch (err) {
const e = err as BusinessError;
// 注意:回调里抛出的错误会被网络栈转换,这里按 msg 里的证书码再兜一层
if (e.message.includes(String(REVOKED)) || e.message.includes(String(EXPIRED))
|| e.message.includes(String(HOSTNAME_MISMATCH)) || e.message.includes(String(UNTRUSTED))) {
hilog.error(0x0001, 'Net', 'server identity rejected, code=%{public}s', e.message);
throw new Error('SERVER_IDENTITY_REJECTED'); // 业务层不得重试、不得降级到 HTTP
}
throw e;
} finally {
req.destroy();
}
}
这里有个实践层面的细节值得强调:ValidationCallback 声明为 (context) => boolean | Promise<boolean>,官方注明"支持同步或异步返回验证结果"。但只要你在回调里 throw,网络栈拿到的就不是"false"而是异常路径,错误码可能被包一层。所以在回调内部先记录一次带原始证书码的 hilog,再决定抛错还是返回 false,是更稳的写法——这样无论上层怎么包装,日志里永远留着 1903xxxx。
4. 自测矩阵:把这四道缺口逐个证伪
// 用不同靶点验证"缺口"是否真的补上了。每一条都应该失败。
const CASES: Array<[string, string]> = [
['https://self-signed.badssl.com', '自签证书 → 期望 19030009'],
['https://expired.badssl.com', '过期证书 → 期望 19030004'],
['https://wrong.host.badssl.com', '主机名不匹配 → 期望 19030012(若不配 hostnames 则误通过)'],
['https://incomplete-chain.badssl.com', '链不完整 → 期望 19030005(开 allowDownloadIntermediateCa 后应通过)'],
['https://revoked.badssl.com', '已吊销 → 期望 19030010(只置 CRL_CHECK 时应命中)']
];
export async function runSelfTest(): Promise<void> {
for (const [url, expect] of CASES) {
const req = http.createHttp();
try {
await req.request(url, { method: http.RequestMethod.GET, remoteValidation: validateRemoteServer });
hilog.warn(0x0001, 'SelfTest', 'UNEXPECTED PASS %{public}s (%{public}s)', url, expect);
} catch (e) {
hilog.info(0x0001, 'SelfTest', 'expected fail %{public}s -> %{public}s', url, (e as BusinessError).message);
} finally {
req.destroy();
}
}
}
这套矩阵的价值在于可证伪:若 wrong.host.badssl.com 通过了,说明 hostnames 没生效;若 revoked.badssl.com 通过了,说明 revocationFlags 或两个 allow* 开关有问题。每一条"意外通过"都是一个真实漏洞,比任何 code review 都直观。
总结
remoteValidation 的正确心智模型不是"加一层自定义校验",而是"把身份校验的全部责任转交给应用"。理解这一点之后,四条必检项就是一个固定清单:
| 检查项 | 复刻时必须显式做的事 | 默认值陷阱 |
|---|---|---|
| 信任锚 | trustSystemCa: true 或 trustedCerts: [根证书] | trustSystemCa 默认 false |
| 链构建 | 中间证书进 untrustedCerts;必要时开 allowDownloadIntermediateCa | partialChain 默认 false;下载需 INTERNET 权限且仅 HTTP |
| 主机名 | hostnames: [ctx.host] | 不传完全不校验;不能用 ctx.ip |
| 有效期 | validateDate: true | 默认就是 true,别关 |
| 吊销 | revokedParams.revocationFlags 含 CRL/OCSP;开 CHECK_ALL_CERT;开两个 allow* | 不传 revokedParams 则吊销检查为空;allow* 均默认 false |
| 失败处理 | 一律拒绝,仅对明确可忽略项用 ignoreErrs | ignoreErrs 最多 8 条,且不含"已吊销"/“主机名不匹配” |
最后三条工程纪律,比代码本身更重要:
- 回调里禁止出现
return true的兜底分支。要兜底就兜到"拒绝 + 上报",不要兜到"放行"。 - 不要用
'skip'做灰度开关。'skip'是文档明确提供的"跳过验证"取值,一旦被塞进配置中心,就是一颗随时会炸的定时炸弹;真要灰度,用"切换信任锚列表"而不是"切换是否校验"。 - 版本兼容要按 26.0.0 划线。API 18~25 上只有
'system'/'skip',想在老设备上做锁定,请继续用 API 12 起就有的certificatePinning,它能覆盖公钥指纹钉扎这个最常见的诉求,只是拿不到吊销和自定义链的决策能力。
如果你的诉求只是"信任一张自建 CA",其实不需要 remoteValidation:把根证书通过 caPath 或信任配置下发,让系统链路带着完整策略去校验,比你自己拼一套更安全。只有当业务真的需要在"吊销状态未知"“链不完整”"证书轮换期"这些边上做业务决策时,才值得接管——接管的前提,是先把上面这张表补齐。
更多推荐

所有评论(0)