Параметры вызова digest

Метод crypto.subtle.digest() предназначен для вычисления криптографического хэша переданных данных. Хэш-функции преобразуют входной массив байтов в фиксированную по длине последовательность, обладающую следующими свойствами:

  • детерминированность (один и тот же вход → один и тот же результат)
  • устойчивость к коллизиям (сложно найти два разных входа с одинаковым хэшем)
  • необратимость (невозможно восстановить исходные данные по хэшу)

Метод возвращает Promise, который резолвится в ArrayBuffer, содержащий результат хэширования.

Сигнатура метода

crypto.subtle.digest(algorithm, data)

Параметры вызова

algorithm

Определяет используемый алгоритм хэширования. Может быть задан в двух формах:

  1. Строка
  2. Объект с полем name
Поддерживаемые значения:
  • "SHA-1"
  • "SHA-256"
  • "SHA-384"
  • "SHA-512"
Примеры:
"SHA-256"

или

{ name: "SHA-256" }
Особенности:
  • Регистр символов имеет значение: "sha-256" приведёт к ошибке
  • Алгоритмы семейства SHA-2 (256 и выше) являются предпочтительными
  • "SHA-1" считается устаревшим и небезопасным для большинства задач

data

Данные для хэширования. Должны быть представлены в виде буфера байтов. Поддерживаются следующие типы:

  • ArrayBuffer
  • TypedArray (например, Uint8Array)
  • DataView
Пример преобразования строки в байты:
const encoder = new TextEncoder();
const data = encoder.encode("example");

Возвращаемое значение

Метод возвращает:

Promise<ArrayBuffer>

Результат необходимо дополнительно преобразовать для удобного использования (например, в строку HEX или Base64).

Пример полного вызова

const encoder = new TextEncoder();
const data = encoder.encode("Hello, world!");

const hashBuffer = await crypto.subtle.digest("SHA-256", data);

Преобразование результата

В HEX-строку

const hashArray = Array.from(new Uint8Array(hashBuffer));
const hex = hashArray
  .map(b => b.toString(16).padStart(2, "0"))
  .join("");

В Base64

const base64 = btoa(
  String.fromCharCode(...new Uint8Array(hashBuffer))
);

Ошибки и исключения

Метод может выбрасывать исключения или отклонять Promise в следующих случаях:

  • Неизвестный алгоритм

    crypto.subtle.digest("MD5", data) // ошибка

  • Неверный тип данных

    crypto.subtle.digest("SHA-256", "string") // ошибка

  • Отсутствие поддержки в окружении

    • Некоторые браузеры или контексты (например, небезопасный HTTP) могут не поддерживать API

Особенности работы

Асинхронность

Метод работает асинхронно и не блокирует основной поток, что особенно важно при обработке больших данных.

Ограничения по памяти

Весь входной массив должен быть загружен в память целиком. Для потоковой обработки больших файлов digest не подходит — требуется использование других API (например, Web Streams + сторонние библиотеки).

Отсутствие “инкрементального” режима

В отличие от многих криптографических библиотек (например, Node.js crypto.createHash()), Web Crypto API:

  • не поддерживает обновление хэша по частям
  • не имеет методов .update() и .final()

Разбор параметра algorithm

Хотя для digest параметр алгоритма минимален, важно учитывать:

  • используется только поле name
  • дополнительные параметры (например, длина ключа) игнорируются

Пример с объектом:

const algorithm = { name: "SHA-512" };

Это полностью эквивалентно строке:

"SHA-512"

Внутреннее поведение

При вызове:

  1. Проверяется корректность алгоритма
  2. Проверяется тип data
  3. Данные копируются во внутренний буфер
  4. Запускается криптографическая функция
  5. Возвращается результат в виде ArrayBuffer

Сравнение алгоритмов

Алгоритм Длина хэша Безопасность Производительность
SHA-1 160 бит Низкая Высокая
SHA-256 256 бит Высокая Средняя
SHA-384 384 бит Очень высокая Ниже средней
SHA-512 512 бит Очень высокая Ниже средней

Практические рекомендации

  • Использовать "SHA-256" как стандартный выбор
  • Избегать "SHA-1"
  • Всегда явно указывать алгоритм
  • Преобразовывать входные данные через TextEncoder
  • Хранить результат в удобном формате (HEX/Base64)

Пример функции-обёртки

async function hashSHA256(text) {
  const encoder = new TextEncoder();
  const data = encoder.encode(text);

  const buffer = await crypto.subtle.digest("SHA-256", data);

  return Array.from(new Uint8Array(buffer))
    .map(b => b.toString(16).padStart(2, "0"))
    .join("");
}

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

  • Хэширование небольших строк — практически мгновенное
  • При работе с массивами в мегабайтах возможны задержки
  • Алгоритмы с большей длиной хэша работают медленнее

Безопасный контекст

Web Crypto API доступен только в:

  • HTTPS
  • localhost

Попытка использовать API в небезопасном контексте приведёт к ошибке:

Uncaught DOMException: SubtleCrypto is not available

Итоговая структура вызова

crypto.subtle.digest(
  /* algorithm */ "SHA-256",
  /* data */ Uint8Array
);

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

Оглавление