harmony 鸿蒙Encryption and Decryption with an SM4 Symmetric Key (CBC Mode) (ArkTS)

2025-06-12
浏览 (4)

Encryption and Decryption with an SM4 Symmetric Key (CBC Mode) (ArkTS)

For details about the algorithm specifications, see SM4.

Encryption

Call cryptoFramework.createSymKeyGenerator and SymKeyGenerator.generateSymKey to generate a 128-bit SM4 symmetric key (SymKey).

In addition to the example in this topic, SM4 and Randomly Generating a Symmetric Key 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.

Call cryptoFramework.createCipher 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.
Call Cipher.init 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.
Call Cipher.update to pass in the data to be encrypted (plaintext).
- If a small amount of data is to be encrypted, you can use Cipher.doFinal immediately after Cipher.init.
- If a large amount of data is to be encrypted, you can call Cipher.update multiple times to pass in the data by segment.
Call Cipher.doFinal to obtain the encrypted data.
- If data has been passed in by Cipher.update, pass in null in the data parameter of Cipher.doFinal.
- The output of Cipher.doFinal may be null. To avoid exceptions, always check whether the result is null before accessing specific data.

Decryption

Call cryptoFramework.createCipher 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.
Call Cipher.init 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.
Call Cipher.update to pass in the data to be decrypted (ciphertext).
Call Cipher.doFinal to obtain the decrypted data.
Example (using asynchronous APIs):

  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
  import { buffer } from '@kit.ArkTS';

  function generateRandom(len: number) {
    let rand = cryptoFramework.createRandom();
    let generateRandSync = rand.generateRandomSync(len);
    return generateRandSync;
  }

  function genIvParamsSpec() {
    let ivBlob = generateRandom(16); // 16 bytes
    let ivParamsSpec: cryptoFramework.IvParamsSpec = {
      algName: "IvParamsSpec",
      iv: ivBlob
    };
    return ivParamsSpec;
  }
  let iv = genIvParamsSpec();
  // Encrypt the message.
  async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
    let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
    await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv);
    let encryptData = await cipher.doFinal(plainText);
    return encryptData;
  }
  // Decrypt the message.
  async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
    let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
    await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv);
    let decryptData = await decoder.doFinal(cipherText);
    return decryptData;
  }
  async function genSymKeyByData(symKeyData: Uint8Array) {
    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
    let symKey = await symGenerator.convertKey(symKeyBlob);
    console.info('convertKey success');
    return symKey;
  }
  async function main() {
    try {
      let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
      let symKey = await genSymKeyByData(keyData);
      let message = "This is a test";
      let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
      let encryptText = await encryptMessagePromise(symKey, plainText);
      let decryptText = await decryptMessagePromise(symKey, encryptText);
      if (plainText.data.toString() === decryptText.data.toString()) {
        console.info('decrypt ok');
        console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
      } else {
        console.error('decrypt failed');
      }
    } catch (error) {
      console.error(`SM4 "${error}", error code: ${error.code}`);
    }
  }

Example (using synchronous APIs):

  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
  import { buffer } from '@kit.ArkTS';

  function generateRandom(len: number) {
    let rand = cryptoFramework.createRandom();
    let generateRandSync = rand.generateRandomSync(len);
    return generateRandSync;
  }

  function genIvParamsSpec() {
    let ivBlob = generateRandom(16); // 16 bytes
    let ivParamsSpec: cryptoFramework.IvParamsSpec = {
      algName: "IvParamsSpec",
      iv: ivBlob
    };
    return ivParamsSpec;
  }
  let iv = genIvParamsSpec();
  // Encrypt the message.
  function encryptMessage(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
    let cipher = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
    cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv);
    let encryptData = cipher.doFinalSync(plainText);
    return encryptData;
  }
  // Decrypt the message.
  function decryptMessage(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
    let decoder = cryptoFramework.createCipher('SM4_128|CBC|PKCS7');
    decoder.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, iv);
    let decryptData = decoder.doFinalSync(cipherText);
    return decryptData;
  }
  function genSymKeyByData(symKeyData: Uint8Array) {
    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
    let symGenerator = cryptoFramework.createSymKeyGenerator('SM4_128');
    let symKey = symGenerator.convertKeySync(symKeyBlob);
    console.info('convertKeySync success');
    return symKey;
  }
  function main() {
    try {
      let keyData = new Uint8Array([7, 154, 52, 176, 4, 236, 150, 43, 237, 9, 145, 166, 141, 174, 224, 131]);
      let symKey = genSymKeyByData(keyData);
      let message = "This is a test";
      let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
      let encryptText = encryptMessage(symKey, plainText);
      let decryptText = decryptMessage(symKey, encryptText);
      if (plainText.data.toString() === decryptText.data.toString()) {
        console.info('decrypt ok');
        console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
      } else {
        console.error('decrypt failed');
      }
    } catch (error) {
      console.error(`SM4 "${error}", error code: ${error.code}`);
    }
  }