1# 消息认证码计算
2
3
4MAC（Message Authentication Code，消息认证码）可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为。
5
6
7HMAC（Hash-based Message Authentication Code）是一种基于哈希的消息认证码算法。
8
9
10HMAC通过指定摘要算法，以通信双方共享密钥与消息作为输入，生成消息认证码用于检验传递报文的完整性。HMAC在消息摘要算法的基础上增加了密钥的输入，确保了信息的正确性。生成的消息认证码为固定长度。
11
12
13## 支持的算法与规格
14
15当创建HMAC消息认证码时，需要使用表中“支持种类”一列，指定HMAC消息认证码算法规格。
16
17| 摘要算法 | 支持种类 | API版本 |
18| -------- | -------- | -------- |
19| HASH | SHA1 | 9+ |
20| HASH | SHA224 | 9+ |
21| HASH | SHA256 | 9+ |
22| HASH | SHA384 | 9+ |
23| HASH | SHA512 | 9+ |
24| HASH | SM3 | 10+ |
25| HASH | MD5 | 12+ |
26
27## 开发步骤
28
29在调用update接口传入数据时，可以[一次性传入所有数据](#hmac一次性传入)，也可以把数据人工分段，然后[分段update](#分段hmac)。对于同一段数据而言，是否分段，计算结果没有差异。对于数据量较大的数据，开发者可以根据实际需求选择是否分段传入。
30
31下面分别提供两种方式的示例代码。
32
33
34### HMAC（一次性传入）
35
361. 调用[cryptoFramework.createMac](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatemac)，指定摘要算法SHA256，生成消息认证码实例（Mac）。
37
382. 调用[cryptoFramework.createSymKeyGenerator](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatesymkeygenerator)、[SymKeyGenerator.convertKey](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkey-1)，生成密钥算法为HMAC的对称密钥（SymKey）。
39   生成对称密钥的详细开发指导，请参考[指定二进制数据生成对称密钥](crypto-convert-binary-data-to-sym-key.md)。
40
413. 调用[Mac.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-6)，指定共享对称密钥（SymKey），初始化Mac对象。
42
434. 调用[Mac.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-8)，传入自定义消息，进行消息认证码计算。单次update长度没有限制。
44
455. 调用[Mac.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-2)，获取Mac计算结果。
46
476. 调用[Mac.getMacLength](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#getmaclength)，获取Mac消息认证码的长度，单位为字节。
48
49- 以使用await方式一次性传入数据，获取消息认证码计算结果为例：
50
51  ```ts
52  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
53  import { buffer } from '@kit.ArkTS';
54
55  async function genSymKeyByData(symKeyData: Uint8Array) {
56    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
57    let aesGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
58    let symKey = await aesGenerator.convertKey(symKeyBlob);
59    console.info('convertKey success');
60    return symKey;
61  }
62  async function doHmac() {
63    // 把字符串按utf-8解码为Uint8Array，使用固定的128位的密钥，即16字节
64    let keyData = new Uint8Array(buffer.from("12345678abcdefgh", 'utf-8').buffer);
65    let key = await genSymKeyByData(keyData);
66    let macAlgName = 'SHA256'; // 摘要算法名
67    let message = 'hmacTestMessgae'; // 待进行HMAC的数据
68    let mac = cryptoFramework.createMac(macAlgName);
69    await mac.init(key);
70    // 数据量较少时，可以只做一次update，将数据全部传入，接口未对入参长度做限制
71    await mac.update({ data: new Uint8Array(buffer.from(message, 'utf-8').buffer) });
72    let macResult = await mac.doFinal();
73    console.info('HMAC result:' + macResult.data);
74    let macLen = mac.getMacLength();
75    console.info('HMAC len:' + macLen);
76  }
77  ```
78
79- 以使用同步方式一次性传入数据，获取消息认证码计算结果为例：
80
81  ```ts
82  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
83  import { buffer } from '@kit.ArkTS';
84
85  function genSymKeyByData(symKeyData: Uint8Array) {
86    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
87    let aesGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
88    let symKey =  aesGenerator.convertKeySync(symKeyBlob);
89    console.info('[Sync]convertKey success');
90    return symKey;
91  }
92  function doHmacBySync() {
93    // 把字符串按utf-8解码为Uint8Array，使用固定的128位的密钥，即16字节
94    let keyData = new Uint8Array(buffer.from("12345678abcdefgh", 'utf-8').buffer);
95    let key = genSymKeyByData(keyData);
96    let macAlgName = 'SHA256'; // 摘要算法名
97    let message = 'hmacTestMessgae'; // 待进行HMAC的数据
98    let mac = cryptoFramework.createMac(macAlgName);
99    mac.initSync(key);
100    // 数据量较少时，可以只做一次update，将数据全部传入，接口未对入参长度做限制
101    mac.updateSync({ data: new Uint8Array(buffer.from(message, 'utf-8').buffer) });
102    let macResult = mac.doFinalSync();
103    console.info('[Sync]HMAC result:' + macResult.data);
104    let macLen = mac.getMacLength();
105    console.info('HMAC len:' + macLen);
106  }
107  ```
108
109### 分段HMAC
110
1111. 调用[cryptoFramework.createMac](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatemac)，指定摘要算法SHA256，生成消息认证码实例（Mac）。
112
1132. 调用[cryptoFramework.createSymKeyGenerator](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatesymkeygenerator)、[SymKeyGenerator.convertKey](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#convertkey-1)，生成密钥算法为HMAC的对称密钥（SymKey）。
114   生成对称密钥的详细开发指导，请参考[指定二进制数据生成对称密钥](crypto-convert-binary-data-to-sym-key.md)。
115
1163. 调用[Mac.init](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#init-7)，指定共享对称密钥（SymKey），初始化Mac对象。
117
1184. 传入自定义消息，将一次传入数据量设置为20字节，多次调用[Mac.update](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#update-9)，进行消息认证码计算。
119
1205. 调用[Mac.doFinal](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#dofinal-3)，获取Mac计算结果。
121
1226. 调用[Mac.getMacLength](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#getmaclength)，获取Mac消息认证码的长度，单位为字节。
123
124- 以使用await方式分段传入数据，获取消息认证码计算结果为例：
125
126  ```ts
127  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
128  import { buffer } from '@kit.ArkTS';
129
130  async function genSymKeyByData(symKeyData: Uint8Array) {
131    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
132    let aesGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
133    let symKey = await aesGenerator.convertKey(symKeyBlob);
134    console.info('convertKey success');
135    return symKey;
136  }
137  async function doLoopHmac() {
138    // 把字符串按utf-8解码为Uint8Array，使用固定的128位的密钥，即16字节
139    let keyData = new Uint8Array(buffer.from("12345678abcdefgh", 'utf-8').buffer);
140    let key = await genSymKeyByData(keyData);
141    let macAlgName = "SHA256"; // 摘要算法名
142    let mac = cryptoFramework.createMac(macAlgName);
143    // 假设信息总共43字节，根据utf-8解码后，也是43字节
144    let messageText = "aaaaa.....bbbbb.....ccccc.....ddddd.....eee";
145    let messageData = new Uint8Array(buffer.from(messageText, 'utf-8').buffer);
146    let updateLength = 20; // 假设以20字节为单位进行分段update，实际并无要求
147    await mac.init(key);
148    for (let i = 0; i < messageData.length; i += updateLength) {
149      let updateMessage = messageData.subarray(i, i + updateLength);
150      let updateMessageBlob: cryptoFramework.DataBlob = { data: updateMessage };
151      await mac.update(updateMessageBlob);
152    }
153    let macOutput = await mac.doFinal();
154    console.info("HMAC result: " + macOutput.data);
155    let macLen = mac.getMacLength();
156    console.info('HMAC len:' + macLen);
157  }
158  ```
159
160- 以使用同步方式分段传入数据，获取消息认证码计算结果为例：
161
162  ```ts
163  import { cryptoFramework } from '@kit.CryptoArchitectureKit';
164  import { buffer } from '@kit.ArkTS';
165
166  function genSymKeyByData(symKeyData: Uint8Array) {
167    let symKeyBlob: cryptoFramework.DataBlob = { data: symKeyData };
168    let aesGenerator = cryptoFramework.createSymKeyGenerator('HMAC');
169    let symKey = aesGenerator.convertKeySync(symKeyBlob);
170    console.info('[Sync]convertKey success');
171    return symKey;
172  }
173  function doLoopHmacBySync() {
174    // 把字符串按utf-8解码为Uint8Array，使用固定的128位的密钥，即16字节
175    let keyData = new Uint8Array(buffer.from("12345678abcdefgh", 'utf-8').buffer);
176    let key = genSymKeyByData(keyData);
177    let macAlgName = "SHA256"; // 摘要算法名
178    let mac = cryptoFramework.createMac(macAlgName);
179    // 假设信息总共43字节，根据utf-8解码后，也是43字节
180    let messageText = "aaaaa.....bbbbb.....ccccc.....ddddd.....eee";
181    let messageData = new Uint8Array(buffer.from(messageText, 'utf-8').buffer);
182    let updateLength = 20; // 假设以20字节为单位进行分段update，实际并无要求
183    mac.initSync(key);
184    for (let i = 0; i < messageData.length; i += updateLength) {
185      let updateMessage = messageData.subarray(i, i + updateLength);
186      let updateMessageBlob: cryptoFramework.DataBlob = { data: updateMessage };
187      mac.updateSync(updateMessageBlob);
188    }
189    let macOutput = mac.doFinalSync();
190    console.info("[Sync]HMAC result: " + macOutput.data);
191    let macLen = mac.getMacLength();
192    console.info('HMAC len:' + macLen);
193  }
194  ```
195