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