1# Security Subsystem Changelog
2
3## cl.security.1 Addition of the @throws Tags for Exceptions Thrown in API Version 9
4Added the @throws tags for the APIs of API version 9 in the JS document.
5
6**Change Impact**
7
8For 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.
9
10**Key API/Component Changes**
11
12Before change:
13
14 ```ts
15interface Key {
16  /**
17   * Encode the key object to binary data.
18   *
19   * @returns { DataBlob } the binary data of the key object.
20   * @syscap SystemCapability.Security.CryptoFramework
21   * @since 9
22   */
23  getEncoded(): DataBlob;
24}
25
26interface AsyKeyGenerator {
27  /**
28   * Used to generate asymmetric key pair.
29   *
30   * @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
31   * @throws { BusinessError } 401 - invalid parameters.
32   * @throws { BusinessError } 17620001 - memory error.
33   * @syscap SystemCapability.Security.CryptoFramework
34   * @since 9
35   */
36  generateKeyPair(callback: AsyncCallback<KeyPair>): void;
37
38  /**
39   * Used to generate asymmetric key pair.
40   *
41   * @returns { Promise<KeyPair> } the promise used to return keypair.
42   * @throws { BusinessError } 401 - invalid parameters.
43   * @throws { BusinessError } 17620001 - memory error.
44   * @syscap SystemCapability.Security.CryptoFramework
45   * @since 9
46   */
47  generateKeyPair(): Promise<KeyPair>;
48
49  /**
50   * Used to convert asymmetric key data to key pair object.
51   *
52   * @param { DataBlob } pubKey - the public key data blob.
53   * @param { DataBlob } priKey - the private key data blob.
54   * @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
55   * @throws { BusinessError } 401 - invalid parameters.
56   * @throws { BusinessError } 17620001 - memory error.
57   * @syscap SystemCapability.Security.CryptoFramework
58   * @since 9
59   */
60  convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback<KeyPair>): void;
61
62  /**
63   * Used to convert asymmetric key data to key pair object.
64   *
65   * @param { DataBlob } pubKey - the public key data blob.
66   * @param { DataBlob } priKey - the private key data blob.
67   * @returns { Promise<KeyPair> } the promise used to return keypair.
68   * @throws { BusinessError } 401 - invalid parameters.
69   * @throws { BusinessError } 17620001 - memory error.
70   * @syscap SystemCapability.Security.CryptoFramework
71   * @since 9
72   */
73  convertKey(pubKey: DataBlob, priKey: DataBlob): Promise<KeyPair>;
74}
75
76/**
77 * Provides the asymmetric key generator instance func.
78 *
79 * @param { string } algName - indicates the algorithm name.
80 * @returns { AsyKeyGenerator } the generator obj create by algName.
81 * @throws { BusinessError } 401 - invalid parameters.
82 * @syscap SystemCapability.Security.CryptoFramework
83 * @since 9
84 */
85function createAsyKeyGenerator(algName: string): AsyKeyGenerator;
86
87/**
88 * Create a cipher object for encryption and decryption operations according to the given specifications.
89 * Two different Cipher objects should be created when using RSA encryption and decryption,
90 * even with the same specifications.
91 *
92 * @param { string } transformation - indicates the description to be transformed to cipher specifications.
93 * @returns { Cipher } the cipher object returned by the function.
94 * @throws { BusinessError } 401 - invalid parameters.
95 * @throws { BusinessError } 801 - this operation is not supported.
96 * @syscap SystemCapability.Security.CryptoFramework
97 * @since 9
98 */
99function createCipher(transformation: string): Cipher;
100
101/**
102 * Create sign class.
103 *
104 * @param { string } algName - indicates the algorithm name and params.
105 * @returns { Sign } the sign class.
106 * @throws { BusinessError } 401 - invalid parameters.
107 * @syscap SystemCapability.Security.CryptoFramework
108 * @since 9
109 */
110function createSign(algName: string): Sign;
111
112/**
113 * Create verify class.
114 *
115 * @param { string } algName - indicates the algorithm name and params.
116 * @returns { Verify } the verify class.
117 * @throws { BusinessError } 401 - invalid parameters.
118 * @syscap SystemCapability.Security.CryptoFramework
119 * @since 9
120 */
121function createVerify(algName: string): Verify;
122
123/**
124 * Create key agreement class.
125 *
126 * @param { string } algName - indicates the algorithm name and params.
127 * @returns { KeyAgreement } the key agreement class.
128 * @throws { BusinessError } 401 - invalid parameters.
129 * @syscap SystemCapability.Security.CryptoFramework
130 * @since 9
131 */
132function createKeyAgreement(algName: string): KeyAgreement;
133 ```
134After change:
135
136 ```ts
137interface Key {
138  /**
139   * Encode the key object to binary data.
140   *
141   * @returns { DataBlob } the binary data of the key object.
142   * @throws { BusinessError } 801 - this operation is not supported.
143   * @throws { BusinessError } 17620001 - memory error.
144   * @throws { BusinessError } 17630001 - crypto operation error.
145   * @syscap SystemCapability.Security.CryptoFramework
146   * @since 9
147   */
148  getEncoded(): DataBlob;
149}
150
151interface AsyKeyGenerator {
152  /**
153   * Used to generate asymmetric keypair.
154   *
155   * @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
156   * @throws { BusinessError } 401 - invalid parameters.
157   * @throws { BusinessError } 17620001 - memory error.
158   * @throws { BusinessError } 17630001 - crypto operation error.
159   * @syscap SystemCapability.Security.CryptoFramework
160   * @since 9
161   */
162  generateKeyPair(callback: AsyncCallback<KeyPair>): void;
163
164  /**
165   * Used to generate asymmetric keypair.
166   *
167   * @returns { Promise<KeyPair> } the promise used to return keypair.
168   * @throws { BusinessError } 401 - invalid parameters.
169   * @throws { BusinessError } 17620001 - memory error.
170   * @throws { BusinessError } 17630001 - crypto operation error.
171   * @syscap SystemCapability.Security.CryptoFramework
172   * @since 9
173   */
174  generateKeyPair(): Promise<KeyPair>;
175
176  /**
177   * Used to convert asymmetric key data to keypair object.
178   *
179   * @param { DataBlob } pubKey - the public key data blob.
180   * @param { DataBlob } priKey - the private key data blob.
181   * @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
182   * @throws { BusinessError } 401 - invalid parameters.
183   * @throws { BusinessError } 17620001 - memory error.
184   * @throws { BusinessError } 17630001 - crypto operation error.
185   * @syscap SystemCapability.Security.CryptoFramework
186   * @since 9
187   */
188  convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback<KeyPair>): void;
189
190  /**
191   * Used to convert asymmetric key data to keypair object.
192   *
193   * @param { DataBlob } pubKey - the public key data blob.
194   * @param { DataBlob } priKey - the private key data blob.
195   * @returns { Promise<KeyPair> } the promise used to return keypair.
196   * @throws { BusinessError } 401 - invalid parameters.
197   * @throws { BusinessError } 17620001 - memory error.
198   * @throws { BusinessError } 17630001 - crypto operation error.
199   * @syscap SystemCapability.Security.CryptoFramework
200   * @since 9
201   */
202  convertKey(pubKey: DataBlob, priKey: DataBlob): Promise<KeyPair>;
203}
204
205/**
206 * Create the asymmetric key generator instance according to the given algorithm name.
207 *
208 * @param { string } algName - indicates the algorithm name.
209 * @returns { AsyKeyGenerator } the asymmetric key generator instance.
210 * @throws { BusinessError } 401 - invalid parameters.
211 * @throws { BusinessError } 801 - this operation is not supported.
212 * @throws { BusinessError } 17620001 - memory error.
213 * @syscap SystemCapability.Security.CryptoFramework
214 * @since 9
215 */
216function createAsyKeyGenerator(algName: string): AsyKeyGenerator;
217
218/**
219 * Create a cipher object for encryption and decryption operations according to the given specifications.
220 * Two different Cipher objects should be created when using RSA encryption and decryption,
221 * even with the same specifications.
222 *
223 * @param { string } transformation - indicates the description to be transformed to cipher specifications.
224 * @returns { Cipher } the cipher object returned by the function.
225 * @throws { BusinessError } 401 - invalid parameters.
226 * @throws { BusinessError } 801 - this operation is not supported.
227 * @throws { BusinessError } 17620001 - memory error.
228 * @syscap SystemCapability.Security.CryptoFramework
229 * @since 9
230 */
231function createCipher(transformation: string): Cipher;
232
233/**
234 * Create a sign object for generating signatures.
235 *
236 * @param { string } algName - indicates the algorithm name and params.
237 * @returns { Sign } the sign class.
238 * @throws { BusinessError } 401 - invalid parameters.
239 * @throws { BusinessError } 801 - this operation is not supported.
240 * @throws { BusinessError } 17620001 - memory error.
241 * @syscap SystemCapability.Security.CryptoFramework
242 * @since 9
243 */
244function createSign(algName: string): Sign;
245
246/**
247 * Create a verify object for verifying signatures.
248 *
249 * @param { string } algName - indicates the algorithm name and the parameters.
250 * @returns { Verify } the verify class.
251 * @throws { BusinessError } 401 - invalid parameters.
252 * @throws { BusinessError } 801 - this operation is not supported.
253 * @throws { BusinessError } 17620001 - memory error.
254 * @syscap SystemCapability.Security.CryptoFramework
255 * @since 9
256 */
257function createVerify(algName: string): Verify;
258
259/**
260 * Create a key agreement object.
261 *
262 * @param { string } algName - indicates the algorithm name and params.
263 * @returns { KeyAgreement } the key agreement object.
264 * @throws { BusinessError } 401 - invalid parameters.
265 * @throws { BusinessError } 801 - this operation is not supported.
266 * @throws { BusinessError } 17620001 - memory error.
267 * @syscap SystemCapability.Security.CryptoFramework
268 * @since 9
269 */
270function createKeyAgreement(algName: string): KeyAgreement;
271 ```
272
273**Adaptation Guide**
274
275Check the exception handling process based on the latest @throws tags and modify the code as required.
276
277- For synchronization methods, such as **createSign**, use try/catch to process error information.
278
279- 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.
280