正确使用Google Apps Script计算带十六进制密钥的HMAC

聖光之護

发布时间：2025-09-10 16:26:01

948人浏览过

来源于php中文网

原创

正确使用google apps script计算带十六进制密钥的hmac

本文详细介绍了在Google Apps Script中正确计算HMAC签名的方法，特别是当密钥以十六进制字符串形式提供时。核心挑战在于将十六进制密钥和消息内容准确转换为Google Apps Script Utilities.computeHmacSignature函数所需的字节数组格式，以确保与PHP等其他语言生成的HMAC结果一致。通过示例代码，我们演示了如何进行正确的字节转换，避免常见的编码陷阱，从而成功实现API认证。

理解HMAC与字节表示

HMAC（Keyed-Hash Message Authentication Code）是一种使用加密哈希函数和密钥来验证消息完整性和真实性的机制。在API认证中，HMAC被广泛应用。当在不同编程环境（如PHP与Google Apps Script）中实现HMAC时，一个常见的挑战是确保密钥和消息的底层字节表示方式一致。特别是当密钥以十六进制字符串形式提供时，需要将其正确转换为二进制字节序列。

PHP的hash_hmac函数在处理字符串类型的密钥时，会将其解释为二进制数据。例如，chr(hexdec('C7'))会将十六进制C7（十进制199）转换为一个字节值为199的字符。然而，Google Apps Script中的Utilities.computeHmacSignature函数对输入类型有更严格的要求，通常期望密钥和消息都是字节数组（byte[]）。

常见错误：字符串与字节的混淆

在Google Apps Script中，初次尝试将十六进制密钥转换为字符串时，可能会使用String.fromCharCode(parseInt("C7", 16))。这种方法会将十六进制值解析为Unicode字符，而不是原始的字节。例如，parseInt("C7", 16)得到199，String.fromCharCode(199)会生成一个Unicode字符，其字节表示可能与原始的二进制字节199不同，尤其是在不同的字符编码环境下。这会导致Utilities.computeHmacSignature函数对密钥的解释出现偏差，从而计算出错误的HMAC值。

原始的Google Apps Script尝试：

// 错误示例：将十六进制转换为Unicode字符
var klucz = String.fromCharCode(parseInt("C7",16)) + String.fromCharCode(parseInt("7C",16)) + ...;
// ...
var hmac = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_SHA_1, wiadomosc, klucz);

这种方法未能正确地将十六进制表示的二进制密钥转换为Utilities.computeHmacSignature所期望的字节数组，导致计算结果与PHP不一致。

正确的HMAC计算方法

为了在Google Apps Script中正确计算HMAC，需要确保以下两点：

十六进制密钥转换为字节数组。
消息内容转换为字节数组。

1. 密钥的十六进制到字节数组转换

给定一个十六进制密钥字符串（例如C77C96EEF6F6995B），我们需要将其分解为每两个字符一组的十六进制对，然后将每对转换为其对应的十进制数值。由于Java（Google Apps Script底层）的byte类型是有符号的，范围是-128到127，因此对于大于127（即0x7F）的无符号字节值，需要进行相应的调整（减去256）以匹配Java的带符号字节表示。

Magician

Figma插件，AI生成图标、图片和UX文案

下载

以下是实现此转换的JavaScript代码片段：

/**
 * 将十六进制字符串转换为Google Apps Script Utilities函数所需的字节数组。
 * 对于大于127的无符号字节值，转换为其对应的带符号字节表示。
 * @param {string} hexString 十六进制密钥字符串，例如 "C77C96EEF6F6995B"。
 * @returns {number[]} 字节数组。
 */
function hexToSignedByteArray(hexString) {
    return hexString.match(/.{2}/g).map(e => {
        const byteValue = parseInt(e, 16);
        // 如果字节值大于127（即最高位为1），则转换为带符号的负数
        return byteValue > 127 ? byteValue - 256 : byteValue;
    });
}

// 示例使用
var hexKey = "C77C96EEF6F6995B";
var kluczByteArray = hexToSignedByteArray(hexKey);
// kluczByteArray 现在是一个如 [-57, 124124, -106, -18, -10, -10, -103, 91] 的数组

这个hexToSignedByteArray函数确保了十六进制密钥被正确地解析为Google Apps Script Utilities函数所期望的byte[]（实际上是number[]，其中数字代表字节值，并处理了符号位）。

2. 消息内容的字节数组转换

同样，为了确保一致性，传递给Utilities.computeHmacSignature的消息内容也应该是一个字节数组。Google Apps Script提供了Utilities.newBlob(string).getBytes()方法，可以将字符串按照UTF-8编码转换为字节数组。

var messageString = "https://www.ifirma.pl/iapi/abonent/miesiacksiegowy.json" + "user@example.com" + "abonent";
var messageByteArray = Utilities.newBlob(messageString).getBytes();

3. 完整的Google Apps Script HMAC计算

结合上述转换，以下是Google Apps Script中正确计算HMAC的完整函数：

/**
 * 将字节数组转换为十六进制字符串，用于日志输出。
 * @param {number[]} data 字节数组。
 * @returns {string} 十六进制字符串。
 */
function bytesToHex(data) {
    return data.map(function(e) {
        // 将带符号字节转换为无符号字节（0-255），然后转为16进制
        var v = (e < 0 ? e + 256 : e).toString(16);
        return v.length == 1 ? "0" + v : v;
    }).join("");
}

/**
 * 将十六进制字符串转换为Google Apps Script Utilities函数所需的字节数组。
 * 对于大于127的无符号字节值，转换为其对应的带符号字节表示。
 * @param {string} hexString 十六进制密钥字符串。
 * @returns {number[]} 字节数组。
 */
function hexToSignedByteArray(hexString) {
    return hexString.match(/.{2}/g).map(e => {
        const byteValue = parseInt(e, 16);
        return byteValue > 127 ? byteValue - 256 : byteValue;
    });
}

/**
 * 在Google Apps Script中计算HMAC-SHA1签名。
 */
function callNumbers() {
  // 1. 准备十六进制密钥并转换为字节数组
  var hexKey = "C77C96EEF6F6995B";
  var kluczByteArray = hexToSignedByteArray(hexKey);

  // 2. 准备消息内容
  var user = "user@example.com"; // 替换为实际的用户信息
  var url = "https://www.ifirma.pl/iapi/abonent/miesiacksiegowy.json"; // 替换为实际的URL
  var nazwaKlucza = "abonent"; // 替换为实际的键名

  var messageString = url + user + nazwaKlucza;

  // 3. 将消息字符串转换为字节数组
  var messageByteArray = Utilities.newBlob(messageString).getBytes();

  // 4. 使用Utilities.computeHmacSignature计算HMAC
  // 注意：HMAC_SHA_1算法，消息和密钥都必须是字节数组
  var hmacByteArray = Utilities.computeHmacSignature(
      Utilities.MacAlgorithm.HMAC_SHA_1,
      messageByteArray,
      kluczByteArray
  );

  // 5. 将结果字节数组转换为十六进制字符串以便于显示和比较
  var hmacHex = bytesToHex(hmacByteArray);
  Logger.log(hmacHex); // 预期输出: 9b5f9bb41ac30b9c55b10f3cecdd6e12e852f274
}

运行上述callNumbers函数，将得到与PHP脚本完全一致的HMAC哈希值：9b5f9bb41ac30b9c55b10f3cecdd6e12e852f274。

总结与注意事项

字节数组是关键： 在Google Apps Script中使用Utilities.computeHmacSignature时，务必将十六进制密钥和消息内容都转换为字节数组。直接使用字符串作为二进制密钥或消息可能会导致不一致的结果。
十六进制密钥转换： 对于十六进制密钥，需要将其解析为每两个字符一组，并转换为对应的数值。考虑到Java底层对byte类型的处理，对于大于127的无符号字节值，需要转换为其对应的带符号表示（即减去256）。
消息编码： Utilities.newBlob(string).getBytes()默认使用UTF-8编码将字符串转换为字节数组。请确保这与API期望的编码一致。
bytesToHex函数： 此辅助函数用于将computeHmacSignature返回的字节数组转换为可读的十六进制字符串，便于验证和调试。

通过遵循这些指导原则，您可以在Google Apps Script中可靠地实现HMAC签名，确保与各种API和平台之间的兼容性。