1# Converting Binary Data into a Symmetric Key (ArkTS)
2
3
4This topic uses 3DES and HMAC as an example to describe how to convert binary data into a symmetric key (**SymKey**). That is, convert a piece of external or internal binary data into a key object for subsequent operations, such as encryption and decryption.
5
6
7## Converting Binary Data into a 3DES Key
8
9For details about the algorithm specifications, see [3DES](crypto-sym-key-generation-conversion-spec.md#3des).
10
111. Obtain the 3DES key binary data and encapsulate it into a **DataBlob** object.
12
132. Use [cryptoFramework.createSymKeyGenerator](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatesymkeygenerator) with the string parameter **'3DES192'** to create a symmetric key generator (**SymKeyGenerator**) object for a 192-bit 3DES key.
14
153. Use [SymKeyGenerator.convertKey](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkey-1) to convert the binary data into a symmetric key (**SymKey**).
16
174. Use [SymKey.getEncoded](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#getencoded) to obtain the binary data of the key.
18
19- Example: Convert binary data into a 192-bit 3DES key (using callback-based APIs).
20
21  ```ts
22  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
23  import { BusinessError } from '@kit.BasicServicesKit';
24
25  function genKeyMaterialBlob(): cryptoFramework.DataBlob {
26    let arr = [
27      0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
28      0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
29      0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // The key length is 192 bits, that is, 24 bytes.
30    let keyMaterial = new Uint8Array(arr);
31    return { data: keyMaterial };
32  }
33
34  function testConvertSymKey() {
35    // Create a SymKeyGenerator instance.
36    let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
37    // Convert the data into a symmetric key.
38    let keyMaterialBlob = genKeyMaterialBlob();
39    try {
40      symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => {
41        if (error) {// If the service logic fails to be executed, the first parameter of the callback returns error information, that is, throw an exception asynchronously.
42          let e: BusinessError = error as BusinessError;
43          console.error(`convertKey error, ${e.code}, ${e.message}`);
44          return;
45        }
46        console.info('key algName: ' + key.algName);
47        console.info('key format: ' + key.format);
48        let encodedKey = key.getEncoded(); // Obtain the binary data of the symmetric key and output the data as a byte array. The length is 24 bytes.
49        console.info('key getEncoded hex: ' + encodedKey.data);
50      })
51    } catch (error) {// Throw an exception immediately when an error is detected during parameter check.
52      let e: BusinessError = error as BusinessError;
53      console.error(`convertKey failed, ${e.code}, ${e.message}`);
54    }
55  }
56  ```
57
58- Example using synchronous API [convertKeySync](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkeysync12):
59  ```ts
60  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
61
62  function genKeyMaterialBlob(): cryptoFramework.DataBlob {
63    let arr = [
64      0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
65      0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
66      0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // The key length is 192 bits, that is, 24 bytes.
67    let keyMaterial = new Uint8Array(arr);
68    return { data: keyMaterial };
69  }
70
71  function testConvertSymKey() {
72    // Create a SymKeyGenerator instance.
73    let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
74    // Convert the data into a symmetric key.
75    let keyMaterialBlob = genKeyMaterialBlob();
76    let key = symKeyGenerator.convertKeySync(keyMaterialBlob);
77    let encodedKey = key.getEncoded(); // Obtain the binary data of the symmetric key and output the data as a byte array. The length is 24 bytes.
78    console.info('key getEncoded hex' + encodedKey.data);
79  }
80  ```
81
82## Converting Binary Data into an HMAC Key
83
84For details about the algorithm specifications, see [HMAC](crypto-sym-key-generation-conversion-spec.md#hmac).
85
861. Obtain the HMAC binary key and encapsulate it into a **DataBlob** object.
87
882. Use [cryptoFramework.createSymKeyGenerator](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatesymkeygenerator) with the string parameter **'HMAC'** to create a symmetric key generator (**SymKeyGenerator**) object for an HMAC key of [1, 32768] bits.
89
903. Use [SymKeyGenerator.convertKey](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkey-1) to convert the binary data into a symmetric key (**SymKey**).
91
924. Use [SymKey.getEncoded](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#getencoded) to obtain the binary data of the key.
93
94- Example: Convert binary data into an HMAC key in await mode.
95
96  ```ts
97  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
98  import { buffer } from '@kit.ArkTS';
99
100  async function testConvertHmacKey() {
101    // The symmetric key length is 64 bytes and 512 bits.
102    let keyMessage = '12345678abcdefgh12345678abcdefgh12345678abcdefgh12345678abcdefgh';
103    let keyBlob: cryptoFramework.DataBlob = {
104      data : new Uint8Array(buffer.from(keyMessage, 'utf-8').buffer)
105    }
106    let symKeyGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
107    let key = await symKeyGenerator.convertKey(keyBlob);
108    let encodedKey = key.getEncoded();
109    console.info('key encoded data: ' + encodedKey.data);
110  }
111  ```
112
113- Example using synchronous API [convertKeySync](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkeysync12):
114  ```ts
115  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
116  import { buffer } from '@kit.ArkTS';
117
118  function testConvertKeySync() {
119    // The symmetric key length is 64 bytes and 512 bits.
120    let keyMessage = '12345678abcdefgh12345678abcdefgh12345678abcdefgh12345678abcdefgh';
121    let keyBlob: cryptoFramework.DataBlob = {
122      data : new Uint8Array(buffer.from(keyMessage, 'utf-8').buffer)
123    }
124    let symKeyGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
125    let key = symKeyGenerator.convertKeySync(keyBlob);
126    let encodedKey = key.getEncoded();
127    console.info('key encoded data: ' + encodedKey.data);
128  }
129  ```
130