Security Subsystem Changelog

cl.security.1 Addition of the @throws Tags for Exceptions Thrown in API Version 9

Added the @throws tags for the APIs of API version 9 in the JS document.

Change Impact

For released JS interfaces, the exception handling process may be affected, including synchronous and asynchronous exceptions. Check the exception handling process based on the latest @throws tags and make adaptation.

Key API/Component Changes

Before change:

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<KeyPair> } 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<KeyPair>): void;

 /**
  * Used to generate asymmetric key pair.
  *
  * @returns { Promise<KeyPair> } the promise used to return keypair.
  * @throws { BusinessError } 401 - invalid parameters.
  * @throws { BusinessError } 17620001 - memory error.
  * @syscap SystemCapability.Security.CryptoFramework
  * @since 9
  */
 generateKeyPair(): Promise<KeyPair>;

 /**
  * 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<KeyPair> } 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<KeyPair>): 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<KeyPair> } 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<KeyPair>;
}

/**
* 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;

After change:

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<KeyPair> } 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<KeyPair>): void;

 /**
  * Used to generate asymmetric keypair.
  *
  * @returns { Promise<KeyPair> } 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<KeyPair>;

 /**
  * 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<KeyPair> } 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<KeyPair>): 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<KeyPair> } 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<KeyPair>;
}

/**
* 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;

Adaptation Guide

Check the exception handling process based on the latest @throws tags and modify the code as required.

  • For synchronization methods, such as createSign, use try/catch to process error information.

  • For asynchronous methods, such as convertKey, use try/catch to process synchronous parameter errors and use the error object to obtain asynchronous parameter errors and service execution errors.