1# @ohos.security.cryptoFramework (加解密算法库框架) 2 3为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。 8 9## 导入模块 10 11```javascript 12import cryptoFramework from "@ohos.security.cryptoFramework" 13``` 14 15## Result 16 17 表示执行结果的枚举。 18 19 **系统能力：** SystemCapability.Security.CryptoFramework 20 21| 名称 | 值 | 说明 | 22| ------------------------------------- | -------- | ---------------------------- | 23| INVALID_PARAMS | 401 | 非法入参。 | 24| NOT_SUPPORT | 801 | 操作不支持。 | 25| ERR_OUT_OF_MEMORY | 17620001 | 内存错误。 | 26| ERR_RUNTIME_ERROR | 17620002 | 运行时外部错误。 | 27| ERR_CRYPTO_OPERATION | 17630001 | 调用三方算法库API出错。 | 28 29## DataBlob 30 31buffer数组。 32 33 **系统能力：** SystemCapability.Security.CryptoFramework 34 35| 名称 | 类型 | 可读 | 可写 | 说明 | 36| ---- | ---------- | ---- | ---- | ------ | 37| data | Uint8Array | 是 | 是 | 数据。 | 38 39 40## cryptoFramework.createMac 41 42createMac(algName : string) : Mac 43 44生成Mac实例，用于进行消息认证码的计算与操作。<br/>支持的规格详见框架概述“[HMAC消息认证码算法规格](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节。 45 46**系统能力：** SystemCapability.Security.CryptoFramework 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 说明 | 51| ------- | ------ | ---- | ------------------------------------------------------------ | 52| algName | string | 是 | 指定摘要算法，支持算法请参考“[HMAC算法支持范围](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节 | 53 54**返回值**： 55 56| 类型 | 说明 | 57| ---- | --------------------------------------- | 58| Mac | 返回由输入算法指定生成的[Mac](#mac)对象 | 59 60**错误码：** 61 62| 错误码ID | 错误信息 | 63| -------- | ------------------ | 64| 17620001 | memory error. | 65 66**示例：** 67 68```javascript 69import cryptoFramework from "@ohos.security.cryptoFramework" 70 71var mac; 72try { 73 // 参数选择请参考上述算法支持范围 74 mac = cryptoFramework.createMac("SHA256"); 75} catch (error) { 76 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 77} 78``` 79 80## Mac 81 82Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过[createMac](#cryptoframeworkcreatemac)构造Mac实例。 83 84### 属性 85 86**系统能力：** SystemCapability.Security.CryptoFramework 87 88| 名称 | 类型 | 可读 | 可写 | 说明 | 89| ------- | ------ | ---- | ---- | -------------------- | 90| algName | string | 是 | 否 | 代表指定的摘要算法名 | 91 92### init 93 94init(key : SymKey, callback : AsyncCallback\<void>) : void; 95 96使用对称密钥初始化Mac计算 97 98**系统能力：** SystemCapability.Security.CryptoFramework 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| -------- | -------------------- | ---- | ------------ | 104| key | [SymKey](#symkey) | 是 | 共享对称密钥 | 105| callback | AsyncCallback\<void> | 是 | 回调函数 | 106 107**错误码：** 108 109| 错误码ID | 错误信息 | 110| -------- | ---------------------- | 111| 17630001 | crypto operation error. | 112 113**示例：** 114 115```javascript 116import cryptoFramework from "@ohos.security.cryptoFramework" 117 118var mac; 119try { 120 mac = cryptoFramework.createMac("SHA256"); 121} catch (error) { 122 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 123} 124var KeyBlob; 125var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 126symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { 127 if (err) { 128 console.error("[Callback] err: " + err.code); 129 } 130 mac.init(symKey, (err1, ) => { 131 if (err1) { 132 console.error("[Callback] err: " + err1.code); 133 } 134 }); 135}); 136``` 137 138### init 139 140init(key : SymKey) : Promise\<void>; 141 142使用对称密钥初始化Mac计算 143 144**系统能力：** SystemCapability.Security.CryptoFramework 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| ------ | ------ | ---- | ------------ | 150| key | [SymKey](#symkey) | 是 | 共享对称密钥 | 151 152**返回值：** 153 154| 类型 | 说明 | 155| -------------- | ----------- | 156| Promise\<void> | Promise对象 | 157 158**错误码：** 159 160| 错误码ID | 错误信息 | 161| -------- | ---------------------- | 162| 17630001 | crypto operation error. | 163 164**示例：** 165 166```javascript 167import cryptoFramework from "@ohos.security.cryptoFramework" 168 169var mac; 170try { 171 mac = cryptoFramework.createMac("SHA256"); 172} catch (error) { 173 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 174} 175console.error("Mac algName is: " + mac.algName); 176 177var KeyBlob; 178var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 179var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); 180promiseConvertKey.then(symKey => { 181 var promiseMacInit = mac.init(symKey); 182 return promiseMacInit; 183}).catch(error => { 184 console.error("[Promise]: error: " + error.message); 185}); 186 187``` 188 189### update 190 191update(input : DataBlob, callback : AsyncCallback\<void>) : void; 192 193传入消息进行Mac更新计算 194 195> **说明：** 196> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 197 198**系统能力：** SystemCapability.Security.CryptoFramework 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| -------- | -------------------- | ---- | ---------- | 204| input | [DataBlob](#datablob)| 是 | 传入的消息 | 205| callback | AsyncCallback\<void> | 是 | 回调函数 | 206 207**错误码：** 208 209| 错误码ID | 错误信息 | 210| -------- | ---------------------- | 211| 17630001 | crypto operation error. | 212 213**示例：** 214 215```javascript 216import cryptoFramework from "@ohos.security.cryptoFramework" 217 218var KeyBlob; 219var mac; 220try { 221 mac = cryptoFramework.createMac("SHA256"); 222} catch (error) { 223 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 224} 225var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 226symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { 227 if (err) { 228 console.error("[Callback] err: " + err.code); 229 } 230 mac.init(symKey, (err1, ) => { 231 if (err1) { 232 console.error("[Callback] err: " + err1.code); 233 } 234 let blob; 235 mac.update(blob, (err2, data) => { 236 if (err2) { 237 console.error("[Callback] err: " + err2.code); 238 } 239 }); 240 }); 241}); 242``` 243 244### update 245 246update(input : DataBlob) : Promise\<void>; 247 248传入消息进行Mac更新计算 249 250> **说明：** 251> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 252 253**系统能力：** SystemCapability.Security.CryptoFramework 254 255**参数：** 256 257| 参数名 | 类型 | 必填 | 说明 | 258| ------ | -------- | ---- | ---------- | 259| input | [DataBlob](#datablob) | 是 | 传入的消息 | 260 261**返回值：** 262 263| 类型 | 说明 | 264| -------------- | ----------- | 265| Promise\<void> | Promise对象 | 266 267**错误码：** 268 269| 错误码ID | 错误信息 | 270| -------- | ---------------------- | 271| 17630001 | crypto operation error. | 272 273**示例：** 274 275```javascript 276import cryptoFramework from "@ohos.security.cryptoFramework" 277 278var mac; 279try { 280 mac = cryptoFramework.createMac("SHA256"); 281} catch (error) { 282 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 283} 284console.error("Mac algName is: " + mac.algName); 285 286var KeyBlob; 287var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 288var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); 289promiseConvertKey.then(symKey => { 290 var promiseMacInit = mac.init(symKey); 291 return promiseMacInit; 292}).then(() => { 293 let blob; 294 var promiseMacUpdate = mac.update(blob); 295 return promiseMacUpdate; 296}).catch(error => { 297 console.error("[Promise]: error: " + error.message); 298}); 299 300``` 301 302### doFinal 303 304doFinal(callback : AsyncCallback\<DataBlob>) : void; 305 306返回Mac的计算结果 307 308**系统能力：** SystemCapability.Security.CryptoFramework 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| -------- | ------------------------ | ---- | -------- | 314| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | 315 316**错误码：** 317 318| 错误码ID | 错误信息 | 319| -------- | ---------------------- | 320| 17620001 | memory error. | 321| 17630001 | crypto operation error. | 322 323**示例：** 324 325```javascript 326import cryptoFramework from "@ohos.security.cryptoFramework" 327 328var KeyBlob; 329var mac; 330try { 331 mac = cryptoFramework.createMac("SHA256"); 332} catch (error) { 333 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 334} 335var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 336symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { 337 if (err) { 338 console.error("[Callback] err: " + err.code); 339 } 340 mac.init(symKey, (err1, ) => { 341 if (err1) { 342 console.error("[Callback] err: " + err1.code); 343 } 344 let blob; 345 mac.update(blob, (err2, ) => { 346 if (err2) { 347 console.error("[Callback] err: " + err2.code); 348 } 349 mac.doFinal((err3, macOutput) => { 350 if (err3) { 351 console.error("[Callback] err: " + err3.code); 352 } else { 353 console.error("[Promise]: HMAC result: " + macOutput); 354 } 355 }); 356 }); 357 }); 358}); 359``` 360 361### doFinal 362 363doFinal() : Promise\<DataBlob> 364 365返回Mac的计算结果 366 367**系统能力：** SystemCapability.Security.CryptoFramework 368 369**返回值：** 370 371| 类型 | 说明 | 372| ------------------ | ----------- | 373| Promise\<[DataBlob](#datablob)> | Promise对象 | 374 375**错误码：** 376 377| 错误码ID | 错误信息 | 378| -------- | ---------------------- | 379| 17620001 | memory error. | 380| 17630001 | crypto operation error. | 381 382**示例：** 383 384```javascript 385import cryptoFramework from "@ohos.security.cryptoFramework" 386 387var mac; 388try { 389 mac = cryptoFramework.createMac("SHA256"); 390} catch (error) { 391 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 392} 393console.error("Mac algName is: " + mac.algName); 394 395var KeyBlob; 396var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 397var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); 398promiseConvertKey.then(symKey => { 399 var promiseMacInit = mac.init(symKey); 400 return promiseMacInit; 401}).then(() => { 402 let blob; 403 var promiseMacUpdate = mac.update(blob); 404 return promiseMacUpdate; 405}).then(() => { 406 var PromiseMacDoFinal = mac.doFinal(); 407 return PromiseMacDoFinal; 408}).then(macOutput => { 409 console.error("[Promise]: HMAC result: " + macOutput.data); 410}).catch(error => { 411 console.error("[Promise]: error: " + error.message); 412}); 413``` 414 415### getMacLength 416 417getMacLength() : number 418 419获取Mac消息认证码的长度（字节数） 420 421**系统能力：** SystemCapability.Security.CryptoFramework 422 423**返回值：** 424 425| 类型 | 说明 | 426| ------ | ------------------------- | 427| number | 返回mac计算结果的字节长度 | 428 429**错误码：** 430 431| 错误码ID | 错误信息 | 432| -------- | ---------------------- | 433| 17630001 | crypto operation error. | 434 435**示例：** 436 437```javascript 438import cryptoFramework from "@ohos.security.cryptoFramework" 439 440var mac; 441try { 442 mac = cryptoFramework.createMac("SHA256"); 443} catch (error) { 444 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 445} 446console.error("Mac algName is: " + mac.algName); 447 448var KeyBlob; 449var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); 450var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); 451promiseConvertKey.then(symKey => { 452 var promiseMacInit = mac.init(symKey); 453 return promiseMacInit; 454}).then(() => { 455 let blob; 456 var promiseMacUpdate = mac.update(blob); 457 return promiseMacUpdate; 458}).then(() => { 459 var PromiseMacDoFinal = mac.doFinal(); 460 return PromiseMacDoFinal; 461}).then(macOutput => { 462 console.error("[Promise]: HMAC result: " + macOutput.data); 463 let macLen = mac.getMacLength(); 464 console.error("MAC len: " + macLen); 465}).catch(error => { 466 console.error("[Promise]: error: " + error.message); 467}); 468``` 469 470## cryptoFramework.createMd 471 472createMd(algName : string) : Md 473 474生成Md实例，用于进行消息摘要的计算与操作。<br/>支持的规格详见框架概述“[MD消息摘要算法规格](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节。 475 476**系统能力：** SystemCapability.Security.CryptoFramework 477 478**参数：** 479 480| 参数名 | 类型 | 必填 | 说明 | 481| ------- | ------ | ---- | ------------------------------------------------------------ | 482| algName | string | 是 | 指定摘要算法，支持算法请参考“[MD算法支持范围](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节 | 483 484**返回值**： 485 486| 类型 | 说明 | 487| ---- | ------------------------------------- | 488| Md | 返回由输入算法指定生成的[Md](#md)对象 | 489 490**错误码：** 491 492| 错误码ID | 错误信息 | 493| -------- | ------------------ | 494| 17620001 | memory error. | 495 496**示例：** 497 498```javascript 499import cryptoFramework from "@ohos.security.cryptoFramework" 500 501var md; 502try { 503 // 参数选择请参考上述算法支持范围 504 md = cryptoFramework.createMd("SHA256"); 505} catch (error) { 506 console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); 507} 508``` 509 510## Md 511 512Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过[createMd](#cryptoframeworkcreatemd)构造Md实例。 513 514### 属性 515 516**系统能力：** SystemCapability.Security.CryptoFramework 517 518| 名称 | 类型 | 可读 | 可写 | 说明 | 519| ------- | ------ | ---- | ---- | -------------------- | 520| algName | string | 是 | 否 | 代表指定的摘要算法名 | 521 522### update 523 524update(input : DataBlob, callback : AsyncCallback\<void>) : void; 525 526传入消息进行Md更新计算 527 528> **说明：** 529> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 530 531**系统能力：** SystemCapability.Security.CryptoFramework 532 533**参数：** 534 535| 参数名 | 类型 | 必填 | 说明 | 536| -------- | -------------------- | ---- | ---------- | 537| input | [DataBlob](#datablob)| 是 | 传入的消息 | 538| callback | AsyncCallback\<void> | 是 | 回调函数 | 539 540**错误码：** 541 542| 错误码ID | 错误信息 | 543| -------- | ---------------------- | 544| 17630001 | crypto operation error. | 545 546**示例：** 547 548```javascript 549import cryptoFramework from "@ohos.security.cryptoFramework" 550 551var md; 552try { 553 md = cryptoFramework.createMd("SHA256"); 554} catch (error) { 555 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 556} 557console.error("Md algName is: " + md.algName); 558 559let blob; 560md.update(blob, (err,) => { 561 if (err) { 562 console.error("[Callback] err: " + err.code); 563 } 564}); 565``` 566 567### update 568 569update(input : DataBlob) : Promise\<void>; 570 571传入消息进行Md更新计算 572 573> **说明：** 574> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 575 576**系统能力：** SystemCapability.Security.CryptoFramework 577 578| 参数名 | 类型 | 必填 | 说明 | 579| ------ | -------- | ---- | ---------- | 580| input | DataBlob | 是 | 传入的消息 | 581 582**返回值：** 583 584| 类型 | 说明 | 585| -------------- | ----------- | 586| Promise\<void> | Promise对象 | 587 588**错误码：** 589 590| 错误码ID | 错误信息 | 591| -------- | ---------------------- | 592| 17630001 | crypto operation error. | 593 594**示例：** 595 596```javascript 597import cryptoFramework from "@ohos.security.cryptoFramework" 598 599var md; 600try { 601 md = cryptoFramework.createMd("SHA256"); 602} catch (error) { 603 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 604} 605console.error("Md algName is: " + md.algName); 606 607let blob; 608var promiseMdUpdate = md.update(blob); 609promiseMdUpdate.then(() => { 610 // do something 611}).catch(error => { 612 console.error("[Promise]: error: " + error.message); 613}); 614``` 615 616### digest 617 618digest(callback : AsyncCallback\<DataBlob>) : void 619 620返回Md的计算结果 621 622**系统能力：** SystemCapability.Security.CryptoFramework 623 624| 参数名 | 类型 | 必填 | 说明 | 625| -------- | ------------------------ | ---- | -------- | 626| callback | AsyncCallback\<DataBlob> | 是 | 回调函数 | 627 628**错误码：** 629 630| 错误码ID | 错误信息 | 631| -------- | ---------------------- | 632| 17620001 | memory error. | 633| 17630001 | crypto operation error. | 634 635**示例：** 636 637```javascript 638import cryptoFramework from "@ohos.security.cryptoFramework" 639 640var md; 641try { 642 md = cryptoFramework.createMd("SHA256"); 643} catch (error) { 644 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 645} 646console.error("Md algName is: " + md.algName); 647 648let blob; 649md.update(blob, (err,) => { 650 if (err) { 651 console.error("[Callback] err: " + err.code); 652 } 653 md.digest((err1, mdOutput) => { 654 if (err1) { 655 console.error("[Callback] err: " + err1.code); 656 } else { 657 console.error("[Callback]: MD result: " + mdOutput); 658 } 659 }); 660}); 661``` 662 663### digest 664 665digest() : Promise\<DataBlob> 666 667返回Md的计算结果 668 669**系统能力：** SystemCapability.Security.CryptoFramework 670 671**返回值：** 672 673| 类型 | 说明 | 674| ------------------ | ----------- | 675| Promise\<[DataBlob](#datablob)> | Promise对象 | 676 677**错误码：** 678 679| 错误码ID | 错误信息 | 680| -------- | ---------------------- | 681| 17620001 | memory error. | 682| 17630001 | crypto operation error. | 683 684**示例：** 685 686```javascript 687import cryptoFramework from "@ohos.security.cryptoFramework" 688 689var md; 690try { 691 md = cryptoFramework.createMd("SHA256"); 692} catch (error) { 693 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 694} 695console.error("Md algName is: " + md.algName); 696 697let blob; 698var promiseMdUpdate = md.update(blob); 699promiseMdUpdate.then(() => { 700 var PromiseMdDigest = md.digest(); 701 return PromiseMdDigest; 702}).then(mdOutput => { 703 console.error("[Promise]: MD result: " + mdOutput.data); 704}).catch(error => { 705 console.error("[Promise]: error: " + error.message); 706}); 707``` 708 709### getMdLength 710 711getMdLength() : number 712 713获取Md消息摘要长度（字节数） 714 715**系统能力：** SystemCapability.Security.CryptoFramework 716 717**返回值：** 718 719| 类型 | 说明 | 720| ------ | ------------------------ | 721| number | 返回md计算结果的字节长度 | 722 723**错误码：** 724 725| 错误码ID | 错误信息 | 726| -------- | ---------------------- | 727| 17630001 | crypto operation error. | 728 729**示例：** 730 731```javascript 732import cryptoFramework from "@ohos.security.cryptoFramework" 733 734var md; 735try { 736 md = cryptoFramework.createMd("SHA256"); 737} catch (error) { 738 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 739} 740console.error("Md algName is: " + md.algName); 741 742let blob; 743var promiseMdUpdate = md.update(blob); 744promiseMdUpdate.then(() => { 745 var PromiseMdDigest = md.digest(); 746 return PromiseMdDigest; 747}).then(mdOutput => { 748 console.error("[Promise]: MD result: " + mdOutput.data); 749 let mdLen = md.getMdLength(); 750 console.error("MD len: " + mdLen); 751}).catch(error => { 752 console.error("[Promise]: error: " + error.message); 753}); 754``` 755 756## cryptoFramework.createRandom 757 758createRandom() : Random 759 760生成Random实例，用于进行随机数的计算与设置种子。 761 762**系统能力：** SystemCapability.Security.CryptoFramework 763 764**返回值**： 765 766| 类型 | 说明 | 767| ------ | --------------------------------------------- | 768| Random | 返回由输入算法指定生成的[Random](#random)对象 | 769 770**错误码：** 771 772| 错误码ID | 错误信息 | 773| -------- | ------------ | 774| 17620001 | memory error. | 775 776**示例：** 777 778```javascript 779import cryptoFramework from "@ohos.security.cryptoFramework" 780 781try { 782 var rand = cryptoFramework.createRandom(); 783} catch (error) { 784 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 785} 786``` 787 788## Random 789 790Random类，调用Random方法可以进行随机数计算。调用前，需要通过[createRandom](#cryptoframeworkcreaterandom)构造Random实例。 791 792### generateRandom 793 794generateRandom(len : number, callback: AsyncCallback\<DataBlob>) : void; 795 796生成指定长度的随机数 797 798**系统能力：** SystemCapability.Security.CryptoFramework 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| -------- | ------------------------ | ---- | -------------------- | 804| len | number | 是 | 表示生成随机数的长度 | 805| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | 806 807**错误码：** 808 809| 错误码ID | 错误信息 | 810| -------- | ---------------------- | 811| 17620001 | memory error. | 812| 17630001 | crypto operation error. | 813 814**示例：** 815 816```javascript 817import cryptoFramework from "@ohos.security.cryptoFramework" 818 819var rand; 820try { 821 rand = cryptoFramework.createRandom(); 822} catch (error) { 823 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 824} 825rand.generateRandom(12, (err, randData) => { 826 if (err) { 827 console.error("[Callback] err: " + err.code); 828 } else { 829 console.error("[Callback]: generate random result: " + randData.data); 830 } 831}); 832``` 833 834### generateRandom 835 836generateRandom(len : number) : Promise\<DataBlob>; 837 838生成指定长度的随机数 839 840**系统能力：** SystemCapability.Security.CryptoFramework 841 842**参数：** 843 844| 参数名 | 类型 | 必填 | 说明 | 845| ------ | ------ | ---- | -------------------- | 846| len | number | 是 | 表示生成随机数的长度 | 847 848**返回值：** 849 850| 类型 | 说明 | 851| ------------------ | ----------- | 852| Promise\<[DataBlob](#datablob)> | Promise对象 | 853 854**错误码：** 855 856| 错误码ID | 错误信息 | 857| -------- | ---------------------- | 858| 17620001 | memory error. | 859| 17630001 | crypto operation error. | 860 861**示例：** 862 863```javascript 864import cryptoFramework from "@ohos.security.cryptoFramework" 865 866var rand; 867try { 868 rand = cryptoFramework.createRandom(); 869} catch (error) { 870 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 871} 872 873var promiseGenerateRand = rand.generateRandom(12); 874promiseGenerateRand.then(randData => { 875 console.error("[Promise]: rand result: " + randData.data); 876}).catch(error => { 877 console.error("[Promise]: error: " + error.message); 878}); 879``` 880 881### setSeed 882 883setSeed(seed : DataBlob) : void; 884 885设置指定的种子 886 887**系统能力：** SystemCapability.Security.CryptoFramework 888 889| 参数名 | 类型 | 必填 | 说明 | 890| -------- | --------------------- | ---- | ---------- | 891| seed | DataBlob | 是 | 设置的种子 | 892 893**错误码：** 894 895| 错误码ID | 错误信息 | 896| -------- | ----------------- | 897| 17620001 | memory error. | 898 899**示例：** 900 901```javascript 902import cryptoFramework from "@ohos.security.cryptoFramework" 903 904var rand; 905try { 906 rand = cryptoFramework.createRandom(); 907} catch (error) { 908 console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); 909} 910 911rand.generateRandom(12, (err, randData) => { 912 if (err) { 913 console.error("[Callback] err: " + err.code); 914 } else { 915 console.error("[Callback]: generate random result: " + randData.data); 916 try { 917 rand.setSeed(randData); 918 } catch (error) { 919 console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); 920 } 921 } 922}); 923``` 924 925## ParamsSpec 926 927加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入[init()](#init-2)方法。<br/>适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在[init()](#init-2)中传入null即可）。 928 929**系统能力：** SystemCapability.Security.CryptoFramework 930 931| 名称 | 类型 | 可读 | 可写 | 说明 | 932| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | 933| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:<br/>- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式<br/>- "GcmParamsSpec": 适用于GCM模式<br/>- "CcmParamsSpec": 适用于CCM模式 | 934 935> **说明：** 936> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 937 938## IvParamsSpec 939 940加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。<br/>适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。 941 942**系统能力：** SystemCapability.Security.CryptoFramework 943 944| 名称 | 类型 | 可读 | 可写 | 说明 | 945| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | 946| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：<br/>- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节<br/>- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | 947 948> **说明：** 949> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 950 951## GcmParamsSpec 952 953加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。<br/>适用于GCM模式。 954 955**系统能力：** SystemCapability.Security.CryptoFramework 956 957| 名称 | 类型 | 可读 | 可写 | 说明 | 958| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | 959| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节 | 960| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | 961| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。<br/>采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾16字节作为解密时[init()](#init-2)方法的入参[GcmParamsSpec](#gcmparamsspec)中的的authTag | 962 963> **说明：** 964> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 965 966## CcmParamsSpec 967 968加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。<br/>适用于CCM模式。 969 970**系统能力：** SystemCapability.Security.CryptoFramework 971 972| 名称 | 类型 | 可读 | 可写 | 说明 | 973| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | 974| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 | 975| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | 976| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。<br/>采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾12字节作为解密时[init()](#init-2)方法的入参[CcmParamsSpec](#ccmparamsspec)中的authTag | 977 978> **说明：** 979> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 980 981## CryptoMode 982 983表示加解密操作的枚举。 984 985**系统能力：** SystemCapability.Security.CryptoFramework 986 987| 名称 | 值 | 说明 | 988| ------------ | ---- | ---------------- | 989| ENCRYPT_MODE | 0 | 表示进行加密操作 | 990| DECRYPT_MODE | 1 | 表示进行解密操作 | 991 992## Key 993 994密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入[Cipher](#cipher)实例的[init()](#init-2)方法。<br/>密钥可以通过密钥生成器来生成。 995 996### 属性 997 998**系统能力：** SystemCapability.Security.CryptoFramework 999 1000| 名称 | 类型 | 可读 | 可写 | 说明 | 1001| ------- | ------ | ---- | ---- | ---------------------------- | 1002| format | string | 是 | 否 | 密钥的格式。 | 1003| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | 1004 1005### getEncoded 1006 1007getEncoded() : DataBlob 1008 1009以同步方法，获取16进制形式的密钥内容。 1010 1011**系统能力：** SystemCapability.Security.CryptoFramework 1012 1013**返回值：** 1014 1015| 类型 | 说明 | 1016| --------------------- | ------------------------ | 1017| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | 1018 1019**示例：** 1020 1021```js 1022import cryptoFramework from "@ohos.security.cryptoFramework" 1023function uint8ArrayToShowStr(uint8Array) { 1024 return Array.prototype.map 1025 .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) 1026 .join(''); 1027} 1028 1029let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 1030let encodedKey = key.getEncoded(); 1031console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); 1032``` 1033 1034## SymKey 1035 1036对称密钥，是[Key](#key)的子类，在对称加解密时需要将其对象传入[Cipher](#cipher)实例的[init()](#init-2)方法使用。<br/>对称密钥可以通过对称密钥生成器[SymKeyGenerator](#symkeygenerator)来生成。 1037 1038### clearMem 1039 1040clearMem() : void 1041 1042以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。 1043 1044**系统能力：** SystemCapability.Security.CryptoFramework 1045 1046**示例：** 1047 1048```js 1049import cryptoFramework from "@ohos.security.cryptoFramework" 1050function uint8ArrayToShowStr(uint8Array) { 1051 return Array.prototype.map 1052 .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) 1053 .join(''); 1054} 1055 1056let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 1057let encodedKey = key.getEncoded(); 1058console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出密钥内容 1059key.clearMem(); 1060encodedKey = key.getEncoded(); 1061console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全零 1062``` 1063 1064## PubKey 1065 1066公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。<br/>公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 1067 1068### 属性 1069 1070**系统能力：** SystemCapability.Security.CryptoFramework 1071 1072| 名称 | 类型 | 可读 | 可写 | 说明 | 1073| ------- | ------ | ---- | ---- | ---------------------------- | 1074| format | string | 是 | 否 | 密钥的格式。 | 1075| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | 1076 1077 1078### getEncoded 1079 1080getEncoded() : DataBlob 1081 1082以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。 1083 1084**系统能力：** SystemCapability.Security.CryptoFramework 1085 1086**返回值：** 1087 1088| 类型 | 说明 | 1089| --------------------- | ------------------------ | 1090| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | 1091 1092**示例：** 1093 1094```js 1095function uint8ArrayToShowStr(uint8Array) { 1096 return Array.prototype.map 1097 .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) 1098 .join(''); 1099} 1100 1101let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 1102console.info("key format:" + key.format); 1103console.info("key algName:" + key.algName); 1104var encodedKey = key.getEncoded(); 1105console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); 1106``` 1107 1108## PriKey 1109 1110私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。<br/>私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 1111 1112### 属性 1113 1114**系统能力：** SystemCapability.Security.CryptoFramework 1115 1116| 名称 | 类型 | 可读 | 可写 | 说明 | 1117| ------- | ------ | ---- | ---- | ---------------------------- | 1118| format | string | 是 | 否 | 密钥的格式。 | 1119| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | 1120 1121### getEncoded 1122 1123getEncoded() : DataBlob 1124 1125以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 1126 1127**系统能力：** SystemCapability.Security.CryptoFramework 1128 1129**返回值：** 1130 1131| 类型 | 说明 | 1132| --------------------- | ------------------------ | 1133| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | 1134 1135**示例：** 1136 1137```js 1138function uint8ArrayToShowStr(uint8Array) { 1139 return Array.prototype.map 1140 .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) 1141 .join(''); 1142} 1143 1144let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 1145console.info("key format:" + key.format); 1146console.info("key algName:" + key.algName); 1147var encodedKey = key.getEncoded(); 1148console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); 1149``` 1150 1151### clearMem 1152 1153clearMem() : void 1154 1155以同步方法，将系统底层内存中的的密钥内容清零。 1156 1157**系统能力：** SystemCapability.Security.CryptoFramework 1158 1159**示例：** 1160 1161```js 1162let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 1163key.clearMem(); 1164``` 1165 1166## KeyPair 1167 1168非对称密钥对，包含：公钥与私钥。<br/>可以通过非对称密钥生成器AsyKeyGenerator来生成。 1169 1170> **说明：** 1171> 1172> KeyPair对象中的pubKey对象和priKey对象，作为KeyPair对象中的一个参数存在，当离开KeyPair对象作用域时，其内部对象可能被析构。<br/>业务方使用时应持有KeyPair对象的引用，而非内部pubKey或priKey对象的引用。 1173 1174### 属性 1175 1176**系统能力：** SystemCapability.Security.CryptoFramework 1177 1178| 名称 | 类型 | 可读 | 可写 | 说明 | 1179| ------- | ------ | ---- | ---- | ------------ | 1180| priKey | [PriKey](#prikey) | 是 | 否 | 私钥。 | 1181| pubKey | [PubKey](#pubkey) | 是 | 否 | 公钥。 | 1182 1183 1184## cryptoFramework.createSymKeyGenerator 1185 1186createSymKeyGenerator(algName : string) : SymKeyGenerator 1187 1188通过指定算法名称的字符串，获取相应的对称密钥生成器实例。<br/>支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 1189 1190**系统能力：** SystemCapability.Security.CryptoFramework 1191 1192**参数：** 1193 1194| 参数名 | 类型 | 必填 | 说明 | 1195| ------- | ------ | ---- | ------------------------------------------------------------ | 1196| algName | string | 是 | 待生成对称密钥生成器的算法名称。<br/>具体取值详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中的“字符串参数”。 | 1197 1198**返回值：** 1199 1200| 类型 | 说明 | 1201| ----------------------------------- | -------------------------- | 1202| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 | 1203 1204**示例：** 1205 1206```js 1207import cryptoFramework from '@ohos.security.cryptoFramework'; 1208let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); 1209``` 1210 1211## SymKeyGenerator 1212 1213对称密钥生成器。<br/>在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。 1214 1215### 属性 1216 1217**系统能力：** SystemCapability.Security.CryptoFramework 1218 1219| 名称 | 类型 | 可读 | 可写 | 说明 | 1220| ------- | ------ | ---- | ---- | ------------------------------ | 1221| algName | string | 是 | 否 | 对称密钥生成器指定的算法名称。 | 1222 1223### generateSymKey 1224 1225generateSymKey(callback : AsyncCallback\<SymKey>) : void 1226 1227异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。<br/>必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。<br/>目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 1228 1229**系统能力：** SystemCapability.Security.CryptoFramework 1230 1231**参数：** 1232 1233| 参数名 | 类型 | 必填 | 说明 | 1234| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | 1235| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | 1236 1237**错误码：** 1238 1239| 错误码ID | 错误信息 | 1240| -------- | ------------- | 1241| 17620001 | memory error. | 1242 1243**示例：** 1244 1245```js 1246import cryptoFramework from '@ohos.security.cryptoFramework'; 1247let symAlgName = '3DES192'; 1248let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); 1249symKeyGenerator.generateSymKey((err, symKey) => { 1250 if (err) { 1251 console.error(`Generate symKey failed, ${err.code}, ${err.message}`); 1252 } else { 1253 console.info(`Generate symKey success, algName: ${symKey.algName}`); 1254 } 1255}) 1256``` 1257 1258### generateSymKey 1259 1260generateSymKey() : Promise\<SymKey> 1261 1262异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。<br/>必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。<br/>目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 1263 1264**系统能力：** SystemCapability.Security.CryptoFramework 1265 1266**返回值：** 1267 1268| 类型 | 说明 | 1269| --------------------------- | --------------------------------- | 1270| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | 1271 1272**错误码：** 1273 1274| 错误码ID | 错误信息 | 1275| -------- | ------------- | 1276| 17620001 | memory error. | 1277 1278**示例：** 1279 1280```js 1281import cryptoFramework from '@ohos.security.cryptoFramework'; 1282let symAlgName = 'AES128'; 1283let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); 1284symKeyGenerator.generateSymKey() 1285.then(symKey => { 1286 console.info(`Generate symKey success, algName: ${symKey.algName}`); 1287}, error => { 1288 console.error(`Generate symKey failed, ${error.code}, ${error.message}`); 1289}) 1290``` 1291 1292### convertKey 1293 1294convertKey(key : DataBlob, callback : AsyncCallback\<SymKey>) : void 1295 1296异步根据指定数据生成对称密钥，通过注册回调函数获取结果。<br/>必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 1297 1298**系统能力：** SystemCapability.Security.CryptoFramework 1299 1300**参数：** 1301 1302| 参数名 | 类型 | 必填 | 说明 | 1303| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | 1304| key | [DataBlob](#datablob) | 是 | 指定的对称密钥材料。 | 1305| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | 1306 1307**错误码：** 1308 1309| 错误码ID | 错误信息 | 1310| -------- | --------------------------------------------------- | 1311| 17620001 | memory error. | 1312 1313**示例：** 1314 1315```js 1316import cryptoFramework from '@ohos.security.cryptoFramework'; 1317 1318function genKeyMaterialBlob() { 1319 let arr = [ 1320 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, 1321 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, 1322 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) 1323 let keyMaterial = new Uint8Array(arr); 1324 return {data : keyMaterial}; 1325} 1326 1327let symAlgName = '3DES192'; 1328let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); 1329let keyMaterialBlob = genKeyMaterialBlob(); 1330symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => { 1331 if (err) { 1332 console.error(`Convert symKey failed, ${err.code}, ${err.message}`); 1333 } else { 1334 console.info(`Convert symKey success, algName: ${symKey.algName}`); 1335 } 1336}) 1337``` 1338 1339### convertKey 1340 1341convertKey(key : DataBlob) : Promise\<SymKey> 1342 1343异步根据指定数据生成对称密钥，通过Promise获取结果。<br/>必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 1344 1345**系统能力：** SystemCapability.Security.CryptoFramework 1346 1347**参数：** 1348 1349| 参数名 | 类型 | 必填 | 说明 | 1350| ---- | --------------------- | ---- | -------------------- | 1351| key | [DataBlob](#datablob) | 是 | 指定的密钥材料数据。 | 1352 1353**返回值：** 1354 1355| 类型 | 说明 | 1356| --------------------------- | --------------------------------- | 1357| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | 1358 1359**错误码：** 1360 1361| 错误码ID | 错误信息 | 1362| -------- | --------------------------------------------- | 1363| 17620001 | memory error. | 1364 1365**示例：** 1366 1367```js 1368import cryptoFramework from '@ohos.security.cryptoFramework'; 1369 1370function genKeyMaterialBlob() { 1371 let arr = [ 1372 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, 1373 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, 1374 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) 1375 let keyMaterial = new Uint8Array(arr); 1376 return {data : keyMaterial}; 1377} 1378 1379let symAlgName = '3DES192'; 1380let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); 1381let keyMaterialBlob = genKeyMaterialBlob(); 1382symKeyGenerator.convertKey(keyMaterialBlob) 1383.then(symKey => { 1384 console.info(`Convert symKey success, algName: ${symKey.algName}`); 1385}, error => { 1386 console.error(`Convert symKey failed, ${error.code}, ${error.message}`); 1387}) 1388``` 1389 1390## cryptoFramework.createAsyKeyGenerator 1391 1392createAsyKeyGenerator(algName : string) : AsyKeyGenerator 1393 1394通过指定算法名称的字符串，获取相应的非对称密钥生成器实例。<br/>支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 1395 1396**系统能力：** SystemCapability.Security.CryptoFramework 1397 1398**参数：** 1399 1400| 参数名 | 类型 | 必填 | 说明 | 1401| ------- | ------ | ---- | -------------------------------- | 1402| algName | string | 是 | 待生成对称密钥生成器的算法名称。 | 1403 1404**返回值：** 1405 1406| 类型 | 说明 | 1407| --------------- | ---------------------------- | 1408| [AsyKeyGenerator](#asykeygenerator) | 返回非对称密钥生成器的对象。 | 1409 1410**示例：** 1411 1412```javascript 1413import cryptoFramework from "@ohos.security.cryptoFramework" 1414 1415let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); 1416``` 1417 1418## AsyKeyGenerator 1419 1420非对称密钥生成器。在使用该类的方法前，需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。 1421 1422### 属性 1423 1424**系统能力：** SystemCapability.Security.CryptoFramework 1425 1426| 名称 | 类型 | 可读 | 可写 | 说明 | 1427| ------- | ------ | ---- | ---- | -------------------------------- | 1428| algName | string | 是 | 否 | 非对称密钥生成器指定的算法名称。 | 1429 1430### generateKeyPair 1431 1432generateKeyPair(callback : AsyncCallback\<KeyPair>) : void; 1433 1434异步获取非对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。 1435 1436**系统能力：** SystemCapability.Security.CryptoFramework 1437 1438**参数：** 1439 1440| 参数名 | 类型 | 必填 | 说明 | 1441| -------- | ----------------------- | ---- | ------------------------------ | 1442| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | 1443 1444**错误码：** 1445 1446| 错误码ID | 错误信息 | 1447| -------- | ---------------------- | 1448| 17620001 | memory error. | 1449 1450**示例：** 1451 1452```javascript 1453import cryptoFramework from "@ohos.security.cryptoFramework" 1454 1455let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); 1456asyKeyGenerator.generateKeyPair((err, keyPair) => { 1457 if (err) { 1458 console.error("generateKeyPair: error."); 1459 return; 1460 } 1461 console.info("generateKeyPair: success."); 1462}) 1463``` 1464 1465 1466### generateKeyPair 1467 1468generateKeyPair() : Promise\<KeyPair> 1469 1470异步获取该非对称密钥生成器随机生成的密钥，通过Promise获取结果。 1471 1472**系统能力：** SystemCapability.Security.CryptoFramework 1473 1474**返回值：** 1475 1476| 类型 | 说明 | 1477| ----------------- | --------------------------------- | 1478| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | 1479 1480**错误码：** 1481 1482| 错误码ID | 错误信息 | 1483| -------- | ---------------------- | 1484| 17620001 | memory error. | 1485 1486**示例：** 1487 1488```javascript 1489import cryptoFramework from "@ohos.security.cryptoFramework" 1490 1491let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); 1492let keyGenPromise = asyKeyGenerator.generateKeyPair(); 1493keyGenPromise.then( keyPair => { 1494 console.info("generateKeyPair success."); 1495}).catch(error => { 1496 console.error("generateKeyPair error."); 1497}); 1498``` 1499 1500### convertKey 1501 1502convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\<KeyPair\>) : void 1503 1504异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明** 1505 1506**系统能力：** SystemCapability.Security.CryptoFramework 1507 1508**参数：** 1509 1510| 参数名 | 类型 | 必填 | 说明 | 1511| -------- | ----------- | ---- | ------------------------------ | 1512| pubKey | [DataBlob](#datablob) | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null。 | 1513| priKey | [DataBlob](#datablob) | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null。 | 1514| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | 1515 1516**错误码：** 1517 1518| 错误码ID | 错误信息 | 1519| -------- | ---------------------- | 1520| 17620001 | memory error. | 1521 1522**示例：** 1523 1524```javascript 1525import cryptoFramework from "@ohos.security.cryptoFramework" 1526let pubKey; // X.509规范、DER格式的公钥数据，此处省略数据。 1527let priKey; // PKCS#8规范、DER格式的私钥数据，此处省略数据。 1528let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); 1529asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => { 1530 if (err) { 1531 console.error("convertKey: error."); 1532 return; 1533 } 1534 console.info("convertKey: success."); 1535}) 1536``` 1537 1538### convertKey 1539 1540convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair> 1541 1542异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明** 1543 1544**系统能力：** SystemCapability.Security.CryptoFramework 1545 1546**参数：** 1547 1548| 参数名 | 类型 | 必填 | 说明 | 1549| ------ | -------- | ---- | ---------------- | 1550| pubKey | DataBlob | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null | 1551| priKey | DataBlob | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null | 1552 1553**返回值：** 1554 1555| 类型 | 说明 | 1556| ----------------- | --------------------------------- | 1557| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | 1558 1559**错误码：** 1560 1561| 错误码ID | 错误信息 | 1562| -------- | ---------------------- | 1563| 17620001 | memory error. | 1564 1565**示例：** 1566 1567```javascript 1568import cryptoFramework from "@ohos.security.cryptoFramework" 1569 1570let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); 1571let pubKey; // pubKey为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 1572let priKey; // priKey为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 1573let keyGenPromise = asyKeyGenerator.convertKey(pubKey, priKey); 1574keyGenPromise.then( keyPair => { 1575 console.info("convertKey success."); 1576}).catch(error => { 1577 console.error("convertKey error."); 1578}); 1579``` 1580 1581**密钥转换说明** 1582 15831. 非对称密钥（RSA、ECC）的公钥和私钥调用getEncoded()方法后，分别返回X.509格式和PKCS#8格式的二进制数据，此数据可用于跨应用传输或持久化存储。 15842. 当调用convertKey方法将外来二进制数据转换为算法库非对称密钥对象时，公钥应满足ASN.1语法、X.509规范、DER编码格式，私钥应满足ASN.1语法、PKCS#8规范、DER编码格式。 15853. convertKey方法中，公钥和密钥二进制数据非必选项，可单独传入公钥或私钥的数据，生成对应只包含公钥或私钥的KeyPair对象。 1586 1587## cryptoFramework.createCipher 1588 1589createCipher(transformation : string) : Cipher 1590 1591通过指定算法名称，获取相应的[Cipher](#cipher)实例。<br/>支持的规格详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节。 1592 1593**系统能力：** SystemCapability.Security.CryptoFramework 1594 1595**参数：** 1596 1597| 参数名 | 类型 | 必填 | 说明 | 1598| -------------- | ------ | ---- | ------------------------------------------------------------ | 1599| transformation | string | 是 | 待生成Cipher的算法名称（含密钥长度）、加密模式以及填充方法的组合。<br/>具体取值详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“字符串参数”。 | 1600 1601> **说明：** 1602> 1. 目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。<br/>开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。 1603> 2. 使用RSA进行非对称加解密时，必须创建两个Cipher对象分别进行加密和解密操作，而不能对同一个Cipher对象进行加解密。对称加解密没有此要求（即只要算法规格一样，可以对同一个Cipher对象进行加解密操作）。 1604 1605**返回值：** 1606 1607| 类型 | 说明 | 1608| ----------------- | ------------------------ | 1609| [Cipher](#cipher) | 返回加解密生成器的对象。 | 1610 1611**示例：** 1612 1613```javascript 1614import cryptoFramework from "@ohos.security.cryptoFramework" 1615 1616let cipherAlgName = '3DES192|ECB|PKCS7'; 1617var cipher; 1618try { 1619 cipher = cryptoFramework.createCipher(cipherAlgName); 1620 console.info(`cipher algName: ${cipher.algName}`); 1621} catch (error) { 1622 console.error(`createCipher failed, ${error.code}, ${error.message}`); 1623} 1624``` 1625 1626## Cipher 1627 1628提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。<br/>完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 1629 1630一次完整的加/解密流程在对称加密和非对称加密中略有不同： 1631 1632- 对称加解密：init为必选，update为可选（且允许多次update加/解密大数据），doFinal为必选；doFinal结束后可以重新init开始新一轮加/解密流程。 1633- RSA非对称加解密：init为必选，不支持update操作，doFinal为必选（允许连续多次doFinal加/解密大数据）；RSA不支持重复init，切换加解密模式或填充方式时，需要重新创建Cipher对象。 1634 1635### 属性 1636 1637**系统能力：** SystemCapability.Security.CryptoFramework 1638 1639 1640| 名称 | 类型 | 可读 | 可写 | 说明 | 1641| ------- | ------ | ---- | ---- | ---------------------------- | 1642| algName | string | 是 | 否 | 加解密生成器指定的算法名称。 | 1643 1644### init 1645 1646init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\<void>) : void 1647 1648初始化加解密的[cipher](#cipher)对象，通过注册回调函数获取结果。<br/>必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 1649 1650**系统能力：** SystemCapability.Security.CryptoFramework 1651 1652**参数：** 1653 1654| 参数名 | 类型 | 必填 | 说明 | 1655| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 1656| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | 1657| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | 1658| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | 1659| callback | AsyncCallback\<void> | 是 | 回调函数。当初始化成功，err为undefined，否则为错误对象。 | 1660 1661**错误码：** 1662 1663| 错误码ID | 错误信息 | 1664| -------- | --------------------------------------------------------- | 1665| 17620001 | memory error. | 1666| 17620002 | runtime error. | 1667| 17630001 | crypto operation error.| 1668 1669**示例：** 1670 1671```js 1672import cryptoFramework from '@ohos.security.cryptoFramework'; 1673let symKey; // 此处省略生成对称密钥的过程 1674let cipher; // 此处省略生成cipher实例的过程 1675 1676cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => { 1677 if (err) { 1678 console.error(`Failed to init cipher, ${err.code}, ${err.message}`); 1679 } else { 1680 console.info(`Init cipher success`); 1681 // 此处进行update等后续操作 1682 } 1683}) 1684``` 1685 1686### init 1687 1688init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\<void> 1689 1690初始化加解密的cipher对象，通过Promise获取结果。<br/>必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 1691 1692**系统能力：** SystemCapability.Security.CryptoFramework 1693 1694**参数：** 1695 1696| 参数名 | 类型 | 必填 | 说明 | 1697| ------ | ------------------------- | ---- | ------------------------------------------------------------ | 1698| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | 1699| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | 1700| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | 1701 1702**返回值：** 1703 1704| 类型 | 说明 | 1705| -------------- | -------------------------------------- | 1706| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1707 1708**错误码：** 1709 1710| 错误码ID | 错误信息 | 1711| -------- | ------------------------------------------------- | 1712| 17620001 | memory error. | 1713| 17620002 | runtime error. | 1714| 17630001 | crypto operation error.| 1715 1716**示例：** 1717 1718```js 1719import cryptoFramework from '@ohos.security.cryptoFramework'; 1720let symKey; // 此处省略生成对称密钥的过程 1721let cipher; // 此处省略生成cipher实例的过程 1722cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null) 1723.then(() => { 1724 console.info(`Init cipher success`); 1725 // 此处进行update等后续操作 1726}, error => { 1727 console.error(`Failed to init cipher, ${error.code}, ${error.message}`); 1728}) 1729``` 1730 1731### update 1732 1733update(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void 1734 1735分段更新加密或者解密数据操作，通过注册回调函数获取加/解密数据。 <br/>必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 1736 1737> **说明：** 1738> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。<br/>（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。<br/>可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。<br/>最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。<br/>而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） 1739> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。<br/>算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。<br/>AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 1740> 3. RSA非对称加解密不支持update操作。 1741 1742**系统能力：** SystemCapability.Security.CryptoFramework 1743 1744**参数：** 1745 1746| 参数名 | 类型 | 必填 | 说明 | 1747| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 1748| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | 1749| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当更新加/解密数据成功，err为undefined，data为此次更新的加/解密结果DataBlob；否则为错误对象。 | 1750 1751**错误码：** 1752 1753| 错误码ID | 错误信息 | 1754| -------- | ------------------------------------------- | 1755| 17620001 | memory error. | 1756| 17620002 | runtime error. | 1757| 17630001 | crypto operation error. | 1758 1759**示例：** 1760 1761```js 1762import cryptoFramework from '@ohos.security.cryptoFramework'; 1763 1764function stringToUint8Array(str) { 1765 let arr = []; 1766 for (let i = 0, j = str.length; i < j; ++i) { 1767 arr.push(str.charCodeAt(i)); 1768 } 1769 return new Uint8Array(arr); 1770} 1771 1772let cipher; // 此处省略生成cipher实例的过程 1773// 此处省略init()过程 1774let plainText = {data : stringToUint8Array('this is test!')}; 1775cipher.update(plainText, (err, output) => { // 加密过程举例 1776 if (err) { 1777 console.error(`Failed to update cipher`); 1778 } else { 1779 console.info(`Update cipher success`); 1780 if (output != null) { 1781 // 拼接output.data到密文 1782 } 1783 // 此处进行doFinal等后续操作 1784 } 1785}) 1786``` 1787 1788### update 1789 1790update(data : DataBlob) : Promise\<DataBlob> 1791 1792分段更新加密或者解密数据操作，通过通过Promise获取加/解密数据。<br/>必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 1793 1794> **说明：** 1795> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。<br/>（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。<br/>可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。<br/>最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。<br/>而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） 1796> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。<br/>算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。<br/>AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 1797> 3. RSA非对称加解密不支持update操作。 1798 1799**系统能力：** SystemCapability.Security.CryptoFramework 1800 1801**参数：** 1802 1803| 参数名 | 类型 | 必填 | 说明 | 1804| ---- | --------------------- | ---- | -------------------- | 1805| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | 1806 1807**返回值：** 1808 1809| 类型 | 说明 | 1810| ------------------------------- | ------------------------------------------------ | 1811| Promise\<[DataBlob](#datablob)> | Promise对象，返回此次更新的加/解密结果DataBlob。 | 1812 1813**错误码：** 1814 1815| 错误码ID | 错误信息 | 1816| -------- | -------------------------------------------- | 1817| 17620001 | memory error. | 1818| 17620002 | runtime error. | 1819| 17630001 | crypto operation error. | 1820 1821**示例：** 1822 1823```js 1824import cryptoFramework from '@ohos.security.cryptoFramework'; 1825 1826function stringToUint8Array(str) { 1827 let arr = []; 1828 for (let i = 0, j = str.length; i < j; ++i) { 1829 arr.push(str.charCodeAt(i)); 1830 } 1831 return new Uint8Array(arr); 1832} 1833 1834let cipher; // 此处省略生成cipher实例的过程 1835// 此处省略init()过程 1836let plainText = {data : stringToUint8Array('this is test!')}; 1837cipher.update(plainText) 1838.then((output) => { 1839 console.info(`Update cipher success.`); 1840 if (output != null) { 1841 // 拼接output.data到密文 1842 } 1843 // 此处进行doFinal等后续操作 1844}, error => { 1845 console.info(`Update cipher failed.`); 1846}) 1847``` 1848 1849### doFinal 1850 1851doFinal(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void 1852 1853（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。<br/>如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。<br/>根据对称加解密的模式不同，doFinal的输出有如下区别： 1854 1855- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）<br/>authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 1856- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 1857 1858（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 1859 1860> **说明：** 1861> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化<br/>（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 1862> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 1863> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 1864> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 1865 1866**系统能力：** SystemCapability.Security.CryptoFramework 1867 1868**参数：** 1869 1870| 参数名 | 类型 | 必填 | 说明 | 1871| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 1872| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。在对称加解密中允许为null，但不允许传入{data : Uint8Array(空) }。 | 1873| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当最终加/解密数据成功，err为undefined，data为剩余数据的加/解密结果DataBlob；否则为错误对象。 | 1874 1875**错误码：** 1876 1877| 错误码ID | 错误信息 | 1878| -------- | ----------------------- | 1879| 17620001 | memory error. | 1880| 17620002 | runtime error. | 1881| 17630001 | crypto operation error. | 1882 1883**示例：** 1884 1885```js 1886import cryptoFramework from '@ohos.security.cryptoFramework'; 1887 1888let cipher; // 此处省略生成cipher实例的过程 1889let data; // 此处省略准备待加密/解密数据的过程 1890// 此处省略init()和update()过程 1891cipher.doFinal(data, (err, output) => { 1892 if (err) { 1893 console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`); 1894 } else { 1895 console.info(`Finalize cipher success`); 1896 if (output != null) { 1897 // 拼接output.data得到完整的明文/密文(及authTag) 1898 } 1899 } 1900}) 1901``` 1902 1903### doFinal 1904 1905doFinal(data : DataBlob) : Promise\<DataBlob> 1906 1907（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过Promise获取加密或者解密数据。<br/>如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。<br/>根据对称加解密的模式不同，doFinal的输出有如下区别： 1908 1909- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）<br/>authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 1910- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 1911 1912（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 1913 1914> **说明：** 1915> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化<br/>（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 1916> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 1917> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 1918> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 1919 1920**系统能力：** SystemCapability.Security.CryptoFramework 1921 1922**参数：** 1923 1924| 参数名 | 类型 | 必填 | 说明 | 1925| ---- | --------------------- | ---- | -------------------- | 1926| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data参数允许为null，但不允许传入{data : Uint8Array(空) } | 1927 1928**返回值：** 1929 1930| 类型 | 说明 | 1931| ------------------------------- | ------------------------------------------------ | 1932| Promise\<[DataBlob](#datablob)> | Promise对象，返回剩余数据的加/解密结果DataBlob。 | 1933 1934**错误码：** 1935 1936| 错误码ID | 错误信息 | 1937| -------- | -------------------------------------------- | 1938| 17620001 | memory error. | 1939| 17620002 | runtime error. | 1940| 17630001 | crypto operation error. | 1941 1942**示例：** 1943 1944```js 1945import cryptoFramework from '@ohos.security.cryptoFramework'; 1946 1947let cipher; // 此处省略生成cipher实例的过程 1948let data; // 此处省略准备待加密/解密数据的过程 1949// 此处省略init()和update()过程 1950cipher.doFinal(data) 1951.then(output => { 1952 console.info(`Finalize cipher success`); 1953 if (output != null) { 1954 // 拼接output.data得到完整的明文/密文(及authTag) 1955 } 1956}, error => { 1957 console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`); 1958}) 1959``` 1960 1961**使用RSA加密的callback完整示例：** 1962 1963```javascript 1964import cryptoFramework from "@ohos.security.cryptoFramework" 1965 1966function stringToUint8Array(str) { 1967 let arr = []; 1968 for (let i = 0, j = str.length; i < j; ++i) { 1969 arr.push(str.charCodeAt(i)); 1970 } 1971 return new Uint8Array(arr); 1972} 1973 1974let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); 1975let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); 1976rsaGenerator.generateKeyPair(function (err, keyPair) { 1977 let pubKey = keyPair.pubKey; 1978 cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) { 1979 let plainText = "this is cipher text"; 1980 let input = {data : stringToUint8Array(plainText) }; 1981 cipher.doFinal(input, function (err, data) { 1982 AlertDialog.show({ message : "EncryptOutPut is " + data.data} ); 1983 }); 1984 }); 1985}); 1986``` 1987 1988**使用RSA加密的promise完整示例：** 1989 1990```javascript 1991import cryptoFramework from "@ohos.security.cryptoFramework" 1992 1993function stringToUint8Array(str) { 1994 let arr = []; 1995 for (let i = 0, j = str.length; i < j; ++i) { 1996 arr.push(str.charCodeAt(i)); 1997 } 1998 return new Uint8Array(arr); 1999} 2000 2001let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); 2002let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); 2003let keyGenPromise = rsaGenerator.generateKeyPair(); 2004keyGenPromise.then(rsaKeyPair => { 2005 let pubKey = rsaKeyPair.pubKey; 2006 return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // 传入私钥和DECRYPT_MODE可初始化解密模式 2007}).then(() => { 2008 let plainText = "this is cipher text"; 2009 let input = { data : stringToUint8Array(plainText) }; 2010 return cipher.doFinal(input); 2011}).then(dataBlob => { 2012 console.info("EncryptOutPut is " + dataBlob.data); 2013}); 2014``` 2015 2016> **说明：** 2017> 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 2018 2019## cryptoFramework.createSign 2020 2021createSign(algName : string) : Sign 2022 2023Sign实例生成。<br/>支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 2024 2025**系统能力：** SystemCapability.Security.CryptoFramework 2026 2027**参数：** 2028 2029| 参数名 | 类型 | 必填 | 说明 | 2030| ------- | ------ | ---- | ------------------------------------------------------------ | 2031| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | 2032 2033**返回值**： 2034 2035| 类型 | 说明 | 2036| ---- | -------------------------------- | 2037| Sign | 返回由输入算法指定生成的Sign对象 | 2038 2039**示例：** 2040 2041```javascript 2042import cryptoFramework from "@ohos.security.cryptoFramework" 2043 2044let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); 2045 2046let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256") 2047``` 2048 2049## Sign 2050 2051Sign类，使用Sign方法之前需要创建该类的实例进行操作，通过createSign(algName : string) : Sign方法构造此实例。Sign类不支持重复初始化，当业务方需要使用新密钥签名时，需要重新创建新Sign对象并调用init初始化。 2052 2053业务方使用时，在createSign时确定签名的模式，调用init接口设置密钥。 2054 2055当待签名数据较短时，可在init初始化后直接调用sign接口传入原文数据进行签名。 2056 2057当待签名数据较长时，可通过update接口分段传入切分后的原文数据，最后调用sign接口对整体原文数据进行签名。 2058 2059当使用update分段传入原文时，sign接口支持传null，业务方可在循环中调用update接口，循环结束后调用sign进行签名。 2060 2061### 属性 2062 2063**系统能力：** SystemCapability.Security.CryptoFramework 2064 2065| 名称 | 类型 | 可读 | 可写 | 说明 | 2066| ------- | ------ | ---- | ---- | ---------------------------- | 2067| algName | string | 是 | 否 | 签名指定的算法名称。 | 2068 2069### init 2070 2071init(priKey : PriKey, callback : AsyncCallback\<void>) : void 2072 2073使用私钥初始化Sign对象，Callback形式，Sign类暂不支持重复init 2074 2075**系统能力：** SystemCapability.Security.CryptoFramework 2076 2077**参数：** 2078 2079| 参数名 | 类型 | 必填 | 说明 | 2080| -------- | -------------------- | ---- | ---------------- | 2081| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | 2082| callback | AsyncCallback\<void> | 是 | 回调函数 | 2083 2084**错误码：** 2085 2086| 错误码ID | 错误信息 | 2087| -------- | ---------------------- | 2088| 17620001 | memory error. | 2089| 17620002 | runtime error. | 2090| 17630001 | crypto operation error. | 2091 2092### init 2093 2094init(priKey : PriKey) : Promise\<void> 2095 2096使用私钥初始化Sign对象，Promise形式，Sign类暂不支持重复init 2097 2098**系统能力：** SystemCapability.Security.CryptoFramework 2099 2100**参数：** 2101 2102| 参数名 | 类型 | 必填 | 说明 | 2103| ------ | ---- | ---- | ---------------- | 2104| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | 2105 2106**返回值：** 2107 2108| 类型 | 说明 | 2109| -------------- | ----------- | 2110| Promise\<void> | Promise对象 | 2111 2112**错误码：** 2113 2114| 错误码ID | 错误信息 | 2115| -------- | ---------------------- | 2116| 17620001 | memory error. | 2117| 17620002 | runtime error. | 2118| 17630001 | crypto operation error. | 2119 2120### update 2121 2122update(data : DataBlob, callback : AsyncCallback\<void>) : void 2123 2124追加待签名数据，callback方式 2125 2126> **说明：** 2127> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 2128 2129**系统能力：** SystemCapability.Security.CryptoFramework 2130 2131**参数：** 2132 2133| 参数名 | 类型 | 必填 | 说明 | 2134| -------- | -------------------- | ---- | ---------- | 2135| data | [DataBlob](#datablob)| 是 | 传入的消息 | 2136| callback | AsyncCallback\<void> | 是 | 回调函数 | 2137 2138**错误码：** 2139 2140| 错误码ID | 错误信息 | 2141| -------- | ---------------------- | 2142| 17620001 | memory error. | 2143| 17620002 | runtime error. | 2144| 17630001 | crypto operation error. | 2145 2146### update 2147 2148update(data : DataBlob) : Promise\<void>; 2149 2150追加待签名数据，promise方式 2151 2152> **说明：** 2153> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 2154 2155**系统能力：** SystemCapability.Security.CryptoFramework 2156 2157**参数：** 2158 2159| 参数名 | 类型 | 必填 | 说明 | 2160| ------ | -------- | ---- | ---------- | 2161| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2162 2163**返回值：** 2164 2165| 类型 | 说明 | 2166| -------------- | ----------- | 2167| Promise\<void> | Promise对象 | 2168 2169**错误码：** 2170 2171| 错误码ID | 错误信息 | 2172| -------- | ---------------------- | 2173| 17620001 | memory error. | 2174| 17620002 | runtime error. | 2175| 17630001 | crypto operation error. | 2176 2177### sign 2178 2179sign(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void 2180 2181对数据进行签名，返回签名结果，callback方式 2182 2183**系统能力：** SystemCapability.Security.CryptoFramework 2184 2185**参数：** 2186 2187| 参数名 | 类型 | 必填 | 说明 | 2188| -------- | -------------------- | ---- | ---------- | 2189| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2190| callback | AsyncCallback\<[DataBlob](#datablob) > | 是 | 回调函数 | 2191 2192**错误码：** 2193 2194| 错误码ID | 错误信息 | 2195| -------- | ---------------------- | 2196| 17620001 | memory error. | 2197| 17620002 | runtime error. | 2198| 17630001 | crypto operation error. | 2199 2200### sign 2201 2202sign(data : DataBlob) : Promise\<DataBlob> 2203 2204对数据进行签名，返回签名结果，promise方式 2205 2206**系统能力：** SystemCapability.Security.CryptoFramework 2207 2208**参数：** 2209 2210| 参数名 | 类型 | 必填 | 说明 | 2211| ------ | -------- | ---- | ---------- | 2212| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2213 2214**返回值：** 2215 2216| 类型 | 说明 | 2217| -------------- | ----------- | 2218| Promise\<void> | Promise对象 | 2219 2220**错误码：** 2221 2222| 错误码ID | 错误信息 | 2223| -------- | ---------------------- | 2224| 17620001 | memory error. | 2225| 17620002 | runtime error. | 2226| 17630001 | crypto operation error. | 2227 2228**callback示例：** 2229 2230```javascript 2231import cryptoFramework from "@ohos.security.cryptoFramework" 2232 2233function stringToUint8Array(str) { 2234 var arr = []; 2235 for (var i = 0, j = str.length; i < j; ++i) { 2236 arr.push(str.charCodeAt(i)); 2237 } 2238 var tmpArray = new Uint8Array(arr); 2239 return tmpArray; 2240} 2241 2242let globalKeyPair; 2243let SignMessageBlob; 2244let plan1 = "This is Sign test plan1"; // The first segment of data. 2245let plan2 = "This is Sign test plan2"; // The second segment of fata. 2246let input1 = { data : stringToUint8Array(plan1) }; 2247let input2 = { data : stringToUint8Array(plan2) }; 2248 2249function signMessageCallback() { 2250 let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); 2251 let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); 2252 rsaGenerator.generateKeyPair(function (err, keyPair) { 2253 globalKeyPair = keyPair; 2254 let priKey = globalKeyPair.priKey; 2255 signer.init(priKey, function (err, data) { 2256 signer.update(input1, function (err, data) { // add first segment of data 2257 signer.sign(input2, function (err, data) { // add second segment of data, sign input1 and input2 2258 SignMessageBlob = data; 2259 AlertDialog.show({message : "res" + SignMessageBlob.data}); 2260 }); 2261 }); 2262 }); 2263 }); 2264} 2265``` 2266 2267**promise示例：** 2268 2269```javascript 2270import cryptoFramework from "@ohos.security.cryptoFramework" 2271 2272function stringToUint8Array(str) { 2273 var arr = []; 2274 for (var i = 0, j = str.length; i < j; ++i) { 2275 arr.push(str.charCodeAt(i)); 2276 } 2277 var tmpArray = new Uint8Array(arr); 2278 return tmpArray; 2279} 2280 2281let globalKeyPair; 2282let SignMessageBlob; 2283let plan1 = "This is Sign test plan1"; // The first segment of data. 2284let plan2 = "This is Sign test plan2"; // The second segment of fata. 2285let input1 = { data : stringToUint8Array(plan1) }; 2286let input2 = { data : stringToUint8Array(plan2) }; 2287 2288function signMessagePromise() { 2289 let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); 2290 let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); 2291 let keyGenPromise = rsaGenerator.generateKeyPair(); 2292 keyGenPromise.then( keyPair => { 2293 globalKeyPair = keyPair; 2294 let priKey = globalKeyPair.priKey; 2295 return signer.init(priKey); 2296 }).then(() => { 2297 return signer.update(input1); // add first segment of data 2298 }).then(() => { 2299 return signer.sign(input2); // add second segment of data, sign input1 and input2 2300 }).then(dataBlob => { 2301 SignMessageBlob = dataBlob; 2302 console.info("sign output is " + SignMessageBlob.data); 2303 AlertDialog.show({message : "output" + SignMessageBlob.data}); 2304 }); 2305} 2306``` 2307 2308## cryptoFramework.createVerify 2309 2310createVerify(algName : string) : Verify 2311 2312Verify实例生成。<br/>支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 2313 2314**系统能力：** SystemCapability.Security.CryptoFramework 2315 2316**参数：** 2317 2318| 参数名 | 类型 | 必填 | 说明 | 2319| ------- | ------ | ---- | ------------------------------------------------------------ | 2320| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | 2321 2322**返回值**： 2323 2324| 类型 | 说明 | 2325| ------ | ---------------------------------- | 2326| Verify | 返回由输入算法指定生成的Verify对象 | 2327 2328**示例：** 2329 2330```javascript 2331import cryptoFramework from "@ohos.security.cryptoFramework" 2332 2333let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); 2334 2335let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256") 2336``` 2337 2338## Verify 2339 2340Verify类，使用Verify方法之前需要创建该类的实例进行操作，通过createVerify(algName : string) : Verify方法构造此实例。 2341 2342Verify类不支持重复初始化，当业务方需要使用新密钥验签时，需要重新创建新Verify对象并调用init初始化。 2343 2344业务方使用时，在createVerify时确定验签的模式，调用init接口设置密钥。 2345 2346当签名数据较短时，可在init初始化后直接调用verify接口传入签名数据和原文进行验签。 2347 2348当签名数据较长时，可通过update接口分段传入签名数据，最后调用verify接口对整体签名数据进行验签。 2349 2350当使用update分段传入签名数据时，verify接口的签名数据支持传null，业务方可在循环中调用update接口，循环结束后调用verify传入原文进行验签。 2351 2352### 属性 2353 2354**系统能力：** SystemCapability.Security.CryptoFramework 2355 2356| 名称 | 类型 | 可读 | 可写 | 说明 | 2357| ------- | ------ | ---- | ---- | ---------------------------- | 2358| algName | string | 是 | 否 | 验签指定的算法名称。 | 2359 2360 2361 2362### init 2363 2364init(pubKey : PubKey, callback : AsyncCallback\<void>) : void 2365 2366传入公钥初始化Verify对象，Callback形式 2367 2368**系统能力：** SystemCapability.Security.CryptoFramework 2369 2370**参数：** 2371 2372| 参数名 | 类型 | 必填 | 说明 | 2373| -------- | -------------------- | ---- | ---------------------------- | 2374| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | 2375| callback | AsyncCallback\<void> | 是 | 回调函数 | 2376 2377**错误码：** 2378 2379| 错误码ID | 错误信息 | 2380| -------- | ---------------------- | 2381| 17620001 | memory error. | 2382| 17620002 | runtime error. | 2383| 17630001 | crypto operation error. | 2384 2385### init 2386 2387init(pubKey : PubKey) : Promise\<void> 2388 2389传入公钥初始化Verify对象，Promise形式 2390 2391**系统能力：** SystemCapability.Security.CryptoFramework 2392 2393**参数：** 2394 2395| 参数名 | 类型 | 必填 | 说明 | 2396| ------ | ---- | ---- | ---------------------------- | 2397| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | 2398 2399**返回值：** 2400 2401| 类型 | 说明 | 2402| -------------- | ----------- | 2403| Promise\<void> | Promise对象 | 2404 2405**错误码：** 2406 2407| 错误码ID | 错误信息 | 2408| -------- | ---------------------- | 2409| 17620001 | memory error. | 2410| 17620002 | runtime error. | 2411| 17630001 | crypto operation error. | 2412 2413### update 2414 2415update(data : DataBlob, callback : AsyncCallback\<void>) : void 2416 2417追加待验签数据，callback方式 2418 2419> **说明：** 2420> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 2421 2422**系统能力：** SystemCapability.Security.CryptoFramework 2423 2424**参数：** 2425 2426| 参数名 | 类型 | 必填 | 说明 | 2427| -------- | -------------------- | ---- | ---------- | 2428| data | [DataBlob](#datablob)| 是 | 传入的消息 | 2429| callback | AsyncCallback\<void> | 是 | 回调函数 | 2430 2431**错误码：** 2432 2433| 错误码ID | 错误信息 | 2434| -------- | ---------------------- | 2435| 17620001 | memory error. | 2436| 17620002 | runtime error. | 2437| 17630001 | crypto operation error. | 2438 2439### update 2440 2441update(data : DataBlob) : Promise\<void>; 2442 2443追加待验签数据，promise方式 2444 2445> **说明：** 2446> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 2447 2448**系统能力：** SystemCapability.Security.CryptoFramework 2449 2450**参数：** 2451 2452| 参数名 | 类型 | 必填 | 说明 | 2453| ------ | -------- | ---- | ---------- | 2454| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2455 2456**返回值：** 2457 2458| 类型 | 说明 | 2459| -------------- | ----------- | 2460| Promise\<void> | Promise对象 | 2461 2462**错误码：** 2463 2464| 错误码ID | 错误信息 | 2465| -------- | ---------------------- | 2466| 17620001 | memory error. | 2467| 17620002 | runtime error. | 2468| 17630001 | crypto operation error. | 2469 2470### verify 2471 2472verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\<boolean>) : void 2473 2474对数据进行验签，返回验签结果，callback方式 2475 2476**系统能力：** SystemCapability.Security.CryptoFramework 2477 2478**参数：** 2479 2480| 参数名 | 类型 | 必填 | 说明 | 2481| ------------- | -------------------- | ---- | ---------- | 2482| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2483| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | 2484| callback | AsyncCallback\<boolean> | 是 | 回调函数 | 2485 2486**错误码：** 2487 2488| 错误码ID | 错误信息 | 2489| -------- | ---------------------- | 2490| 17620001 | memory error. | 2491| 17620002 | runtime error. | 2492| 17630001 | crypto operation error. | 2493 2494### verify 2495 2496verify(data : DataBlob, signatureData : DataBlob) : Promise\<boolean> 2497 2498对数据进行验签，返回验签结果，promise方式 2499 2500**系统能力：** SystemCapability.Security.CryptoFramework 2501 2502**参数：** 2503 2504| 参数名 | 类型 | 必填 | 说明 | 2505| ------------- | -------- | ---- | ---------- | 2506| data | [DataBlob](#datablob) | 是 | 传入的消息 | 2507| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | 2508 2509**返回值：** 2510 2511| 类型 | 说明 | 2512| ----------------- | ---------------------------- | 2513| Promise\<boolean> | 异步返回值，代表验签是否通过 | 2514 2515**错误码：** 2516 2517| 错误码ID | 错误信息 | 2518| -------- | ---------------------- | 2519| 17620001 | memory error. | 2520| 17620002 | runtime error. | 2521| 17630001 | crypto operation error. | 2522 2523**callback示例：** 2524 2525```javascript 2526import cryptoFramework from "@ohos.security.cryptoFramework" 2527 2528let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 2529let input1 = null; 2530let input2 = null; 2531let signMessageBlob = null; // 签名后的数据，此处省略 2532let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25"); 2533verifyer.init(globalKeyPair.pubKey, function (err, data) { 2534 verifyer.update(input1, function(err, data) { 2535 verifyer.verify(input2, signMessageBlob, function(err, data) { 2536 console.info("verify result is " + data); 2537 }) 2538 }); 2539}) 2540``` 2541 2542**promise示例：** 2543 2544```javascript 2545import cryptoFramework from "@ohos.security.cryptoFramework" 2546 2547let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 2548let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); 2549let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); 2550let input1 = null; 2551let input2 = null; 2552let signMessageBlob = null; // 签名后的数据，此处省略 2553verifyInitPromise.then(() => { 2554 return verifyer.update(input1); 2555}).then(() => { 2556 return verifyer.verify(input2, signMessageBlob); 2557}).then(res => { 2558 console.log("Verify result is " + res); 2559}); 2560``` 2561 2562## cryptoFramework.createKeyAgreement 2563 2564createKeyAgreement(algName : string) : KeyAgreement 2565 2566KeyAgreement实例生成。<br/>支持的规格详见框架概述“[密钥协商规格](../../security/cryptoFramework-overview.md#密钥协商规格)”一节。 2567 2568**系统能力：** SystemCapability.Security.CryptoFramework 2569 2570**参数：** 2571 2572| 参数名 | 类型 | 必填 | 说明 | 2573| ------- | ------ | ---- | ------------------------------- | 2574| algName | string | 是 | 指定密钥协商算法：目前仅支持ECC | 2575 2576**返回值**： 2577 2578| 类型 | 说明 | 2579| ------------ | ---------------------------------------- | 2580| KeyAgreement | 返回由输入算法指定生成的KeyAgreement对象 | 2581 2582**示例：** 2583 2584```javascript 2585import cryptoFramework from "@ohos.security.cryptoFramework" 2586 2587let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); 2588 2589``` 2590 2591## KeyAgreement 2592 2593KeyAgreement类，使用密钥协商方法之前需要创建该类的实例进行操作，通过createKeyAgreement(algName : string) : KeyAgreement方法构造此实例。 2594 2595### 属性 2596 2597**系统能力：** SystemCapability.Security.CryptoFramework 2598 2599| 名称 | 类型 | 可读 | 可写 | 说明 | 2600| ------- | ------ | ---- | ---- | ---------------------------- | 2601| algName | string | 是 | 否 | 密钥协商指定的算法名称。 | 2602 2603### generateSecret 2604 2605generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\<DataBlob>) : void 2606 2607基于传入的私钥与公钥进行密钥协商，返回共享秘密，Callback形式 2608 2609**系统能力：** SystemCapability.Security.CryptoFramework 2610 2611**参数：** 2612 2613| 参数名 | 类型 | 必填 | 说明 | 2614| -------- | ------------------------ | ---- | ---------------------- | 2615| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | 2616| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | 2617| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 异步接受共享秘密的回调 | 2618 2619**错误码：** 2620 2621| 错误码ID | 错误信息 | 2622| -------- | ---------------------- | 2623| 17620001 | memory error. | 2624| 17620002 | runtime error. | 2625| 17630001 | crypto operation error. | 2626 2627### generateSecret 2628 2629generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\<DataBlob> 2630 2631基于传入的私钥与公钥进行密钥协商，返回共享秘密，Promise形式 2632 2633**系统能力：** SystemCapability.Security.CryptoFramework 2634 2635**参数：** 2636 2637| 参数名 | 类型 | 必填 | 说明 | 2638| ------ | ------ | ---- | ---------------------- | 2639| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | 2640| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | 2641 2642**返回值：** 2643 2644| 类型 | 说明 | 2645| ------------------ | -------- | 2646| Promise\<[DataBlob](#datablob)> | 共享秘密 | 2647 2648**错误码：** 2649 2650| 错误码ID | 错误信息 | 2651| -------- | ---------------------- | 2652| 17620001 | memory error. | 2653| 17620002 | runtime error. | 2654| 17630001 | crypto operation error. | 2655 2656**callback示例：** 2657 2658```javascript 2659import cryptoFramework from "@ohos.security.cryptoFramework" 2660 2661let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 2662let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); 2663keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) { 2664 if (err) { 2665 console.error("keyAgreement error."); 2666 return; 2667 } 2668 console.info("keyAgreement output is " + secret.data); 2669}); 2670``` 2671 2672**promise示例：** 2673 2674```javascript 2675import cryptoFramework from "@ohos.security.cryptoFramework" 2676 2677let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 2678let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); 2679let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey); 2680keyAgreementPromise.then((secret) => { 2681 console.info("keyAgreement output is " + secret.data); 2682}).catch((error) => { 2683 console.error("keyAgreement error."); 2684}); 2685``` 2686