• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Encryption and Decryption with an SM4 Symmetric Key (CBC Mode) (ArkTS)
2
3
4For details about the algorithm specifications, see [SM4](crypto-sym-encrypt-decrypt-spec.md#sm4).
5
6**Encryption**
7
8
91. Call [cryptoFramework.createSymKeyGenerator](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatesymkeygenerator) and [SymKeyGenerator.generateSymKey](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#generatesymkey-1) to generate a 128-bit SM4 symmetric key (**SymKey**).
10
11   In addition to the example in this topic, [SM4](crypto-sym-key-generation-conversion-spec.md#sm4) and [Randomly Generating a Symmetric Key](crypto-generate-sym-key-randomly.md) may help you better understand how to generate an SM4 symmetric key. Note that the input parameters in the reference documents may be different from those in the example below.
12
132. Call [cryptoFramework.createCipher](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatecipher) with the string parameter **'SM4_128|CBC|PKCS7'** to create a **Cipher** instance for encryption. The key type is **SM4_128**, block cipher mode is **CBC**, and the padding mode is **PKCS7**.
14
153. Call [Cipher.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-1) to initialize the **Cipher** instance. In the **Cipher.init** API, set **opMode** to **CryptoMode.ENCRYPT_MODE** (encryption), **key** to **SymKey** (the key for encryption), and **params** to **IvParamsSpec** corresponding to the CBC mode.
16
174. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be encrypted (plaintext).
18
19   - If a small amount of data is to be encrypted, you can use **Cipher.doFinal** immediately after **Cipher.init**.
20   - If a large amount of data is to be encrypted, you can call **Cipher.update** multiple times to pass in the data by segment.
21
225. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the encrypted data.
23
24   - If data has been passed in by **Cipher.update**, pass in **null** in the **data** parameter of **Cipher.doFinal**.
25   - The output of **Cipher.doFinal** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data.
26
27
28**Decryption**
29
301. Call [cryptoFramework.createCipher](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatecipher) with the string parameter **'SM4_128|CBC|PKCS7'** to create a **Cipher** instance for decryption. The key type is **SM4_128**, block cipher mode is **CBC**, and the padding mode is **PKCS7**.
31
322. Call [Cipher.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-1) to initialize the **Cipher** instance. In the **Cipher.init** API, set **opMode** to **CryptoMode.DECRYPT_MODE** (decryption), **key** to **SymKey** (the key for decryption), and **params** to **IvParamsSpec** corresponding to the CBC mode.
33
343. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be decrypted (ciphertext).
35
364. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the decrypted data.
37
38
39- Example (using asynchronous APIs):
40
41  ```ts
42  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
43  import { buffer } from '@kit.ArkTS';
44
45  function generateRandom(len: number) {
46    let rand = cryptoFramework.createRandom();
47    let generateRandSync = rand.generateRandomSync(len);
48    return generateRandSync;
49  }
50
51  function genIvParamsSpec() {
52    let ivBlob = generateRandom(16); // 16 bytes
53    let ivParamsSpec: cryptoFramework.IvParamsSpec = {
54      algName: "IvParamsSpec",
55      iv: ivBlob
56    };
57    return ivParamsSpec;
58  }
59  let iv = genIvParamsSpec();
60  // Encrypt the message.
61  async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
62    let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
63    await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv);
64    let encryptData = await cipher.doFinal(plainText);
65    return encryptData;
66  }
67  // Decrypt the message.
68  async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
69    let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
70    await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv);
71    let decryptData = await decoder.doFinal(cipherText);
72    return decryptData;
73  }
74  async function genSymKeyByData(symKeyData: Uint8Array) {
75    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
76    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
77    let symKey = await symGenerator.convertKey(symKeyBlob);
78    console.info('convertKey success');
79    return symKey;
80  }
81  async function main() {
82    try {
83      let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
84      let symKey = await genSymKeyByData(keyData);
85      let message = "This is a test";
86      let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
87      let encryptText = await encryptMessagePromise(symKey, plainText);
88      let decryptText = await decryptMessagePromise(symKey, encryptText);
89      if (plainText.data.toString() === decryptText.data.toString()) {
90        console.info('decrypt ok');
91        console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
92      } else {
93        console.error('decrypt failed');
94      }
95    } catch (error) {
96      console.error(`SM4 "${error}", error code: ${error.code}`);
97    }
98  }
99  ```
100
101- Example (using synchronous APIs):
102
103  ```ts
104  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
105  import { buffer } from '@kit.ArkTS';
106
107  function generateRandom(len: number) {
108    let rand = cryptoFramework.createRandom();
109    let generateRandSync = rand.generateRandomSync(len);
110    return generateRandSync;
111  }
112
113  function genIvParamsSpec() {
114    let ivBlob = generateRandom(16); // 16 bytes
115    let ivParamsSpec: cryptoFramework.IvParamsSpec = {
116      algName: "IvParamsSpec",
117      iv: ivBlob
118    };
119    return ivParamsSpec;
120  }
121  let iv = genIvParamsSpec();
122  // Encrypt the message.
123  function encryptMessage(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
124    let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
125    cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv);
126    let encryptData = cipher.doFinalSync(plainText);
127    return encryptData;
128  }
129  // Decrypt the message.
130  function decryptMessage(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
131    let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
132    decoder.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv);
133    let decryptData = decoder.doFinalSync(cipherText);
134    return decryptData;
135  }
136  function genSymKeyByData(symKeyData: Uint8Array) {
137    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
138    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
139    let symKey = symGenerator.convertKeySync(symKeyBlob);
140    console.info('convertKeySync success');
141    return symKey;
142  }
143  function main() {
144    try {
145      let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
146      let symKey = genSymKeyByData(keyData);
147      let message = "This is a test";
148      let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
149      let encryptText = encryptMessage(symKey, plainText);
150      let decryptText = decryptMessage(symKey, encryptText);
151      if (plainText.data.toString() === decryptText.data.toString()) {
152        console.info('decrypt ok');
153        console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
154      } else {
155        console.error('decrypt failed');
156      }
157    } catch (error) {
158      console.error(`SM4 "${error}", error code: ${error.code}`);
159    }
160  }
161  ```
162