• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Encryption and Decryption with an SM4 Symmetric Key (ECB Mode) (ArkTS)
2
3<!--Kit: Crypto Architecture Kit-->
4<!--Subsystem: Security-->
5<!--Owner: @zxz--3-->
6<!--Designer: @lanming-->
7<!--Tester: @PAFT-->
8<!--Adviser: @zengyawen-->
9
10For details about the algorithm specifications, see [SM4](crypto-sym-encrypt-decrypt-spec.md#sm4).
11
12**Encryption**
13
141. 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**).
15
16   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.
17
182. Call [cryptoFramework.createCipher](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatecipher) with the string parameter **'SM4_128|ECB|PKCS7'** to create a **Cipher** instance for encryption. The key type is **SM4_128**, block cipher mode is **ECB**, and the padding mode is **PKCS7**.
19
203. Call [Cipher.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-1) to initialize the **Cipher** instance. In **Cipher.init**, set **opMode** to **CryptoMode.ENCRYPT_MODE** (encryption) and **key** to **SymKey** (the key used for encryption).
21
22   When ECB mode is used, pass in **null** in **params**.
23
244. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be encrypted (plaintext).
25
26   - If a small amount of data is to be encrypted, you can use **Cipher.doFinal** immediately after **Cipher.init**.
27   - If a large amount of data is to be encrypted, you can call **Cipher.update** multiple times to pass in the data by segment.
28
295. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the encrypted data.
30
31   - If data has been passed in by **Cipher.update**, pass in **null** in the **data** parameter of **Cipher.doFinal**.
32   - The output of **Cipher.doFinal** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data.
33
34**Decryption**
35
361. Call [cryptoFramework.createCipher](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatecipher) with the string parameter **'SM4_128|ECB|PKCS7'** to create a **Cipher** instance for decryption. The key type is **SM4_128**, block cipher mode is **ECB**, and the padding mode is **PKCS7**.
37
382. Call [Cipher.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-1) to initialize the **Cipher** instance. In **Cipher.init**, set **opMode** to **CryptoMode.DECRYPT_MODE** (decryption) and **key** to **SymKey** (the key used for decryption). When ECB mode is used, pass in **null** in **params**.
39
403. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be decrypted (ciphertext).
41
424. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the decrypted data.
43
44- Example (using asynchronous APIs):
45
46  ```ts
47  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
48  import { buffer } from '@kit.ArkTS';
49
50  // Encrypt the message.
51  async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
52    let cipher = cryptoFramework.createCipher('SM4_128|ECB|PKCS7');
53    await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null);
54    let encryptData = await cipher.doFinal(plainText);
55    return encryptData;
56  }
57  // Decrypt the message.
58  async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
59    let decoder = cryptoFramework.createCipher('SM4_128|ECB|PKCS7');
60    await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, null);
61    let decryptData = await decoder.doFinal(cipherText);
62    return decryptData;
63  }
64  async function genSymKeyByData(symKeyData: Uint8Array) {
65    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
66    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
67    let symKey = await symGenerator.convertKey(symKeyBlob);
68    console.info('convertKey success');
69    return symKey;
70  }
71  async function main() {
72    let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
73    let symKey = await genSymKeyByData(keyData);
74    let message = "This is a test";
75    let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
76    let encryptText = await encryptMessagePromise(symKey, plainText);
77    let decryptText = await decryptMessagePromise(symKey, encryptText);
78    if (plainText.data.toString() === decryptText.data.toString()) {
79      console.info('decrypt ok');
80      console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
81    } else {
82      console.error('decrypt failed');
83    }
84  }
85  ```
86
87- Example (using synchronous APIs):
88
89  ```ts
90  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
91  import { buffer } from '@kit.ArkTS';
92
93  // Encrypt the message.
94  function encryptMessage(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
95    let cipher = cryptoFramework.createCipher('SM4_128|ECB|PKCS7');
96    cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null);
97    let encryptData = cipher.doFinalSync(plainText);
98    return encryptData;
99  }
100  // Decrypt the message.
101  function decryptMessage(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
102    let decoder = cryptoFramework.createCipher('SM4_128|ECB|PKCS7');
103    decoder.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, null);
104    let decryptData = decoder.doFinalSync(cipherText);
105    return decryptData;
106  }
107  function genSymKeyByData(symKeyData: Uint8Array) {
108    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
109    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
110    let symKey = symGenerator.convertKeySync(symKeyBlob);
111    console.info('convertKeySync success');
112    return symKey;
113  }
114  function main() {
115    let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
116    let symKey = genSymKeyByData(keyData);
117    let message = "This is a test";
118    let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
119    let encryptText = encryptMessage(symKey, plainText);
120    let decryptText = decryptMessage(symKey, encryptText);
121    if (plainText.data.toString() === decryptText.data.toString()) {
122      console.info('decrypt ok');
123      console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
124    } else {
125      console.error('decrypt failed');
126    }
127  }
128  ```
129