• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Encryption and Decryption with an AES Symmetric Key (GCM Mode)
2
3
4For details about the algorithm specifications, see [AES](crypto-sym-encrypt-decrypt-spec.md#aes).
5
6
7**Encryption**
8
9
101. Use [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 AES symmetric key (**SymKey**).
11
12   In addition to the example in this topic, [AES](crypto-sym-key-generation-conversion-spec.md#aes) and [Randomly Generating a Symmetric Key](crypto-generate-sym-key-randomly.md) 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.
13
142. Use [cryptoFramework.createCipher](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatecipher) 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**.
15
163. Use [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 **GcmParamsSpec** corresponding to the GCM mode.
17
184. Use [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be encrypted (plaintext).
19
20   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.
21
22   - If the data to be encrypted is short, you can use **doFinal** immediately after **init**.
23   - If the data to be encrypted is considerably long, you can call **update()** multiple times to [pass in the data by segment](crypto-aes-sym-encrypt-decrypt-gcm-by-segment.md).
24
255. Use [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the encrypted data.
26   - If data has been passed in by **update()**, pass in **null** in the **data** parameter of **Cipher.doFinal**.
27   - The output of **doFinal** may be **null**. To avoid exceptions, always check whether the result is **null** before accessing specific data.
28
296. Obtain [GcmParamsSpec.authTag](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#gcmparamsspec) as the authentication information for decryption.
30   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.
31
32
33**Decryption**
34
35
361. Use [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 **GcmParamsSpec** corresponding to the GCM mode.
37
382. Use [Cipher.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-1) to pass in the data to be decrypted (ciphertext).
39
403. Use [Cipher.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-1) to obtain the decrypted data.
41
42
43  ```ts
44  import cryptoFramework from '@ohos.security.cryptoFramework';
45  import buffer from '@ohos.buffer';
46
47  function genGcmParamsSpec() {
48    let arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]; // 12 bytes
49    let dataIv = new Uint8Array(arr);
50    let ivBlob: cryptoFramework.DataBlob = { data: dataIv };
51    arr = [0, 0, 0, 0, 0, 0, 0, 0]; // 8 bytes
52    let dataAad = new Uint8Array(arr);
53    let aadBlob: cryptoFramework.DataBlob = { data: dataAad };
54    arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]; // 16 bytes
55    let dataTag = new Uint8Array(arr);
56    let tagBlob: cryptoFramework.DataBlob = {
57      data: dataTag
58    };
59    // Obtain the GCM authTag from the doFinal result in encryption and fill it in the params parameter of init() in decryption.
60    let gcmParamsSpec: cryptoFramework.GcmParamsSpec = {
61      iv: ivBlob,
62      aad: aadBlob,
63      authTag: tagBlob,
64      algName: "GcmParamsSpec"
65    };
66    return gcmParamsSpec;
67  }
68
69  let gcmParams = genGcmParamsSpec();
70
71  // Encrypt the message.
72  async function encryptMessagePromise(symKey: cryptoFramework.SymKey, plainText: cryptoFramework.DataBlob) {
73    let cipher = cryptoFramework.createCipher('AES128|GCM|PKCS7');
74    await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams);
75    let encryptUpdate = await cipher.update(plainText);
76    // In GCM mode, pass in null in doFinal() in encryption. Obtain the tag data and fill it in the gcmParams object.
77    gcmParams.authTag = await cipher.doFinal(null);
78    return encryptUpdate;
79  }
80  // Decrypt the message.
81  async function decryptMessagePromise(symKey: cryptoFramework.SymKey, cipherText: cryptoFramework.DataBlob) {
82    let decoder = cryptoFramework.createCipher('AES128|GCM|PKCS7');
83    await decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, gcmParams);
84    let decryptUpdate = await decoder.update(cipherText);
85    // 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.
86    let decryptData = await decoder.doFinal(null);
87    if (decryptData == null) {
88      console.info('GCM decrypt success, decryptData is null');
89    }
90    return decryptUpdate;
91  }
92  async function genSymKeyByData(symKeyData: Uint8Array) {
93    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
94    let aesGenerator = cryptoFramework.createSymKeyGenerator('AES128');
95    let symKey = await aesGenerator.convertKey(symKeyBlob);
96    console.info('convertKey success');
97    return symKey;
98  }
99  async function main() {
100    let keyData = new Uint8Array([83, 217, 231, 76, 28, 113, 23, 219, 250, 71, 209, 210, 205, 97, 32, 159]);
101    let symKey = await genSymKeyByData(keyData);
102    let message = "This is a test";
103    let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
104    let encryptText = await encryptMessagePromise(symKey, plainText);
105    let decryptText = await decryptMessagePromise(symKey, encryptText);
106    if (plainText.data.toString() === decryptText.data.toString()) {
107      console.info('decrypt ok');
108      console.info('decrypt plainText: ' + buffer.from(decryptText.data).toString('utf-8'));
109    } else {
110      console.error('decrypt failed');
111    }
112  }
113  ```
114