jose 非对称密钥对生成结果详解：GenerateKeyPairResult 接口与 generateKeyPair 实战指南

网络安全认证鉴权后端【免费下载链接】joseJWA, 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其结构如下属性类型说明privateKeyCryptoKey生成的私钥Private KeypublicKeyCryptoKey与私钥对应的公钥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): PromiseGenerateKeyPairResult参数说明参数类型说明algstring要使用的 JWA 算法标识符见下方支持列表options?GenerateKeyPairOptions传递给底层密钥生成的附加选项该函数只能生成非对称密钥对对称密钥如 HS256 的共享密钥应改用generateSecret函数见 generateSecret 文档。它同时从jose主入口和jose/key/generate/keypair子路径导出。支持的 JWA 算法标识符从 src/key/generate_key_pair.ts 的类型定义可以看出generateKeyPair可生成的算法覆盖三大类RSA 系列PS256、PS384、PS512RSASSA-PSS、RS256、RS384、RS512RSASSA-PKCS1-v1_5、RSA-OAEP、RSA-OAEP-256、RSA-OAEP-384、RSA-OAEP-512RSA-OAEP 加密EC 系列ES256、ES384、ES512以及密钥协商类ECDH-ES、ECDH-ESA128KW、ECDH-ESA192KW、ECDH-ESA256KWOKP / 后量子签名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 算法的crvCurve与 OKP 算法的crvKey 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选项。modulusLengthRSA 密钥长度提示仅对 RSA 算法生效表示密钥长度位。JOSE 规范要求2048 位或更大默认值为 2048。const { publicKey, privateKey } await jose.generateKeyPair(RS256, { modulusLength: 4096, })校验逻辑位于 src/key/generate_key_pair.tsmodulusLength必须是大于等于 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 READMEimport * 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_SUPPORTEDInvalid or unsupported alg (Algorithm) value见 test/jwk/generate_key_pair.test.ts对称算法被明确拒绝如向本函数传入HS256会因entry.secret为真而被unsupportedAlg拦截避免误用密钥用途usages由算法决定生成时会把该算法允许的公钥用途与私钥用途合并传入crypto.subtle.generateKeysrc/key/generate_key_pair.ts最终CryptoKey上的usages会限制其可用操作crv 选项对无曲线的算法保持惰性对 RSA、ML-DSA 这类没有曲线的算法传入crv会被忽略而非报错见 test/jwk/generate_key_pair.test.ts运行时支持决定最终成败jose 只负责构造 WebCrypto 参数最终是否支持取决于当前运行环境Node.js 版本、浏览器、Worker 等对对应算法/曲线的原生实现。相关资源GenerateKeyPairResult 接口文档GenerateKeyPairOptions 接口文档generateKeyPair 函数文档key/generate_key_pair 模块索引源码实现src/key/generate_key_pair.ts测试用例test/jwk/generate_key_pair.test.ts对称密钥生成对比generate_secret 文档密钥导出key/export README赞分享网络安全认证鉴权后端【免费下载链接】joseJWA, 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 用法与底层源码解析jose 非对称密钥对生成指南generateKeyPair 用法与底层源码解析 generateKeyPair 是 jose 库中用于生成非对称密钥对公钥网络安全认证鉴权后端jose 非对称密钥对生成选项 GenerateKeyPairOptions 全面解析crv、modulusLength 与 extractable 的实战用法jose 非对称密钥对生成选项 GenerateKeyPairOptions 全面解析crv、modulusLength 与 extractable 的实战用网络安全认证鉴权后端jose 对称密钥生成指南深入解析 generateSecret 与 GenerateSecretOptionsjose 对称密钥生成指南深入解析 generateSecret 与 GenerateSecretOptions jose 是一套为 Node.js、浏览器、网络安全认证鉴权后端上一篇MP4Box.js浏览器端MP4处理的完整解决方案快速实现视频文件解析与处理下一篇如何高效使用MP4Box.js实现浏览器端MP4文件处理开发者实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考