We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
GuidesSystemSecurityCrypto Architecture KitEncryption and DecryptionEncryption and Decryption DevelopmentEncryption and Decryption Using ECIES (ArkTS)

Encryption and Decryption Using ECIES (ArkTS)

Last updated: 2026-09-08 08:15
Content overview

The ECIES algorithm is supported since API version 26.0.0. It is an encryption algorithm based on elliptic curve cryptography.

Constraints

  • Key agreement algorithms ECC256, ECC384, and ECC521 are supported.
  • Among key derivation algorithms, only X963KDF is supported. Digest algorithms SHA-1, SHA-256, SHA-384, and SHA-512 are supported.
  • Symmetric encryption algorithms AES-128, AES-192, and AES-256 are supported.
  • Among block cipher modes, only GCM is supported.

Development Procedure

Encryption

  1. Call cryptoFramework.createAsyKeyGenerator and SymKeyGenerator.generateKeyPair to generate a key pair using the ECC algorithm.

  2. Call cryptoFramework.createKeyAgreement and KeyAgreement.generateSecret to perform key agreement based on the local private key (KeyPair.priKey) and peer public key (KeyPair.pubKey) and return the shared key.

  3. Call cryptoFramework.createKdf and Kdf.generateSecret to derive a key based on the shared key (Secret) using the X963KDF algorithm and return the derived key.

  4. Call cryptoFramework.createCipher with the string parameter 'AES128|GCM' to create a Cipher instance for encryption. The key type is AES-128, and the block cipher mode is GCM.

  5. Call Cipher.init to initialize the Cipher instance. Specifically, set the mode to cryptoFramework.CryptoMode.ENCRYPT_MODE (encryption), key to SymKey (the key for encryption), and parameter to GcmParamsSpec corresponding to the GCM mode.

  6. Call Cipher.update to pass the data to be encrypted (plaintext).

  7. Call Cipher.doFinal to obtain the encrypted data.

  8. Obtain GcmParamsSpec.authTag as the authentication information for decryption.

Decryption

  1. Call cryptoFramework.createAsyKeyGenerator and SymKeyGenerator.generateKeyPair to generate a key pair using the ECC algorithm.

  2. Call cryptoFramework.createKeyAgreement and KeyAgreement.generateSecret to perform key agreement based on the local private key (KeyPair.priKey) and peer public key (KeyPair.pubKey) and return the shared key.

  3. Call cryptoFramework.createKdf and Kdf.generateSecret to derive a key based on the shared key (Secret) using the X963KDF algorithm and return the derived key.

  4. Call cryptoFramework.createCipher with the string parameter 'AES128|GCM' to create a Cipher instance for decryption. The key type is AES-128, and the block cipher mode is GCM.

  5. Call Cipher.init to initialize the Cipher instance. Specifically, set the mode to cryptoFramework.CryptoMode.DECRYPT_MODE (decryption), key to SymKey (the key for decryption), and parameter to GcmParamsSpec corresponding to the GCM mode.

  6. Call Cipher.update to pass the data to be decrypted (ciphertext).

  7. Call Cipher.doFinal to obtain the decrypted data.

Example Code

  • Example (using asynchronous APIs):

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. import { cryptoFramework } from '@kit.CryptoArchitectureKit';
    2. import { buffer } from '@kit.ArkTS';
    3. 

    4. namespace ECIES {
    5.   function generateGcmParamsSpec(ivData: Uint8Array): cryptoFramework.GcmParamsSpec {
    6.     let ivBlob: cryptoFramework.DataBlob = {
    7.       data: ivData,
    8.     };
    9.     let rand: cryptoFramework.Random = cryptoFramework.createRandom();
    10.     let aadBlob: cryptoFramework.DataBlob = rand.generateRandomSync(8);
    11.     let tagBlob: cryptoFramework.DataBlob = rand.generateRandomSync(16);
    12.     // Obtain the GCM authTag from the Cipher.doFinal result in encryption and fill it in the params parameter of Cipher.init in decryption.
    13.     let gcmParams: cryptoFramework.GcmParamsSpec = {
    14.       iv: ivBlob,
    15.       aad: aadBlob,
    16.       authTag: tagBlob,
    17.       algName: 'GcmParamsSpec',
    18.     };
    19.     return gcmParams;
    20.   }
    21. 

    22.   async function generateSecret(priKey: cryptoFramework.PriKey, pubKey: cryptoFramework.PubKey):
    23.     Promise<cryptoFramework.DataBlob> {
    24.     // EC key agreement.
    25.     let agreement: cryptoFramework.KeyAgreement = cryptoFramework.createKeyAgreement('ECC256');
    26.     let keyData: cryptoFramework.DataBlob = await agreement.generateSecret(priKey, pubKey);
    27. 

    28.     let infoData: Uint8Array = new Uint8Array(buffer.from('infostring', 'utf-8').buffer);
    29.     let spec: cryptoFramework.X963KdfSpec = {
    30.       algName: 'X963KDF',
    31.       key: keyData.data,
    32.       info: infoData,
    33.       keySize: 32, // The first 16 bytes are used as the IV of AES-128, and the last 16 bytes are used as the key.
    34.     };
    35. 

    36.     // Derive the key using X963KDF.
    37.     let kdf = cryptoFramework.createKdf('X963KDF|SHA256');
    38.     let secret = await kdf.generateSecret(spec);
    39.     return secret;
    40.   }
    41. 

    42.   async function generateSymKey(secret: cryptoFramework.DataBlob): Promise<cryptoFramework.SymKey> {
    43.     let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES128');
    44.     let keyData: cryptoFramework.DataBlob = {
    45.       data: secret.data.slice(16),
    46.     };
    47.     let symKey: cryptoFramework.SymKey = await symKeyGenerator.convertKey(keyData);
    48.     return symKey;
    49.   }
    50. 

    51.   async function encrypt(symKey: cryptoFramework.SymKey, gcmParams: cryptoFramework.GcmParamsSpec,
    52.     plainText: cryptoFramework.DataBlob): Promise<cryptoFramework.DataBlob> {
    53.     // AES-GCM symmetric encryption
    54.     let cipher: cryptoFramework.Cipher = cryptoFramework.createCipher('AES128|GCM');
    55.     await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams);
    56.     let cipherText: cryptoFramework.DataBlob = await cipher.update(plainText);
    57.     gcmParams.authTag = await cipher.doFinal(null);
    58.     return cipherText;
    59.   }
    60. 

    61.   async function decrypt(symKey: cryptoFramework.SymKey, gcmParams: cryptoFramework.GcmParamsSpec,
    62.     cipherText: cryptoFramework.DataBlob): Promise<cryptoFramework.DataBlob> {
    63.     // AES-GCM symmetric decryption.
    64.     let cipher: cryptoFramework.Cipher = cryptoFramework.createCipher('AES128|GCM');
    65.     await cipher.init(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, gcmParams);
    66.     let plainText: cryptoFramework.DataBlob = await cipher.doFinal(cipherText);
    67.     return plainText;
    68.   }
    69. 

    70.   export async function doEciesTest(): Promise<string> {
    71.     try {
    72.       // Generate EC key pairs for ends A and B.
    73.       let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
    74.       let keyPairA: cryptoFramework.KeyPair = asyKeyGenerator.generateKeyPairSync();
    75.       let keyPairB: cryptoFramework.KeyPair = asyKeyGenerator.generateKeyPairSync();
    76. 

    77.       // Encryption at end A: private key of end A + public key of end B
    78.       let secretA: cryptoFramework.DataBlob = await generateSecret(keyPairA.priKey, keyPairB.pubKey);
    79.       let symKeyA: cryptoFramework.SymKey = await generateSymKey(secretA);
    80.       let ivData: Uint8Array = secretA.data.slice(0, 16);
    81.       let gcmParams: cryptoFramework.GcmParamsSpec = generateGcmParamsSpec(ivData);
    82. 

    83.       let message: string = 'This is a test message!!!';
    84.       let plainText: cryptoFramework.DataBlob = {
    85.         data: new Uint8Array(buffer.from(message, 'utf-8').buffer),
    86.       };
    87.       let cipherData: cryptoFramework.DataBlob = await encrypt(symKeyA, gcmParams, plainText);
    88. 

    89.       // Decryption at end B: private key of end B + public key of end A
    90.       let secretB: cryptoFramework.DataBlob = await generateSecret(keyPairB.priKey, keyPairA.pubKey);
    91.       let symKeyB: cryptoFramework.SymKey = await generateSymKey(secretB);
    92.       let plainData: cryptoFramework.DataBlob = await decrypt(symKeyB, gcmParams, cipherData);
    93.       console.info('doEciesTest success, message: ' + buffer.from(plainData.data).toString('utf-8'));
    94.       return 'Success';
    95.     } catch (error) {
    96.       console.error(`doEciesTest failed, error: + ${JSON.stringify(error)}`);
    97.       return 'Failed';
    98.     }
    99.   }
    100. }
    Await.ets

  • Example (using synchronous APIs):

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. import { cryptoFramework } from '@kit.CryptoArchitectureKit';
    2. import { buffer } from '@kit.ArkTS';
    3. 

    4. namespace ECIES {
    5.   function generateGcmParamsSpec(ivData: Uint8Array): cryptoFramework.GcmParamsSpec {
    6.     let ivBlob: cryptoFramework.DataBlob = {
    7.       data: ivData,
    8.     };
    9.     let rand: cryptoFramework.Random = cryptoFramework.createRandom();
    10.     let aadBlob: cryptoFramework.DataBlob = rand.generateRandomSync(8);
    11.     let tagBlob: cryptoFramework.DataBlob = rand.generateRandomSync(16);
    12.     // Obtain the GCM authTag from the Cipher.doFinal result in encryption and fill it in the params parameter of Cipher.init in decryption.
    13.     let gcmParams: cryptoFramework.GcmParamsSpec = {
    14.       iv: ivBlob,
    15.       aad: aadBlob,
    16.       authTag: tagBlob,
    17.       algName: 'GcmParamsSpec',
    18.     };
    19.     return gcmParams;
    20.   }
    21. 

    22.   function generateSecret(priKey: cryptoFramework.PriKey, pubKey: cryptoFramework.PubKey):
    23.     cryptoFramework.DataBlob {
    24.     // EC key agreement.
    25.     let agreement: cryptoFramework.KeyAgreement = cryptoFramework.createKeyAgreement('ECC256');
    26.     let keyData: cryptoFramework.DataBlob = agreement.generateSecretSync(priKey, pubKey);
    27. 

    28.     let infoData: Uint8Array = new Uint8Array(buffer.from('infostring', 'utf-8').buffer);
    29.     let spec: cryptoFramework.X963KdfSpec = {
    30.       algName: 'X963KDF',
    31.       key: keyData.data,
    32.       info: infoData,
    33.       keySize: 32, // The first 16 bytes are used as the IV of AES-128, and the last 16 bytes are used as the key.
    34.     };
    35. 

    36.     // Derive the key using X963KDF.
    37.     let kdf = cryptoFramework.createKdf('X963KDF|SHA256');
    38.     let secret = kdf.generateSecretSync(spec);
    39.     return secret;
    40.   }
    41. 

    42.   function generateSymKey(secret: cryptoFramework.DataBlob): cryptoFramework.SymKey {
    43.     let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES128');
    44.     let keyData: cryptoFramework.DataBlob = {
    45.       data: secret.data.slice(16),
    46.     };
    47.     let symKey: cryptoFramework.SymKey = symKeyGenerator.convertKeySync(keyData);
    48.     return symKey;
    49.   }
    50. 

    51.   function encrypt(symKey: cryptoFramework.SymKey, gcmParams: cryptoFramework.GcmParamsSpec,
    52.     plainText: cryptoFramework.DataBlob): cryptoFramework.DataBlob {
    53.     // AES-GCM symmetric encryption
    54.     let cipher: cryptoFramework.Cipher = cryptoFramework.createCipher('AES128|GCM');
    55.     cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams);
    56.     let cipherText: cryptoFramework.DataBlob = cipher.updateSync(plainText);
    57.     gcmParams.authTag = cipher.doFinalSync(null);
    58.     return cipherText;
    59.   }
    60. 

    61.   function decrypt(symKey: cryptoFramework.SymKey, gcmParams: cryptoFramework.GcmParamsSpec,
    62.     cipherText: cryptoFramework.DataBlob): cryptoFramework.DataBlob {
    63.     // AES-GCM symmetric decryption.
    64.     let cipher: cryptoFramework.Cipher = cryptoFramework.createCipher('AES128|GCM');
    65.     cipher.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE, symKey, gcmParams);
    66.     let plainText: cryptoFramework.DataBlob = cipher.doFinalSync(cipherText);
    67.     return plainText;
    68.   }
    69. 

    70.   export function doEciesTest(): string {
    71.     try {
    72.       // Generate EC key pairs for ends A and B.
    73.       let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
    74.       let keyPairA: cryptoFramework.KeyPair = asyKeyGenerator.generateKeyPairSync();
    75.       let keyPairB: cryptoFramework.KeyPair = asyKeyGenerator.generateKeyPairSync();
    76. 

    77.       // Encryption at end A: private key of end A + public key of end B
    78.       let secretA: cryptoFramework.DataBlob = generateSecret(keyPairA.priKey, keyPairB.pubKey);
    79.       let symKeyA: cryptoFramework.SymKey = generateSymKey(secretA);
    80.       let ivData: Uint8Array = secretA.data.slice(0, 16);
    81.       let gcmParams: cryptoFramework.GcmParamsSpec = generateGcmParamsSpec(ivData);
    82. 

    83.       let message: string = 'This is a test message!!!';
    84.       let plainText: cryptoFramework.DataBlob = {
    85.         data: new Uint8Array(buffer.from(message, 'utf-8').buffer),
    86.       };
    87.       let cipherData: cryptoFramework.DataBlob = encrypt(symKeyA, gcmParams, plainText);
    88. 

    89.       // Decryption at end B: private key of end B + public key of end A
    90.       let secretB: cryptoFramework.DataBlob = generateSecret(keyPairB.priKey, keyPairA.pubKey);
    91.       let symKeyB: cryptoFramework.SymKey = generateSymKey(secretB);
    92.       let plainData: cryptoFramework.DataBlob = decrypt(symKeyB, gcmParams, cipherData);
    93.       console.info('doEciesTest success, message: ' + buffer.from(plainData.data).toString('utf-8'));
    94.       return 'Success';
    95.     } catch (error) {
    96.       console.error(`doEciesTest failed, error: + ${JSON.stringify(error)}`);
    97.       return 'Failed';
    98.     }
    99.   }
    100. }
    Sync.ets
Encryption and Decryption with an RC4 Symmetric Key (ArkTS)
Encryption and Decryption Using ECIES (C/C++)
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.