KJUR.crypto.Mac: методы и параметры

KJUR.crypto.Mac — компонент библиотеки Jsrsasign, реализующий вычисление кода аутентификации сообщений (MAC), чаще всего в форме HMAC (Hash-based Message Authentication Code). Используется для проверки целостности данных и подтверждения их подлинности на основе общего секретного ключа.

В основе работы лежат криптографические хеш-функции (SHA-1, SHA-256, SHA-384, SHA-512 и другие), которые применяются совместно с секретным ключом.

Класс ориентирован на потоковую обработку данных: сообщение может поступать по частям, а итоговый MAC вычисляется после завершения ввода.

Поддерживаемые алгоритмы

Параметр алгоритма задаётся строкой и передаётся при создании экземпляра.

Чаще всего используются:

  • HmacSHA1
  • HmacSHA224
  • HmacSHA256
  • HmacSHA384
  • HmacSHA512

Выбор алгоритма определяет криптографическую стойкость и размер выходного значения.

Конструктор и параметры инициализации

Объект создаётся через:

var mac = new KJUR.crypto.Mac(params);

Основные параметры params

  • alg Алгоритм MAC, например "HmacSHA256".

  • pass или key Секретный ключ. Может передаваться как:

    • строка (UTF-8)
    • hex-строка
    • массив байтов

  • utf8 Интерпретация входных данных как UTF-8 строк (логическое значение).

  • hex Указывает, что ключ представлен в hex-формате.

  • prov / provider (в некоторых сборках) Определяет криптографический провайдер (если доступно).

Инициализация MAC-объекта

После создания объект может быть инициализирован явно:

mac.init();

Инициализация сбрасывает внутреннее состояние и подготавливает объект к новому вычислению.

При использовании конструктора с параметрами инициализация обычно выполняется автоматически.

Обновление данных (streaming input)

updateString

Добавление строки в вычисление MAC:

mac.updateString("message part");

Строка интерпретируется согласно настройкам (UTF-8 или raw).

updateHex

Добавление данных в hex-представлении:

mac.updateHex("0a1b2c3d");

Используется при работе с бинарными данными, уже преобразованными в hex.

Потоковая модель

Внутренне данные накапливаются блоками. Это позволяет:

  • обрабатывать большие сообщения без загрузки в память целиком
  • вычислять MAC для потоков данных (например, сетевых пакетов)

Завершение вычисления

doFinal

Основной метод получения результата:

var macValue = mac.doFinal();

Возвращает бинарное значение MAC.

После вызова объект обычно требует повторной инициализации для нового расчёта.

Получение результата в разных форматах

getMacHex

Возвращает MAC в hex-строке:

var hex = mac.getMacHex();

Используется при хранении и передаче в текстовых протоколах.

getMacBase64

Возвращает результат в Base64:

var b64 = mac.getMacBase64();

Часто применяется в HTTP-заголовках, JWT-подобных структурах и API-аутентификации.

Сброс состояния

reset

Приводит объект к начальному состоянию:

mac.reset();

Используется при повторном вычислении MAC с тем же ключом.

Полный цикл вычисления MAC

Типичный сценарий работы включает три этапа:

  1. Создание объекта с параметрами
  2. Постепенная подача данных
  3. Получение результата
var mac = new KJUR.crypto.Mac({
  alg: "HmacSHA256",
  pass: "secret"
});

mac.updateString("data part 1");
mac.updateString("data part 2");

var resultHex = mac.getMacHex();

Работа с ключами

Ключ может задаваться в разных представлениях:

Строка

pass: "password"

Hex

pass: "61626364",
hex: true

Байтовый массив

pass: [97, 98, 99, 100]

При использовании hex-режима важно учитывать корректность длины и кодировки.

Внутренние особенности реализации

  • Используется блоковая обработка данных (padding и chunking)
  • Поддерживаются стандартные HMAC-алгоритмы RFC 2104
  • При работе с SHA-2 алгоритмами длина блока зависит от выбранного хеша
  • Состояние MAC сохраняется между вызовами update*

Ошибки и типичные проблемы

Несовпадение кодировки ключа

Если ключ интерпретируется как UTF-8 вместо hex, результат MAC будет отличаться.

Повторное использование без reset

После doFinal() объект содержит завершённое состояние, и дальнейшие update* могут давать некорректный результат без reset().

Несоответствие алгоритма на стороне сервера

HMAC требует идентичного алгоритма и формата ключа на обеих сторонах.

Пример интеграции в протокол аутентификации

function signRequest(secret, payload) {
  var mac = new KJUR.crypto.Mac({
    alg: "HmacSHA256",
    pass: secret
  });

  mac.updateString(payload);
  return mac.getMacBase64();
}

Используется как основа для подписи API-запросов, где важно обеспечить неизменность данных и подтверждение источника.

Особенности работы с большими данными

При обработке больших сообщений предпочтительно использовать updateString/updateHex по частям:

mac.updateString(chunk1);
mac.updateString(chunk2);
mac.updateString(chunk3);

Такой подход снижает нагрузку на память и позволяет интеграцию с потоковыми источниками данных (файлы, сети, буферы).

Совместимость и окружения

KJUR.crypto.Mac работает:

  • в браузере
  • в Node.js (при использовании Jsrsasign)
  • в изолированных JavaScript-окружениях

Зависит от доступности криптографических провайдеров, встроенных в библиотеку.

Связанные компоненты Jsrsasign

В экосистеме часто используется совместно с:

  • KJUR.crypto.MessageDigest — хеширование без ключа
  • KJUR.crypto.Signature — цифровые подписи (RSA/ECDSA)
  • KEYUTIL — управление ключами
  • X509 — работа с сертификатами
Оглавление