素性检测在密码学代码里出现的频率比多数人预想的要高：生成DH参数后验证对端传来的质数、检查RSA因子是否合规、在协议握手前确认某个大数不是精心构造的合数。crypto.checkPrimeSync()把这些需求收进了一个同步方法里，调用简单，但它背后的概率测试语义和同步阻塞代价，是选型时绕不开的两个点。下面从接口语义、参数实质、对照选型、安全边界几个角度把这件事讲清楚。

1.接口语义：它接受什么，返回什么

根据Node.js官方文档，crypto.checkPrimeSync(candidate[,options])接受一个candidate，类型可以是ArrayBuffer、SharedArrayBuffer、TypedArray、Buffer、DataView或bigint，编码为大端字节序的任意长度序列。返回值是布尔值：true表示候选数在给定的错误概率范围内是质数。

这里有一个容易被忽略的细节：传入的Buffer或ArrayBuffer不会被当作“数字的字符串表示”来解析，而是被当作大端字节序列直接解释为一个整数。如果传入一个16字节全零的ArrayBuffer，它代表的是整数0，不是质数，返回false。如果想检查十进制数13，需要传入Buffer.from([13])或直接传13n（bigint在Node.js中已被接受，内部会做转换）。

const crypto = require('crypto');

// 正确：用 bigint 传入小整数
console.log(crypto.checkPrimeSync(13n)); // true

// 正确：用 Buffer 传入大端字节序列
const buf = Buffer.from([0x7f, 0xff, 0xff, 0xff]); // 2147483647
console.log(crypto.checkPrimeSync(buf)); // true

// 容易误解：空 Buffer 代表 0
console.log(crypto.checkPrimeSync(Buffer.alloc(0))); // false

项目反思：曾有人把crypto.randomBytes(16)直接丢进去期望得到一个“随机质数检测结果”，这本身没有语法错误，但randomBytes产出的是随机字节序列，绝大多数情况下不是质数。素性检测和随机数生成是两件事，不能因为都出自crypto模块就混着用。

2.checks参数的真实含义：它不是“检查次数越多越安全”这么简单

options.checks指定Miller-Rabin概率测试的迭代次数。官方文档的表述是：当值为0（默认）时，使用一定数量的检查，使随机输入的误报率最多为2^-64；返回true时，候选数是质数的错误概率小于0.25**options.checks。

这里需要拆开理解两层含义。第一层，默认值0不等于“不检查”。在Node.js的底层实现中，checks=0会被转发给OpenSSL的BN_check_prime，OpenSSL根据候选数的位长从FIPS186-4附录C.3的表中选取合适的轮数，而不是跳过Miller-Rabin。所以Node.js环境下默认参数是可用的。

第二层，0.25**checks这个错误概率公式只在显式传入checks>=1时直接对应。当checks为默认0时，实际轮数由OpenSSL按位长决定，误报率控制在2^-64量级。理解这一点很重要：如果代码中因为“想更安全”而传了checks:1，那单轮Miller-Rabin的错误概率上界是0.25，反而可能比默认配置更宽松。个人建议：除非有明确的性能或安全需求需要调参，否则不要随手改动checks的默认值。

3.与相邻函数的职责对照：sync版、回调版与自建实现

crypto.checkPrime(candidate[,options],callback)是异步回调版本，参数和返回值语义与sync版一致，区别在于计算过程不阻塞主线程，结果通过回调返回。两者的选择标准很直接：如果在请求处理路径中检测一个位数较大的候选数，用sync版会卡住事件循环，影响同一进程内其他请求的响应；用回调版或util.promisify后的版本可以把计算交给线程池。

与自建素性检测函数对比，差异不在“能不能算对”，而在概率语义和位长适应性。一个简单的for(leti=5;i*i<=n;i+=6)试除法在小范围内准确且可控，但面对密码学量级的位长（比如2048位），试除法的时间成本不可接受。checkPrimeSync走的是Miller-Rabin概率路线，配合OpenSSL的优化实现，在密码学场景下是更合理的选择。但反过来，如果只是检测一个32位整数是否为质数，自建试除法反而更轻量、没有模块依赖，也不需要理解checks参数。

4.同步阻塞的代价：事件循环视角

checkPrimeSync的“Sync”后缀意味着它在当前线程同步执行，直到OpenSSL返回结果。候选数的位长越大，阻塞时间越长。在Web服务的请求处理函数中直接调用它，如果传入的是一个1024位或更长的候选数，这段时间内该Node.js进程无法处理其他任何请求。

const crypto = require('crypto');

// 不推荐：在请求处理路径中同步检测大数
function handleVerify(req, res) {
  const candidate = req.body.prime; // 可能是 2048 位
  const isPrime = crypto.checkPrimeSync(candidate); // 阻塞事件循环
  res.json({ valid: isPrime });
}

更稳妥的做法是在需要检测大数的场景中改用异步版crypto.checkPrime，或者在架构上把这类计算放到worker线程或独立服务中。项目反思：一个内部签名服务曾因为在一处中间件里调用了checkPrimeSync处理外部传入的候选质数，高峰期出现了接口响应时间明显拉长。排查时发现CPU并不高，问题在于事件循环被同步计算占住，后续请求排队。换成异步版后响应时间恢复平稳。这个教训说明：同步API的“简单”是有代价的，代价出现在并发场景里，而不是在单次调用的基准测试里。

5.跨运行时差异与安全边界（值得单独留意）

Node.js的checkPrimeSync底层依赖OpenSSL，默认checks=0时OpenSSL会替补合理的Miller-Rabin轮数。但其他实现了node:crypto兼容接口的运行时不一定有同样的行为。公开的安全公告记录了一个案例：某个兼容运行时在checks=0时直接跳过了Miller-Rabin循环，只做了对小质数的试除，导致两个大于17863的质数之积会被报告为质数。这个问题的根因不在Node.js本身，但它提醒了一件事：如果代码需要在多个运行时之间移植，不要假设checkPrimeSync的默认行为在所有环境中一致。在安全敏感的路径中，显式传入一个合理的checks值（比如根据位长对应FIPS表中的轮数，或保守地传64）是更可控的做法。

另一个边界是输入合法性。checkPrimeSync对candidate的类型有要求，传入不支持的类型的值会抛出TypeError。传入负数或0时返回false，不会报错。如果上游数据来源不可信，建议在调用前先做类型和范围校验，把错误处理放在业务层而不是依赖底层抛异常。

6.本节课程知识要点

• checkPrimeSync接受大端字节序列或bigint，返回布尔值，错误概率由checks和OpenSSL的位长策略共同决定。

• 默认checks=0在Node.js中走OpenSSL的位长替补逻辑，不是“零轮检查”；显式传小值可能反而放宽误报率。

• 同步调用会阻塞事件循环，大数检测应改用异步版checkPrime或worker线程。

• 跨运行时环境中，checks=0的替补行为可能不一致，安全敏感场景建议显式指定轮数。

• 小整数素性检测用自建试除法更轻量，密码学量级才需要Miller-Rabin概率测试。

7.练习与思考

思考题一：一个API端点接收外部传入的候选质数并同步调用checkPrimeSync做校验。请从事件循环阻塞和概率误报两个角度，写出至少两项改进措施。

思考题二：如果需要在浏览器端（WebCryptoAPI）完成类似的素性检测，现有Node.js的checkPrimeSync调用逻辑能否直接迁移？从API可用性和概率语义两个层面分析。

四、延伸阅读与参考文献

Node.js官方文档。crypto.checkPrimeSync(candidate[,options])。https://url.nodejs.cn/api/v26/crypto/crypto_checkprimesync_candidate_options.html。官方API说明，明确了candidate类型、checks默认值0的语义以及返回值的错误概率公式，是理解该方法行为的基础依据。

Node.js官方文档。crypto.checkPrime(candidate[,options],callback)。https://url.nodejs.cn/api/v26/crypto/crypto_checkprime_candidate_options_callback.html。异步版本的参数与语义说明，用于对照同步与异步在职责上的分工。

OSV安全公告。GHSA-9xg4-qhm4-g43w：Miller-RabinPrimalityTestAllowsZeroRounds。https://osv.dev/vulnerability/GHSA-9xg4-qhm4-g43w。记录了一个兼容运行时在checks=0时跳过Miller-Rabin的问题，以及Node.js通过OpenSSL替补轮数避免该问题的机制，对理解跨运行时差异有参考价值。

DenoPR#34391讨论记录。fix(ext/node):enforceminimumMiller-RabinroundsincheckPrime。https://app.semanticdiff.com/gh/denoland/deno/pull/34391/overview。展示了FIPS186-4附录C.3轮数表在修复中的使用方式，以及checks=0在不同实现中语义分叉的具体案例。