1# @system.cipher (Cipher Algorithm)
2
3> **NOTE**
4>
5> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
6>
7> - The APIs provided by this module are deprecated since API version 9. You are advised to use [@ohos.security.cryptoFramework Cipher](js-apis-cryptoFramework.md#cipher).
8
9## Modules to Import
10
11
12```js
13import cipher from '@system.cipher';
14```
15
16## CipherResponse
17
18Defines the response to the cipher interface called.
19
20**System capability**: SystemCapability.Security.Cipher
21
22| Name| Type  | Readable| Writable|Description        |
23| ------ | ------ | ---- | ---- | ------------ |
24| text   | string | Yes  | No  | Response content.|
25
26
27## CipherRsaOptions
28
29Defines the input parameters of **cipher.rsa()**.
30
31**System capability**: SystemCapability.Security.Cipher
32
33| Name        | Type                                | Mandatory| Description                                                        |
34| -------------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
35| action         | string                               | Yes  | Action to perform. The options are as follows:<br>1. **encrypt**: Encrypts data.<br>2. **decrypt**: Decrypts data.|
36| text           | string                               | Yes  | Text to be encrypted or decrypted.<br> The text to be encrypted must be a common text and cannot exceed the length calculated based on the formula (keySize/8 - 66). **keySize** indicates the key length. <br>For example, if the key length is 1024 bytes, the text cannot exceed 62 bytes (1024/8 - 66 = 62). The text to be decrypted must be a binary value encoded in Base64. The default format is used for Base64 encoding.|
37| key            | string                               | Yes  | RSA key. It is a public key in encryption and a private key in decryption.     |
38| transformation | string                               | No  | RSA padding. The default value is **RSA/None/OAEPWithSHA256AndMGF1Padding**.|
39| success        | (data: [CipherResponse](#cipherresponse)) => void       | No  | Called when data is encrypted or decrypted successfully.                                    |
40| fail           | (data: string, code: number) => void | No  | Called when data fails to be encrypted or decrypted.                                    |
41| complete       | () => void                           | No  | Called when the execution is complete.                                    |
42
43## CipherAesOptions
44
45Defines the input parameters of **cipher.aes()**.
46
47**System capability**: SystemCapability.Security.Cipher
48
49| Name        | Type                                | Mandatory| Description                                                        |
50| -------------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
51| action         | string                               | Yes  | Action to perform. The options are as follows:<br>1. **encrypt**: Encrypts data.<br>2. **decrypt**: Decrypts data.|
52| text           | string                               | Yes  | Text to be encrypted or decrypted.<br> The text to be encrypted must be common text. The text to be decrypted must be a binary value encoded in Base64. The default format is used for Base64 encoding.|
53| key            | string                               | Yes  | Key used for encryption or decryption. It is a Base64 encoded string.|
54| transformation | string                               | No  | Encryption mode and padding of the AES algorithm. The default value is **AES/CBC/PKCS5Padding**.         |
55| iv             | string                               | No  | Initialization vector (IV) for AES-based encryption and decryption. The value is a string encoded in Base64. The default value is the key value.|
56| ivOffset       | string                               | No  | Offset of the IV for AES-based encryption and decryption. The default value is **0**, which is the only value supported.                 |
57| ivLen          | string                               | No  | Length of the IV, in bytes. This field is reserved. The default value is **16**, which is the only value supported.|
58| success        | (data: [CipherResponse](#cipherresponse)) => void       | No  | Called when data is encrypted or decrypted successfully.                                    |
59| fail           | (data: string, code: number) => void | No  | Called when data fails to be encrypted or decrypted.                                    |
60| complete       | () => void                           | No  | Called when the execution is complete.                                    |
61
62## cipher.rsa
63
64rsa(options: CipherRsaOptions): void
65
66Encrypts or decrypts data using RSA.
67
68**System capability**: SystemCapability.Security.Cipher
69
70**Parameters**
71
72| Name| Type| Mandatory| Description|
73| -------- | -------- | -------- | -------- |
74| options | [CipherRsaOptions](#cipherrsaoptions) | Yes| Parameters set for RSA encryption or decryption.|
75
76**Example**
77
78```js
79export default {
80  rsa() {
81    cipher.rsa({
82      // Encrypt data.
83      action: 'encrypt',
84      // Text to be encrypted.
85      text: 'hello',
86      // Base64-encoded public key used for encryption.
87      key:
88     'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCx414QSP3RsYWYzf9mkBMiBAXo\n' +
89     '6S7Lpva1fKlcuVxjoFC1iMnzD4mC0uiL4k5MNi43J64c7dbqi3qAJjdAtuwQ6NZJ\n' +
90     '+Enz0RzmVFh/4yk6lmqRzuEFQqhQqSZzaLq6sq2N2G0Sv2Xl3sLvqAfe2HNm2oBw\n' +
91     'jBpApTJ3TeneOo6Z5QIDAQAB',
92      success: function(data) {
93        console.log(`handling success:${data.text}`);
94      },
95      fail: function(data, code) {
96        console.log(`### cipher.rsa encrypt fail ### ${code}:${data}`);
97      },
98      complete: function() {
99        console.log(`operation complete!`);
100      }
101      });
102      cipher.rsa({
103        // Decrypt data.
104        action: 'decrypt',
105        // Text to be decrypted, which is binary text encoded in Base64. The decrypted text is "hello".
106        text:
107       'EPeCFPib6ayKbA0M6oSywARvFZ8dFYfjQv3nY8ikZGtS9UHq2sLPvAfpeIzggSiCxqbWeCftP1XQ\n' +
108       'Sa+jEpzFlT1qoSTunBbrYzugPTajIJDTg6R1IRsF/J+mmakn0POVPvi4jCo9wqavB324Bx0Wipnc\n' +
109       'EU5WO0oBHo5l4x6dTpU=',
110           // Base64-encoded private key used for decryption.
111         key:
112        'MIICXgIBAAKBgQCx414QSP3RsYWYzf9mkBMiBAXo6S7Lpva1fKlcuVxjoFC1iMnz\n' +
113        'D4mC0uiL4k5MNi43J64c7dbqi3qAJjdAtuwQ6NZJ+Enz0RzmVFh/4yk6lmqRzuEF\n' +
114        'QqhQqSZzaLq6sq2N2G0Sv2Xl3sLvqAfe2HNm2oBwjBpApTJ3TeneOo6Z5QIDAQAB\n' +
115        'AoGBAKPNtoRQcklxqo+2wQP0j2m3Qqnib1DggjVEgb/8f/LNYQSI3U2QdROemryU\n' +
116        'u3y6N3xacZ359PktTrRKfH5+8ohmHGhIuPAnefp6bLvAFUcl4t1xm74Cow62Kyw3\n' +
117        'aSbmuTG98dxPA1sXD0jiprdtsq2wQ9CoKNyY7/d/pKoqxNuBAkEA4GytZ60NCTj9\n' +
118        'w24jACFeko5YqCFY/TTLoc4SQvWtFMnimRPclLZhtUIK0P8dib71UFedx+AxklgL\n' +
119        'A5gjcfo+2QJBAMrqiwyCh3OQ5DhyRPDwt87x1/jg5fy4hhete2ufSf2FoQCVqO+w\n' +
120        'PKoljdXmJeS6rGgzGibstuHLrP3tcIho4+0CQD3ZFWzF/xq0jxKlrpWhnJuNCRfE\n' +
121        'oO6e9yNvVA8J/5oEDSOcmqSNIp4+RhbUx8InUxnCG6Ryv5aSFu71pYcKrPkCQQCL\n' +
122        'RUGcm3ZGTnslduB0knNF+V2ndwzDUQ7P74UXT+PjurTPhujFYiuxCEd6ORVnEOzG\n' +
123        'M9TORIgdH8MjIbWsGnndAkEAw9yURDaorE8IYPLF2IEn09g1uzvWPs3phDb6smVx\n' +
124        '8GfqIdUNf+aCG5TZK/kXBF1sqcsi7jXMAf4jBlejVbSVZg==',
125         success: function(data) {
126           console.log(`handling success:${data.text}`);
127         },
128         fail: function(data, code) {
129           console.log(`### cipher.rsa encrypt fail ### ${code}:${data}`);
130         },
131         complete: function() {
132           console.log(`operation complete!`);
133         }
134       });
135   }
136}
137```
138
139
140## cipher.aes
141
142aes(options: CipherAesOptions): void
143
144Encrypts or decrypts data using AES.
145
146**System capability**: SystemCapability.Security.Cipher
147
148**Parameters**
149
150| Name| Type| Mandatory| Description|
151| -------- | -------- | -------- | -------- |
152| options | [CipherAesOptions](#cipheraesoptions) | Yes| Parameters set for AES encryption or decryption.|
153
154**Example**
155
156```js
157export default {
158  aes() {
159    cipher.aes({
160      // Encrypt data.
161      action: 'encrypt',
162      // Text to be encrypted.
163      text: 'hello',
164      // Base64-encoded key.
165      key: 'NDM5Qjk2UjAzMEE0NzVCRjlFMkQwQkVGOFc1NkM1QkQ=',
166      transformation: 'AES/CBC/PKCS5Padding',
167      ivOffset: '0',
168      ivLen: '16',
169      success: function(data) {
170        console.log(`handling success:${data.text}`);
171        },
172      fail: function(data, code) {
173        console.log(`### cipher.rsa encrypt fail ### ${code}:${data}`);
174        },
175      complete: function() {
176        console.log(`operation complete!`);
177      }
178    });
179    cipher.aes({
180      // Decrypt data.
181      action: 'decrypt',
182      // Text to be decrypted, which is binary text encoded in Base64.
183      text: '1o0kf2HXwLxHkSh5W5NhzA==',
184       // Base64-encoded key.
185       key: 'NDM5Qjk2UjAzMEE0NzVCRjlFMkQwQkVGOFc1NkM1QkQ=',
186       transformation: 'AES/CBC/PKCS5Padding',
187       ivOffset: '0',
188       ivLen: '16',
189       success: function(data) {
190         console.log(`handling success:${data.text}`);
191        },
192       fail: function(data, code) {
193         console.log(`### cipher.aes encrypt fail ### ${code}:${data}`);
194       },
195       complete: function() {
196         console.log(`operation complete!`);
197        }
198     });
199  }
200}
201
202```
203