diff --git a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md index 1173f2e8ff1d183ef6a1b27b99281cdf10edcce3..b44328c93044c68ac91d811d2346acbcf486ef6d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @@ -369,10 +369,6 @@ getEncoded(): DataBlob **错误码:** -> **说明:** -> -> 从API version 10开始,该接口支持抛出错误码。 - | 错误码ID | 错误信息 | | -------- | ---------------------- | | 801 | this operation is not supported. | @@ -794,8 +790,8 @@ createAsyKeyGenerator(algName: string): AsyKeyGenerator | 错误码ID | 错误信息 | | -------- | ---------------------- | | 401 | invalid parameters. | -| 80110+ | this operation is not supported. | -| 1762000110+ | memory error. | +| 801 | this operation is not supported. | +| 17620001 | memory error. | **示例:** @@ -837,7 +833,7 @@ generateKeyPair(callback: AsyncCallback\): void | -------- | ---------------------- | | 401 | invalid parameters. | | 17620001 | memory error. | -| 1763000110+ | crypto operation error. | +| 17630001 | crypto operation error. | **示例:** @@ -874,7 +870,7 @@ generateKeyPair(): Promise\ | -------- | ---------------------- | | 401 | invalid parameters. | | 17620001 | memory error. | -| 1763000110+ | crypto operation error. | +| 17630001 | crypto operation error. | **示例:** @@ -912,7 +908,7 @@ convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback\10+ | crypto operation error. | +| 17630001 | crypto operation error. | **示例:** @@ -960,7 +956,7 @@ convertKey(pubKey: DataBlob, priKey: DataBlob): Promise\ | -------- | ---------------------- | | 401 | invalid parameters. | | 17620001 | memory error. | -| 1763000110+ | crypto operation error. | +| 17630001 | crypto operation error. | **示例:** @@ -1315,7 +1311,7 @@ createCipher(transformation: string): Cipher | -------- | ---------------------- | | 401 | invalid parameters. | | 801 | this operation is not supported. | -| 1762000110+ | memory error. | +| 17620001 | memory error. | **示例:** @@ -1837,8 +1833,8 @@ Sign实例生成。
支持的规格详见框架概述“[签名验签规格] | 错误码ID | 错误信息 | | -------- | ---------------------- | | 401 | invalid parameters. | -| 80110+ | this operation is not supported. | -| 1762000110+ | memory error. | +| 801 | this operation is not supported. | +| 17620001 | memory error. | **示例:** @@ -2224,8 +2220,8 @@ Verify实例生成。
支持的规格详见框架概述“[签名验签规 | 错误码ID | 错误信息 | | -------- | ---------------------- | | 401 | invalid parameters. | -| 80110+ | this operation is not supported. | -| 1762000110+ | memory error. | +| 801 | this operation is not supported. | +| 17620001 | memory error. | **示例:** @@ -2570,8 +2566,8 @@ KeyAgreement实例生成。
支持的规格详见框架概述“[密钥协 | 错误码ID | 错误信息 | | -------- | ---------------------- | | 401 | invalid parameters. | -| 80110+ | this operation is not supported. | -| 1762000110+ | memory error. | +| 801 | this operation is not supported. | +| 17620001 | memory error. | **示例:** diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.9.1/changelogs-security.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.9.1/changelogs-security.md new file mode 100644 index 0000000000000000000000000000000000000000..af231cb94fe7c6121ae62619fe692096242b1edd --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.9.1/changelogs-security.md @@ -0,0 +1,279 @@ +# security子系统ChangeLog + +## cl.security.1 对API9中已经抛出的异常,补写throws标签 +对于在API9中已经抛出异常而JS DOC中漏写throws标签的接口,在since 9的注释中补上throws标签。 + +**变更影响** + +对于已发布的JS接口,可能影响异常处理流程,包括同步异常和异步异常。应用需要根据最新的throws标签,排查是否有遗漏的异常处理流程,结合实际情况进行适配。 + +**关键的接口/组件变更** + +修改前的接口原型: + + ```ts +interface Key { + /** + * Encode the key object to binary data. + * + * @returns { DataBlob } the binary data of the key object. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + getEncoded(): DataBlob; +} + +interface AsyKeyGenerator { + /** + * Used to generate asymmetric key pair. + * + * @param { AsyncCallback } callback - the callback used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + generateKeyPair(callback: AsyncCallback): void; + + /** + * Used to generate asymmetric key pair. + * + * @returns { Promise } the promise used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + generateKeyPair(): Promise; + + /** + * Used to convert asymmetric key data to key pair object. + * + * @param { DataBlob } pubKey - the public key data blob. + * @param { DataBlob } priKey - the private key data blob. + * @param { AsyncCallback } callback - the callback used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback): void; + + /** + * Used to convert asymmetric key data to key pair object. + * + * @param { DataBlob } pubKey - the public key data blob. + * @param { DataBlob } priKey - the private key data blob. + * @returns { Promise } the promise used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + convertKey(pubKey: DataBlob, priKey: DataBlob): Promise; +} + +/** + * Provides the asymmetric key generator instance func. + * + * @param { string } algName - indicates the algorithm name. + * @returns { AsyKeyGenerator } the generator obj create by algName. + * @throws { BusinessError } 401 - invalid parameters. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createAsyKeyGenerator(algName: string): AsyKeyGenerator; + +/** + * Create a cipher object for encryption and decryption operations according to the given specifications. + * Two different Cipher objects should be created when using RSA encryption and decryption, + * even with the same specifications. + * + * @param { string } transformation - indicates the description to be transformed to cipher specifications. + * @returns { Cipher } the cipher object returned by the function. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createCipher(transformation: string): Cipher; + +/** + * Create sign class. + * + * @param { string } algName - indicates the algorithm name and params. + * @returns { Sign } the sign class. + * @throws { BusinessError } 401 - invalid parameters. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createSign(algName: string): Sign; + +/** + * Create verify class. + * + * @param { string } algName - indicates the algorithm name and params. + * @returns { Verify } the verify class. + * @throws { BusinessError } 401 - invalid parameters. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createVerify(algName: string): Verify; + +/** + * Create key agreement class. + * + * @param { string } algName - indicates the algorithm name and params. + * @returns { KeyAgreement } the key agreement class. + * @throws { BusinessError } 401 - invalid parameters. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createKeyAgreement(algName: string): KeyAgreement; + ``` +修改后的接口原型: + + ```ts +interface Key { + /** + * Encode the key object to binary data. + * + * @returns { DataBlob } the binary data of the key object. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @throws { BusinessError } 17630001 - crypto operation error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + getEncoded(): DataBlob; +} + +interface AsyKeyGenerator { + /** + * Used to generate asymmetric keypair. + * + * @param { AsyncCallback } callback - the callback used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @throws { BusinessError } 17630001 - crypto operation error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + generateKeyPair(callback: AsyncCallback): void; + + /** + * Used to generate asymmetric keypair. + * + * @returns { Promise } the promise used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @throws { BusinessError } 17630001 - crypto operation error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + generateKeyPair(): Promise; + + /** + * Used to convert asymmetric key data to keypair object. + * + * @param { DataBlob } pubKey - the public key data blob. + * @param { DataBlob } priKey - the private key data blob. + * @param { AsyncCallback } callback - the callback used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @throws { BusinessError } 17630001 - crypto operation error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback): void; + + /** + * Used to convert asymmetric key data to keypair object. + * + * @param { DataBlob } pubKey - the public key data blob. + * @param { DataBlob } priKey - the private key data blob. + * @returns { Promise } the promise used to return keypair. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 17620001 - memory error. + * @throws { BusinessError } 17630001 - crypto operation error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + convertKey(pubKey: DataBlob, priKey: DataBlob): Promise; +} + +/** + * Create the asymmetric key generator instance according to the given algorithm name. + * + * @param { string } algName - indicates the algorithm name. + * @returns { AsyKeyGenerator } the asymmetric key generator instance. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createAsyKeyGenerator(algName: string): AsyKeyGenerator; + +/** + * Create a cipher object for encryption and decryption operations according to the given specifications. + * Two different Cipher objects should be created when using RSA encryption and decryption, + * even with the same specifications. + * + * @param { string } transformation - indicates the description to be transformed to cipher specifications. + * @returns { Cipher } the cipher object returned by the function. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createCipher(transformation: string): Cipher; + +/** + * Create a sign object for generating signatures. + * + * @param { string } algName - indicates the algorithm name and params. + * @returns { Sign } the sign class. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createSign(algName: string): Sign; + +/** + * Create a verify object for verifying signatures. + * + * @param { string } algName - indicates the algorithm name and the parameters. + * @returns { Verify } the verify class. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createVerify(algName: string): Verify; + +/** + * Create a key agreement object. + * + * @param { string } algName - indicates the algorithm name and params. + * @returns { KeyAgreement } the key agreement object. + * @throws { BusinessError } 401 - invalid parameters. + * @throws { BusinessError } 801 - this operation is not supported. + * @throws { BusinessError } 17620001 - memory error. + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ +function createKeyAgreement(algName: string): KeyAgreement; + ``` + +**适配指导** + +由于漏标的throws异常发生在较少见的情况下,应用可以结合实际情况,排查漏标的throws标签是否需要专门适配。 + +- 对于同步方法,如createSign等,请使用try/catch方式处理错误信息。 + +- 对于异步方法,如convertKey等,请使用try/catch方式处理同步的参数错误,使用error对象的方式获取异步的参数错误和业务执行错误。