Encryption and Decryption with an AES Symmetric Key (GCM Mode)

For details about the algorithm specifications, see AES.

Encryption

1. Use cryptoFramework.createSymKeyGenerator and SymKeyGenerator.generateSymKey to generate a 128-bit AES symmetric key (SymKey).

   In addition to the example in this topic, AES and Randomly Generating a Symmetric Key may help you better understand how to generate an AES symmetric key. Note that the input parameters in the reference documents may be different from those in the example below.

2. Use cryptoFramework.createCipher with the string parameter 'AES128|GCM|PKCS7' to create a Cipher instance. The key type is AES128, block cipher mode is GCM, and the padding mode is PKCS7.

3. Use 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 GcmParamsSpec corresponding to the GCM mode.

4. Use Cipher.update to pass in the data to be encrypted (plaintext).

   Currently, the data to be passed in by a single update() is not size bound. You can determine how to pass in data based on the data volume.

   • If the data to be encrypted is short, you can use doFinal immediately after init.
   • If the data to be encrypted is considerably long, you can call update() multiple times to pass in the data by segment.

5. Use Cipher.doFinal to obtain the encrypted data.

   • If data has been passed in by update(), pass in null in the data parameter of Cipher.doFinal.
   • The output of doFinal may be null. To avoid exceptions, always check whether the result is null before accessing specific data.

6. Obtain GcmParamsSpec.authTag as the authentication information for decryption. In GCM mode, extract the last 16 bytes from the encrypted data as the authentication information for initializing the Cipher instance in decryption. In the example, authTag is of 16 bytes.

Decryption

1. Use 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 GcmParamsSpec corresponding to the GCM mode.

2. Use Cipher.update to pass in the data to be decrypted (ciphertext).

3. Use Cipher.doFinal to obtain the decrypted data.

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

function genGcmParamsSpec() {
  let arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]; // 12 bytes
  let dataIv = new Uint8Array(arr);
  let ivBlob: cryptoFramework.DataBlob = { data: dataIv };
  arr = [0, 0, 0, 0, 0, 0, 0, 0]; // 8 bytes
  let dataAad = new Uint8Array(arr);
  let aadBlob: cryptoFramework.DataBlob = { data: dataAad };
  arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]; // 16 bytes
  let dataTag = new Uint8Array(arr);
  let tagBlob: cryptoFramework.DataBlob = {
    data: dataTag
  }; 
  // Obtain the GCM authTag from the doFinal result in encryption and fill it in the params parameter of init() in decryption.
  let gcmParamsSpec: cryptoFramework.GcmParamsSpec = {
    iv: ivBlob,
    aad: aadBlob,
    authTag: tagBlob,
    algName: "GcmParamsSpec"
  };
  return gcmParamsSpec;
}

let gcmParams = genGcmParamsSpec();

// Encrypt the message.
async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
  let cipher = cryptoFramework.createCipher('AES128|GCM|PKCS7');
  await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams);
  let encryptUpdate = await cipher.update(plainText);
  // In GCM mode, pass in null in doFinal() in encryption. Obtain the tag data and fill it in the gcmParams object.
  gcmParams.authTag = await cipher.doFinal(null);
  return encryptUpdate;
}
// Decrypt the message.
async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
  let decoder = cryptoFramework.createCipher('AES128|GCM|PKCS7');
  await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, gcmParams);
  let decryptUpdate = await decoder.update(cipherText);
  // In GCM mode, pass in null in doFinal() in decryption. Verify the tag data passed in **init**. If the verification fails, an exception will be thrown.
  let decryptData = await decoder.doFinal(null);
  if (decryptData == null) {
    console.info('GCM decrypt success, decryptData is null');
  }
  return decryptUpdate;
}
async function genSymKeyByData(symKeyData: Uint8Array) {
  let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
  let aesGenerator = cryptoFramework.createSymKeyGenerator('AES128');
  let symKey = await aesGenerator.convertKey(symKeyBlob);
  console.info('convertKey success');
  return symKey;
}
async function main() {
  let keyData = new Uint8Array([83, 217, 231, 76, 28, 113, 23, 219, 250, 71, 209, 210, 205, 97, 32, 159]);
  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');
  }
}