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