jose 非对称密钥对生成结果详解：GenerateKeyPairResult 接口与 generateKeyPair 实战指南-平芜编程栈

网络安全
认证鉴权
后端

【免费下载链接】jose

JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes

项目地址：https://gitcode.com/gh_mirrors/jo/jose

本指南围绕 jose 库中generateKeyPair函数的返回结果接口GenerateKeyPairResult展开，完整讲解该接口的privateKey与publicKey两个属性、配套的GenerateKeyPairOptions配置参数，并结合仓库源码与测试用例说明密钥对生成背后的算法选择、曲线解析与安全默认值。读完本文，你将掌握在 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等 Web 互操作运行时中生成并使用 RSA、EC、OKP、ML-DSA、ECDH-ES 等非对称密钥对的完整方法。

接口定义与核心作用

GenerateKeyPairResult是 jose 库中非对称密钥对生成函数generateKeyPair()的返回值类型，定义位于 src/key/generate_key_pair.ts，其结构如下：

属性	类型	说明
`privateKey`	`CryptoKey`	生成的私钥（Private Key）
`publicKey`	`CryptoKey`	与私钥对应的公钥（Public Key）

接口官方文档见 GenerateKeyPairResult 接口文档。从接口语义可以明确两个关键事实：

返回值永远是成对出现的：publicKey与privateKey一一对应，公钥可用于加密与验签并对外分发，私钥必须保密保存；
两者均为 Web Crypto 标准对象：类型是CryptoKey而非字符串或 PEM 文本。若需要以 JWK、PKCS#8、SPKI 等格式导出，需通过exportJWK、exportPKCS8、exportSPKI等配套函数完成（见导出相关文档）。

generateKeyPair：生成密钥对的核心函数

generateKeyPair是唯一会返回GenerateKeyPairResult的函数，官方文档见 generateKeyPair 函数文档，签名如下：

generateKeyPair(alg: string, options?: GenerateKeyPairOptions): Promise<GenerateKeyPairResult>

参数说明

参数	类型	说明
`alg`	`string`	要使用的 JWA 算法标识符，见下方支持列表
`options?`	`GenerateKeyPairOptions`	传递给底层密钥生成的附加选项

该函数只能生成非对称密钥对；对称密钥（如 HS256 的共享密钥）应改用generateSecret函数（见 generateSecret 文档）。它同时从'jose'主入口和'jose/key/generate/keypair'子路径导出。

支持的 JWA 算法标识符

从 src/key/generate_key_pair.ts 的类型定义可以看出，generateKeyPair可生成的算法覆盖三大类：

RSA 系列：PS256、PS384、PS512（RSASSA-PSS）、RS256、RS384、RS512（RSASSA-PKCS1-v1_5）、RSA-OAEP、RSA-OAEP-256、RSA-OAEP-384、RSA-OAEP-512（RSA-OAEP 加密）；
EC 系列：ES256、ES384、ES512，以及密钥协商类ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW、ECDH-ES+A256KW；
OKP / 后量子签名：Ed25519、EdDSA，以及仓库已纳入的 ML-DSA 后量子算法ML-DSA-44、ML-DSA-65、ML-DSA-87。

底层实现（src/key/generate_key_pair.ts）通过keyAlgorithm从 JWS/JWE 算法注册表解析标识符（见 src/lib/key_algorithm.ts），并在算法属于对称密钥（entry.secret为真）时直接抛出ERR_JOSE_NOT_SUPPORTED异常，确保该函数只处理非对称场景。

GenerateKeyPairOptions：三个可调参数

GenerateKeyPairOptions接口定义了三个可选参数，官方文档见 GenerateKeyPairOptions 接口文档，源码实现位于 src/key/generate_key_pair.ts。

crv：显式指定曲线

EC 算法的crv（Curve）与 OKP 算法的crv（Key Pair 子类型）。曲线必须同时满足两个条件：运行时支持，且适用于给定的 JWA 算法标识符。

// 为 ES256 显式指定 P-256 曲线 const { publicKey, privateKey } = await jose.generateKeyPair('ES256', { crv: 'P-256', })

从源码看，crv的校验逻辑分两种情况（src/key/generate_key_pair.ts）：

固定曲线的算法（如ES256→P-256、ES384→P-384、ES512→P-521、Ed25519/EdDSA→Ed25519）：若传入的crv与算法隐含曲线不一致，直接抛出JOSENotSupported，错误信息形如Invalid or unsupported crv option provided, the only supported value for ES256 is P-256；
不固定曲线的算法（ECDH-ES家族）：曲线完全由crv选项决定，合法值为P-256、P-384、P-521与X25519，缺省默认P-256，对应的 WebCrypto 生成参数分别为{ name: 'ECDH', namedCurve }与{ name: 'X25519' }。

测试 test/jwk/generate_key_pair.test.ts 覆盖了上述两类行为：冲突的crv会被拒绝，匹配的crv会被接受并体现在导出 JWK 的crv字段中，而ECDH-ES会自行解析crv选项。

modulusLength：RSA 密钥长度提示

仅对 RSA 算法生效，表示密钥长度（位）。JOSE 规范要求2048 位或更大，默认值为 2048。

const { publicKey, privateKey } = await jose.generateKeyPair('RS256', { modulusLength: 4096, })

校验逻辑位于 src/key/generate_key_pair.ts：modulusLength必须是大于等于 2048 的整数，否则抛出JOSENotSupported。注意 RSA 密钥生成固定使用publicExponent = 0x0100_0001（即 65537，业界标准安全公钥指数），该值由 src/key/generate_key_pair.ts 硬编码注入底层crypto.subtle.generateKey调用。

extractable：私钥是否可导出

对应 Web CryptoSubtleCrypto.generateKey的extractable参数，默认值为false。

const { publicKey, privateKey } = await jose.generateKeyPair('PS256', { extractable: true, }) console.log(await jose.exportJWK(privateKey)) console.log(await jose.exportPKCS8(privateKey))

这是 jose 刻意设计的安全默认值：私钥默认不可导出，防止未授权的代码把私钥材料泄露到应用之外。只有当你确实需要将私钥导出为 JWK 或 PKCS#8 格式（例如持久化存储、迁移到其他服务）时，才应显式开启extractable: true。该选项的类型校验在 src/lib/key_options.ts 中实现，非布尔值会抛出TypeError，且测试 test/jwk/generate_key_pair.test.ts 验证了选项只会被读取一次（防止 getter 副作用导致结果不一致）。

最小可用示例：从生成到导出

官方文档给出的最简用法如下（完整示例见 generateKeyPair 函数文档）：

const { publicKey, privateKey } = await jose.generateKeyPair('PS256') console.log(publicKey) console.log(privateKey)

结合导出函数即可构成完整的实战链路（导出函数文档见 key/export README）：

import * as jose from 'jose' // 1. 生成 ES256 密钥对 const { publicKey, privateKey } = await jose.generateKeyPair('ES256', { crv: 'P-256', extractable: true, // 需要导出私钥时开启 }) // 2. 导出 JWK 公钥用于分发 const publicJwk = await jose.exportJWK(publicKey) console.log(publicJwk) // { kty: 'EC', crv: 'P-256', x: '...', y: '...' } // 3. 导出 PKCS#8 私钥用于安全存储 const privatePem = await jose.exportPKCS8(privateKey) console.log(privatePem) // -----BEGIN PRIVATE KEY-----

若密钥对用于 JWE 加密场景，可直接将publicKey作为接收方公钥参与CompactEncrypt或FlattenedEncrypt的encrypt(publicKey)调用；用于 JWS 签名场景，则将privateKey传入new SignJWT(payload).sign(privateKey)。

关键行为与边界一览

结合 src/key/generate_key_pair.ts 的完整实现路径，可以归纳出以下确定的行为：

算法标识符必须是字符串：非字符串会抛出ERR_JOSE_NOT_SUPPORTED（Invalid or unsupported "alg" (Algorithm) value），见 test/jwk/generate_key_pair.test.ts；
对称算法被明确拒绝：如向本函数传入HS256，会因entry.secret为真而被unsupportedAlg拦截，避免误用；
密钥用途（usages）由算法决定：生成时会把该算法允许的公钥用途与私钥用途合并传入crypto.subtle.generateKey（src/key/generate_key_pair.ts），最终CryptoKey上的usages会限制其可用操作；
crv 选项对无曲线的算法保持惰性：对 RSA、ML-DSA 这类没有曲线的算法传入crv会被忽略而非报错，见 test/jwk/generate_key_pair.test.ts；
运行时支持决定最终成败：jose 只负责构造 WebCrypto 参数，最终是否支持取决于当前运行环境（Node.js 版本、浏览器、Worker 等）对对应算法/曲线的原生实现。