Класс KJUR.crypto.Mac

Класс KJUR.crypto.Mac реализует вычисление кода аутентификации сообщения (MAC) в библиотеке jsrsasign и служит универсальной обёрткой над симметричными алгоритмами контроля целостности, прежде всего HMAC и CMAC. Его задача заключается в последовательной обработке входных данных и получении криптографической подписи фиксированной структуры на основе секретного ключа.

Механизм MAC основан на идее использования секретного ключа и криптографической хеш-функции или блочного шифра. В jsrsasign класс KJUR.crypto.Mac абстрагирует различия между алгоритмами и предоставляет единый интерфейс для вычисления кода аутентификации.

Внутри реализуется типовой поток обработки данных:

  1. Инициализация алгоритма и ключа
  2. Постепенная подача данных (streaming)
  3. Финализация и получение результата

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

В зависимости от конфигурации поддерживаются следующие типы MAC:

  • HMAC на базе SHA-1, SHA-256, SHA-384, SHA-512
  • CMAC на основе блочных шифров (AES)

На практике чаще всего используется HMAC-SHA256 как баланс между скоростью и криптографической стойкостью.

Создание экземпляра класса

Инициализация MAC-объекта выполняется через передачу параметров в конструктор:

var mac = new KJUR.crypto.Mac({
  "alg": "HmacSHA256",
  "pass": "secret_key"
});

Ключевые параметры:

  • alg — алгоритм вычисления MAC
  • pass — секретный ключ (в виде строки или hex)
  • prov — криптографический провайдер (опционально, зависит от реализации)

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

Внутреннее состояние объекта

После создания экземпляр содержит следующие логические компоненты:

  • выбранный алгоритм (alg)
  • объект хеш-функции или блочного шифра
  • буфер входных данных
  • нормализованный ключ

Архитектура построена так, чтобы поддерживать потоковую обработку без необходимости загружать весь текст сообщения в память.

Инициализация вычисления

Перед началом обработки данных вызывается метод инициализации (обычно автоматически внутри конструктора или через внутренний reset):

  • создание HMAC-контекста
  • применение ключа
  • подготовка внутреннего состояния хеш-функции

Для HMAC используется стандартная схема:

  • XOR ключа с ipad
  • первичное хеширование

Подача данных на вход

Класс поддерживает поэтапное добавление данных, что важно при работе с большими потоками.

Основные методы:

mac.updateString("hello");
mac.updateHex("616263");

updateString

Принимает строку и преобразует её в байтовое представление UTF-8 перед обработкой.

updateHex

Принимает данные в виде hex-строки и интерпретирует их как бинарный массив.

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

Каждый вызов update* не приводит к финализации результата. Вместо этого данные добавляются во внутренний буфер и немедленно передаются в хеш-функцию.

Это позволяет:

  • обрабатывать файлы по частям
  • вычислять MAC для сетевых потоков
  • избегать лишнего копирования данных

Финализация вычисления

Завершающий этап выполняется через метод:

var result = mac.doFinal();

или альтернативные формы:

mac.getMac();

(в зависимости от версии реализации)

На этом этапе происходит:

  1. Добавление padding (если требуется)
  2. Финальное хеширование
  3. Применение второй стадии HMAC (outer hash)
  4. Возврат результата

Результат обычно возвращается в hex-формате.

Пример полного цикла HMAC

var mac = new KJUR.crypto.Mac({
  alg: "HmacSHA256",
  pass: "my_secret"
});

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

var hmac = mac.doFinal();

Работа с различными форматами входных данных

Класс поддерживает несколько представлений входа:

Текстовые данные

mac.updateString("data");

Используется UTF-8 кодирование.

Hex данные

mac.updateHex("deadbeef");

Используется для бинарных сообщений.

Алгоритмическая независимость

Одной из ключевых особенностей KJUR.crypto.Mac является унификация интерфейса для разных алгоритмов.

При смене параметра alg меняется только внутренняя реализация:

"HmacSHA1"
"HmacSHA256"
"HmacSHA512"
"AESCMAC"

Внешний API остаётся одинаковым, что упрощает интеграцию в криптографические модули.

CMAC режим

При использовании блочного шифра (например, AES) класс переключается в режим CMAC.

Особенности:

  • отсутствие хеш-функции
  • использование блокового шифрования
  • обработка данных по 16-байтным блокам
  • формирование подстановочных ключей (K1, K2)

CMAC чаще используется в протоколах, где требуется стандарт AES-based аутентификация.

Внутренняя криптографическая схема HMAC

При использовании HMAC выполняется стандартная конструкция:

(K, m) = H((K opad) H((K ipad) m))

Где:

  • K — секретный ключ
  • m — сообщение
  • H — хеш-функция
  • ipad, opad — фиксированные константы

Особенности реализации в jsrsasign

Реализация в KJUR.crypto.Mac отличается рядом инженерных решений:

  • отсутствие глобального состояния
  • чистая объектная модель
  • возможность многократного использования экземпляра
  • поддержка потоковой обработки
  • совместимость с другими модулями KJUR.crypto

Повторное использование экземпляра

После вызова doFinal объект может быть повторно использован, если выполнен reset состояния:

mac.updateString("first");
var r1 = mac.doFinal();

mac.updateString("second");
var r2 = mac.doFinal();

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

Обработка ошибок и некорректных данных

Типовые ситуации:

  • отсутствие ключа
  • неподдерживаемый алгоритм
  • неверный формат hex-строки

В этих случаях выполнение прерывается с генерацией исключения JavaScript.

Производительность

HMAC-реализация оптимизирована под:

  • минимизацию копирования буферов
  • потоковую обработку
  • использование встроенных криптографических примитивов jsrsasign

Наибольшая нагрузка приходится на хеш-функцию, особенно при SHA-512.

Практическое использование в протоколах

MAC на базе KJUR.crypto.Mac применяется в:

  • JWT-подобных структурах подписи
  • API-аутентификации
  • защите сообщений в REST и WebSocket
  • проверке целостности передаваемых данных

Особенности работы с ключами

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

  • строка (UTF-8)
  • hex
  • иногда Base64 (при предварительном декодировании)

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

Потоковая безопасность

Класс не является потокобезопасным в смысле конкурентного доступа. Каждый экземпляр предназначен для использования в одном контексте вычисления MAC.

Интеграция с другими компонентами jsrsasign

KJUR.crypto.Mac часто используется совместно с:

  • KJUR.crypto.Cipher
  • KJUR.crypto.Signature
  • KEYUTIL для работы с ключами

Это позволяет строить полные криптографические цепочки: подпись, шифрование и аутентификация данных в одном стеке.

Оглавление