1# 非对称密钥生成和转换规格 2 3<!--Kit: Crypto Architecture Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @zxz--3--> 6<!--Designer: @lanming--> 7<!--Tester: @PAFT--> 8<!--Adviser: @zengyawen--> 9 10当前章节说明系统支持的算法及其对应规格。密钥生成指定规格的方式有两种： 11 12- 字符串参数：以字符串的形式描述开发者需要生成的密钥规格。 13 14- 密钥参数：使用密钥的详细密码学信息，构造密钥对象。 15 16对于每种算法采用哪种方式，将会在具体的每个算法规格中介绍。 17 18## RSA 19 20RSA（Rivest–Shamir–Adleman），当前支持使用字符串参数和密钥参数两种方式生成RSA密钥。 21 22### 使用字符串参数生成 23 24以字符串参数生成RSA密钥，具体的“字符串参数”由“RSA密钥类型”和“素数个数”使用符号“|”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 25 26> **说明：** 27> 28> 生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 29 30| RSA密钥类型 | 素数个数 | 字符串参数 | API版本 | 31| -------- | -------- | -------- | -------- | 32| RSA512 | 2 | RSA512\|PRIMES_2 | 9+ | 33| RSA768 | 2 | RSA768\|PRIMES_2 | 9+ | 34| RSA1024 | 2 | RSA1024\|PRIMES_2 | 9+ | 35| RSA1024 | 3 | RSA1024\|PRIMES_3 | 9+ | 36| RSA2048 | 2 | RSA2048\|PRIMES_2 | 9+ | 37| RSA2048 | 3 | RSA2048\|PRIMES_3 | 9+ | 38| RSA3072 | 2 | RSA3072\|PRIMES_2 | 9+ | 39| RSA3072 | 3 | RSA3072\|PRIMES_3 | 9+ | 40| RSA4096 | 2 | RSA4096\|PRIMES_2 | 9+ | 41| RSA4096 | 3 | RSA4096\|PRIMES_3 | 9+ | 42| RSA4096 | 4 | RSA4096\|PRIMES_4 | 9+ | 43| RSA8192 | 2 | RSA8192\|PRIMES_2 | 9+ | 44| RSA8192 | 3 | RSA8192\|PRIMES_3 | 9+ | 45| RSA8192 | 4 | RSA8192\|PRIMES_4 | 9+ | 46| RSA8192 | 5 | RSA8192\|PRIMES_5 | 9+ | 47 48> **注意：** 49> 50> 使用同步接口生成RSA2048、RSA3072、RSA4096和RSA8192非对称密钥会增加耗时。 51> 52> 系统对主线程有时间限制，耗时较长会导致失败。建议生成大位数密钥时，使用异步接口或[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)。 53> 54> 创建RSA非对称密钥生成器时，若用于随机生成密钥，生成的RSA密钥规格与创建时指定的密钥规格一致；若用于密钥转换，生成的RSA密钥规格与转换时指定的密钥数据规格一致。 55 56### 使用密钥参数生成 57 58从API版本10开始，支持使用密钥参数生成RSA密钥。 59 60RSA密钥参数，涉及三个整数，包括： 61 62- n：模数（Modulus），是私钥和公钥的公共参数。 63 64- sk：私钥指数（privateExponent），公式中常写作d。 65 66- pk：公钥指数（publicExponent），公式中常写作e。 67 68创建非对称密钥生成器时，支持根据指定的公钥和私钥参数生成RSA密钥，具体情况见下表： 69 70- √：表示需要指定这一列中的具体属性，来构成密钥参数。 71 72- ×：表示这一列中的具体属性对应某种密钥参数，但是当前不支持通过该密钥参数生成密钥。 73 74| | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 | 75| -------- | -------- | -------- | -------- | -------- | 76| n | × | √ | × | √ | 77| pk | N/A | √ | N/A | √ | 78| sk | N/A | N/A | × | √ | 79 80根据上表： 81 82- RSA不支持通过指定公共参数（n）来随机生成密钥。 83 84- RSA不支持通过指定私钥参数（n, sk）来生成私钥。 85 86## ECC 87 88ECC（Elliptic Curve Cryptography），是一种基于椭圆曲线数学的公钥密码算法。 89 90椭圆曲线算法可以看作是定义在特殊集合下数的运算，当前算法库支持的ECC密钥均为Fp域的椭圆曲线，p为素数，Fp域也称素数域。 91 92支持使用字符串参数和密钥参数生成ECC密钥，还支持通过曲线名生成公共密钥参数。 93 94### 使用字符串参数生成 95 96以字符串参数生成ECC密钥，具体的“字符串参数”由“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 97 98| 非对称密钥算法 | 密钥长度（bit） | 曲线名 | 字符串参数 | API版本 | 99| -------- | -------- | -------- | -------- | -------- | 100| ECC | 224 | NID_secp224r1 | ECC224 | 9+ | 101| ECC | 256 | NID_X9_62_prime256v1 | ECC256 | 9+ | 102| ECC | 384 | NID_secp384r1 | ECC384 | 9+ | 103| ECC | 521 | NID_secp521r1 | ECC521 | 9+ | 104| ECC | 160 | NID_brainpoolP160r1 | ECC_BrainPoolP160r1 | 11+ | 105| ECC | 160 | NID_brainpoolP160t1 | ECC_BrainPoolP160t1 | 11+ | 106| ECC | 192 | NID_brainpoolP192r1 | ECC_BrainPoolP192r1 | 11+ | 107| ECC | 192 | NID_brainpoolP192t1 | ECC_BrainPoolP192t1 | 11+ | 108| ECC | 224 | NID_brainpoolP224r1 | ECC_BrainPoolP224r1 | 11+ | 109| ECC | 224 | NID_brainpoolP224t1 | ECC_BrainPoolP224t1 | 11+ | 110| ECC | 256 | NID_brainpoolP256r1 | ECC_BrainPoolP256r1 | 11+ | 111| ECC | 256 | NID_brainpoolP256t1 | ECC_BrainPoolP256t1 | 11+ | 112| ECC | 320 | NID_brainpoolP320r1 | ECC_BrainPoolP320r1 | 11+ | 113| ECC | 320 | NID_brainpoolP320t1 | ECC_BrainPoolP320t1 | 11+ | 114| ECC | 384 | NID_brainpoolP384r1 | ECC_BrainPoolP384r1 | 11+ | 115| ECC | 384 | NID_brainpoolP384t1 | ECC_BrainPoolP384t1 | 11+ | 116| ECC | 512 | NID_brainpoolP512r1 | ECC_BrainPoolP512r1 | 11+ | 117| ECC | 512 | NID_brainpoolP512t1 | ECC_BrainPoolP512t1 | 11+ | 118| ECC | 256 | NID_secp256k1 | ECC_Secp256k1 | 14+ | 119 120> **注意：** 121> 122> 创建ECC非对称密钥生成器时，如果用于随机生成密钥，生成的ECC密钥规格与创建密钥生成器时指定的密钥规格一致。如果用于密钥转换，生成的ECC密钥规格与密钥转换时指定的密钥数据规格一致。 123 124### 使用密钥参数生成 125 126从API版本10开始，支持使用密钥参数生成ECC密钥。 127 128Fp域下的ECC密钥参数包括： 129 130- p：素数，用于确定Fp。 131 132- a, b：确定椭圆曲线的方程。 133 134- g：椭圆曲线的一个基点(base point)，可由gx，gy表示。 135 136- n：基点g的阶(order)。 137 138- h：余因子(cofactor)。 139 140- sk：私钥，是一个随机整数，小于n。 141 142- pk：公钥，是椭圆曲线上的一个点， pk = sk \* g。 143 144创建非对称密钥生成器时，支持使用指定的公钥和私钥参数生成ECC密钥，具体情况见下表： 145 146- √：表示需要指定这一列中的具体属性，来构成密钥参数。 147 148| | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 | 149| -------- | -------- | -------- | -------- | -------- | 150| fieldType | √ | √ | √ | √ | 151| p | √ | √ | √ | √ | 152| a | √ | √ | √ | √ | 153| b | √ | √ | √ | √ | 154| g | √ | √ | √ | √ | 155| n | √ | √ | √ | √ | 156| h | √ | √ | √ | √ | 157| pk | N/A | √ | N/A | √ | 158| sk | N/A | N/A | √ | √ | 159 160> **说明：** 161> - 当前ECC只支持Fp域，因此fieldType固定为"Fp"。fieldType和p构成了属性field，当前field只支持[ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10)。 162> 163> - g和pk为ECC曲线上的点，属于[Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10)类型，需要指定具体的X和Y坐标。 164 165### 使用曲线名生成密钥参数 166 167从API版本11开始，支持使用曲线名来生成ECC公共密钥参数。 168 169> **说明：** 170> - 曲线名为要求输入的字符串参数，支持的曲线名请参考[ECC密钥字符串参数表](#使用字符串参数生成-1)中的“曲线名”一列。 171> 172> - 生成的公共密钥参数可以直接用于随机生成公私钥，也可用于构造公钥、私钥及公私钥对密钥参数。 173 174## DSA 175 176DSA（Digital Signature Algorithm），是一种基于模算数和整数有限域离散对数难题的一种公钥密码算法，常用于数字签名和验签，不能用于加解密。 177 178当前支持使用字符串参数和密钥参数两种方式生成DSA密钥。 179 180### 约束与限制 181 182使用同步接口生成DSA2048或DSA3072非对称密钥，或者处理明文长度超过2048位，会导致耗时增加。 183 184系统对主线程有时间限制，耗时较长会导致失败。建议生成大位数密钥时，使用异步接口或[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)。 185 186### 使用字符串参数生成 187 188使用字符串参数生成DSA密钥，具体的“字符串参数”由“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 189 190| 非对称密钥算法 | 密钥长度（bit） | 字符串参数 | API版本 | 191| -------- | -------- | -------- | -------- | 192| DSA | 1024 | DSA1024 | 10+ | 193| DSA | 2048 | DSA2048 | 10+ | 194| DSA | 3072 | DSA3072 | 10+ | 195 196> **注意：** 197> 198> 使用同步接口生成DSA2048、DSA3072非对称密钥或明文长度超过2048位会导致耗时增加。 199> 200> 系统对主线程有时间限制，耗时较长会导致失败。建议生成大位数密钥时，使用异步接口或[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)。 201> 202> 创建的DSA非对称密钥生成器用于随机生成密钥时，生成的密钥规格与创建时指定的密钥规格一致。用于密钥转换时，生成的密钥规格与转换时指定的密钥数据规格一致。 203 204### 使用密钥参数生成 205 206从API版本10开始支持，使用密钥参数生成DSA密钥。 207 208DSA密钥参数，包括： 209 210- p：一个素模数，比特长度为64的整数倍。 211 212- q：p-1的素因子，长度与p的长度有关。 213 214- g：g = (h ^ ((p - 1) / q)) mod p，h为满足1 < h < p -1的任意整数。 215 216- sk：私钥，为随机生成的整数，满足0 < sk < q。 217 218- pk：公钥，pk = (g ^ sk) mod p。 219 220当创建非对称密钥生成器时，支持根据指定的公钥和私钥参数生成DSA密钥，具体情况参见下表： 221 222- √：表示需要指定这一列中的具体属性，来构成密钥参数。 223 224- ×：表示这一列中的具体属性对应某种密钥参数，但是当前不支持通过该密钥参数生成密钥。 225 226| | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 | 227| -------- | -------- | -------- | -------- | -------- | 228| p | √ | √ | × | √ | 229| q | √ | √ | × | √ | 230| g | √ | √ | × | √ | 231| pk | N/A | √ | N/A | √ | 232| sk | N/A | N/A | × | √ | 233 234> **说明：** 235> - DSA不支持通过指定私钥参数（p, q, g, sk）来生成私钥。 236> 237> - 当使用公共参数（p, q, g）来生成DSA密钥对时，DSA密钥长度至少需要1024位。 238 239## SM2 240 241SM2是一种基于椭圆曲线的公钥密码算法，采用Fp域上的椭圆曲线。 242 243当前支持使用字符串参数和密钥参数生成SM2密钥，并支持通过曲线名生成公共密钥参数。 244 245### 使用字符串参数生成 246 247当前支持以字符串参数生成SM2密钥，具体的“字符串参数”由“非对称密钥算法”和“密钥长度”使用符号“_”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 248 249| 非对称密钥算法 | 密钥长度（bit） | 曲线名 | 字符串参数 | API版本 | 250| -------- | -------- | -------- | -------- | -------- | 251| SM2 | 256 | NID_sm2 | SM2_256 | 10+ | 252 253### 使用密钥参数生成 254 255从API版本11开始，支持使用密钥参数生成SM2密钥。 256 257Fp域下的SM2密钥参数包括： 258 259- p：素数，用于确定Fp。 260 261- a, b：确定椭圆曲线的方程。 262 263- g：椭圆曲线的一个基点(base point)，可由gx，gy表示。 264 265- n：基点g的阶(order)。 266 267- h：余因子(cofactor)。 268 269- sk：私钥，是一个随机整数，小于n。 270 271- pk：公钥，是椭圆曲线上的一个点，pk = sk \* g。 272 273当创建非对称密钥生成器时，支持根据指定的公钥和私钥参数生成SM2密钥，具体支持情况如表所示： 274 275- √：表示需要指定这一列中的具体属性，来构成密钥参数。 276 277| | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 | 278| -------- | -------- | -------- | -------- | -------- | 279| fieldType | √ | √ | √ | √ | 280| p | √ | √ | √ | √ | 281| a | √ | √ | √ | √ | 282| b | √ | √ | √ | √ | 283| g | √ | √ | √ | √ | 284| n | √ | √ | √ | √ | 285| h | √ | √ | √ | √ | 286| pk | N/A | √ | N/A | √ | 287| sk | N/A | N/A | √ | √ | 288 289> **说明：** 290> - 当前SM2只支持Fp域，因此fieldType固定为"Fp"。fieldType和p构成了属性field，当前field只支持[ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10)。 291> 292> - g和pk为SM2曲线上的点，属于[Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10)类型，需要指定具体X，Y坐标。 293 294### 使用曲线名生成密钥参数 295 296从API版本11开始，支持使用曲线名称生成SM2公钥参数。 297 298> **说明：** 299> - 曲线名为要求输入的字符串参数，支持的曲线名为"NID_sm2"。 300> 301> - 生成的公共密钥参数可以直接随机生成公私钥，也可用于构造公、私以及公私钥对密钥参数。 302 303## Ed25519 304 305Ed25519算法是基于EdDSA算法的数字签名算法，密钥长度为256位，采用Edwards曲线实现。该算法不支持加解密，主要用于数字签名和验证。 306 307当前支持使用字符串参数和密钥参数生成Ed25519密钥。 308 309### 使用字符串参数生成 310 311使用字符串参数生成 Ed25519 密钥，以在创建非对称密钥生成器时指定密钥规格。 312 313| 非对称密钥算法 | 字符串参数 | API版本 | 314| -------- | -------- | -------- | 315| Ed25519 | Ed25519 | 11+ | 316 317### 使用密钥参数生成 318 319从API版本11开始，支持使用密钥参数生成Ed25519密钥。 320 321Ed25519密钥参数包括： 322 323- sk：私钥，一个 32 字节的随机值。 324 325- pk：公钥，一个 32 字节的值，从私钥派生而来。 326 327当创建非对称密钥生成器时，支持根据指定的公钥和私钥参数生成Ed25519密钥，具体情况见下表： 328 329- √：表示需要指定这一列中的具体属性，来构成密钥参数。 330 331| | 公钥参数 | 私钥参数 | 公私钥对参数 | 332| -------- | -------- | -------- | -------- | 333| pk | √ | N/A | √ | 334| sk | N/A | √ | √ | 335 336> **说明：** 337> 338> Ed25519密钥参数没有公共参数，不支持通过公共参数生成密钥。 339 340## X25519 341 342X25519算法是一种 Diffie-Hellman 密钥交换算法，用于密钥协商。 343 344支持使用字符串参数和密钥参数生成X25519密钥。 345 346### 使用字符串参数生成 347 348使用字符串参数生成X25519密钥，指定密钥规格。 349 350| 非对称密钥算法 | 字符串参数 | API版本 | 351| -------- | -------- | -------- | 352| X25519 | X25519 | 11+ | 353 354### 使用密钥参数生成 355 356从API版本11开始支持使用密钥参数生成X25519密钥。 357 358X25519密钥参数包括： 359 360- sk：私钥，一个 32 字节的随机值。 361 362- pk：公钥，一个 32 字节的值，从私钥派生而来。 363 364当创建非对称密钥生成器时，指定公/私钥参数生成X25519密钥的支持情况如表所示。 365 366- √：表示需要指定这一列中的具体属性，来构成密钥参数。 367 368| | 公钥参数 | 私钥参数 | 公私钥对参数 | 369| -------- | -------- | -------- | -------- | 370| pk | √ | N/A | √ | 371| sk | N/A | √ | √ | 372 373> **说明：** 374> 375> X25519没有公共密钥参数，不支持通过公共参数生成密钥。 376 377## DH 378 379DH（Diffie–Hellman key exchange），是一种密钥协商算法，只涉及公钥的交换，它可以提供前向安全性，即使在通信渠道被监听的情况下，也不会暴露双方的私钥。 380 381支持使用字符串参数和密钥参数生成DH密钥，支持根据素数长度和私钥长度生成公共密钥参数。 382 383### 使用字符串参数生成 384 385以字符串参数生成DH密钥，具体的“字符串参数”由“非对称密钥算法”和“知名安全素数群参数”使用符号“_”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 386 387| 非对称密钥算法 | 知名安全素数群参数 | 密钥长度（bit） | 字符串参数 | API版本 | 388| -------- | -------- | -------- | -------- | -------- | 389| DH | modp1536 | 1536 | DH_modp1536 | 11+ | 390| DH | modp2048 | 2048 | DH_modp2048 | 11+ | 391| DH | modp3072 | 3072 | DH_modp3072 | 11+ | 392| DH | modp4096 | 4096 | DH_modp4096 | 11+ | 393| DH | modp6144 | 6144 | DH_modp6144 | 11+ | 394| DH | modp8192 | 8192 | DH_modp8192 | 11+ | 395| DH | ffdhe2048 | 2048 | DH_ffdhe2048 | 11+ | 396| DH | ffdhe3072 | 3072 | DH_ffdhe3072 | 11+ | 397| DH | ffdhe4096 | 4096 | DH_ffdhe4096 | 11+ | 398| DH | ffdhe6144 | 6144 | DH_ffdhe6144 | 11+ | 399| DH | ffdhe8192 | 8192 | DH_ffdhe8192 | 11+ | 400 401> **注意：** 402> 403> 创建DH非对称密钥生成器时，如果用于随机生成密钥，生成的DH密钥规格与创建密钥生成器时指定的密钥规格一致；如果用于密钥转换，生成的DH密钥规格与密钥转换时指定的密钥数据规格一致。 404 405### 使用密钥参数生成 406 407从API版本11开始支持使用密钥参数生成DH密钥。 408 409DH密钥参数，包括： 410 411- p：一个足够大的素数，用作有限域的模数。它被所有通信双方共享。 412 413- g：g是DH算法的生成元，是素数p的原根。它被所有通信双方共享。 414 415- l：length，表示私钥长度，以bit为单位。当l为0时，代表不指定私钥长度。 416 417- sk：私钥，一个随机生成的私钥值。 418 419- pk：公钥，通过使用公共参数（p 和 g）和私钥进行计算得到。 420 421当创建非对称密钥生成器时，对于指定公/私钥参数生成DH密钥的支持情况，如表所示。 422 423- √：表示需要指定这一列中的具体属性，来构成密钥参数。 424 425| | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 | 426| -------- | -------- | -------- | -------- | -------- | 427| p | √ | √ | √ | √ | 428| g | √ | √ | √ | √ | 429| l | √ | √ | √ | √ | 430| pk | N/A | √ | N/A | √ | 431| sk | N/A | N/A | √ | √ | 432 433### 使用素数长度和私钥长度生成公共密钥参数 434 435从API版本11开始，使用素数长度和私钥长度生成DH公共密钥参数。 436 437如果素数长度与安全素数组的素数长度一致，则选用对应的知名安全素数群。对应关系如表所示。 438 439| 素数长度（bit） | 知名安全素数群 | 440| -------- | -------- | 441| 2048 | ffdhe2048 | 442| 3072 | ffdhe3072 | 443| 4096 | ffdhe4096 | 444| 6144 | ffdhe6144 | 445| 8192 | ffdhe8192 | 446 447- 素数p的比特长度必须大于等于512且小于等于10000。 448 449- 私钥长度l为可选参数，默认为0，l值的设置范围需大于2*(96+(素数P位数-1)/1024*16)。 450 451- 生成的公共密钥参数可以直接用于随机生成公私钥，也可以用于构造公钥、私钥或公私钥对。 452 453- 生成非知名群的密钥参数耗时较长，建议优先选用知名安全素数群。 454 455