1# Encryption and Decryption with an SM4 Symmetric Key (CBC 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|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**. 19 203. 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. 21 224. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be encrypted (plaintext). 23 24 - If a small amount of data is to be encrypted, you can use **Cipher.doFinal** immediately after **Cipher.init**. 25 - If a large amount of data is to be encrypted, you can call **Cipher.update** multiple times to pass in the data by segment. 26 275. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the encrypted data. 28 29 - If data has been passed in by **Cipher.update**, pass in **null** in the **data** parameter of **Cipher.doFinal**. 30 - The output of **Cipher.doFinal** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data. 31 32**Decryption** 33 341. 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**. 35 362. 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. 37 383. Call [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be decrypted (ciphertext). 39 404. Call [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the decrypted data. 41 42- Example (using asynchronous APIs): 43 44 ```ts 45 import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 46 import { buffer } from '@kit.ArkTS'; 47 48 function generateRandom(len: number) { 49 let rand = cryptoFramework.createRandom(); 50 let generateRandSync = rand.generateRandomSync(len); 51 return generateRandSync; 52 } 53 54 function genIvParamsSpec() { 55 let ivBlob = generateRandom(16); // 16 bytes 56 let ivParamsSpec: cryptoFramework.IvParamsSpec = { 57 algName: "IvParamsSpec", 58 iv: ivBlob 59 }; 60 return ivParamsSpec; 61 } 62 let iv = genIvParamsSpec(); 63 // Encrypt the message. 64 async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) { 65 let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7'); 66 await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv); 67 let encryptData = await cipher.doFinal(plainText); 68 return encryptData; 69 } 70 // Decrypt the message. 71 async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) { 72 let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7'); 73 await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv); 74 let decryptData = await decoder.doFinal(cipherText); 75 return decryptData; 76 } 77 async function genSymKeyByData(symKeyData: Uint8Array) { 78 let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData }; 79 let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128'); 80 let symKey = await symGenerator.convertKey(symKeyBlob); 81 console.info('convertKey success'); 82 return symKey; 83 } 84 async function main() { 85 try { 86 let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]); 87 let symKey = await genSymKeyByData(keyData); 88 let message = "This is a test"; 89 let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) }; 90 let encryptText = await encryptMessagePromise(symKey, plainText); 91 let decryptText = await decryptMessagePromise(symKey, encryptText); 92 if (plainText.data.toString() === decryptText.data.toString()) { 93 console.info('decrypt ok'); 94 console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8')); 95 } else { 96 console.error('decrypt failed'); 97 } 98 } catch (error) { 99 console.error(`SM4 "${error}", error code: ${error.code}`); 100 } 101 } 102 ``` 103 104- Example (using synchronous APIs): 105 106 ```ts 107 import { cryptoFramework } from '@kit.CryptoArchitectureKit'; 108 import { buffer } from '@kit.ArkTS'; 109 110 function generateRandom(len: number) { 111 let rand = cryptoFramework.createRandom(); 112 let generateRandSync = rand.generateRandomSync(len); 113 return generateRandSync; 114 } 115 116 function genIvParamsSpec() { 117 let ivBlob = generateRandom(16); // 16 bytes 118 let ivParamsSpec: cryptoFramework.IvParamsSpec = { 119 algName: "IvParamsSpec", 120 iv: ivBlob 121 }; 122 return ivParamsSpec; 123 } 124 let iv = genIvParamsSpec(); 125 // Encrypt the message. 126 function encryptMessage(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) { 127 let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7'); 128 cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv); 129 let encryptData = cipher.doFinalSync(plainText); 130 return encryptData; 131 } 132 // Decrypt the message. 133 function decryptMessage(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) { 134 let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7'); 135 decoder.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv); 136 let decryptData = decoder.doFinalSync(cipherText); 137 return decryptData; 138 } 139 function genSymKeyByData(symKeyData: Uint8Array) { 140 let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData }; 141 let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128'); 142 let symKey = symGenerator.convertKeySync(symKeyBlob); 143 console.info('convertKeySync success'); 144 return symKey; 145 } 146 function main() { 147 try { 148 let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]); 149 let symKey = genSymKeyByData(keyData); 150 let message = "This is a test"; 151 let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) }; 152 let encryptText = encryptMessage(symKey, plainText); 153 let decryptText = decryptMessage(symKey, encryptText); 154 if (plainText.data.toString() === decryptText.data.toString()) { 155 console.info('decrypt ok'); 156 console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8')); 157 } else { 158 console.error('decrypt failed'); 159 } 160 } catch (error) { 161 console.error(`SM4 "${error}", error code: ${error.code}`); 162 } 163 } 164 ``` 165