Метод seal: параметры и возвращаемые значения

Метод seal формирует защищённое (зашифрованное и подписанное) представление произвольного значения, превращая его в строку, пригодную для безопасного хранения или передачи. Внутри выполняется сериализация данных, их криптографическая защита и упаковка в единый токен.

Iron.seal(object, password, options)

В современных версиях библиотеки метод возвращает Promise, что позволяет использовать его с async/await.

const sealed = await Iron.seal(object, password, options);

Параметры метода

object

Первый аргумент — данные, которые необходимо защитить.

  • Тип: Object | string | number | boolean | Buffer
  • Обязательный параметр
  • Передаётся любое сериализуемое значение

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

  • Объект сериализуется в JSON-формат
  • Буферы преобразуются в безопасное бинарное представление
  • Потеря несериализуемых типов (например, функции) происходит на этапе упаковки

password

Ключ, используемый для шифрования и формирования HMAC-подписи.

  • Тип: string
  • Обязательный параметр
  • Должен иметь достаточную криптографическую стойкость

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

  • Используется как основа для генерации ключей шифрования и проверки целостности
  • При изменении значения невозможно расшифровать ранее созданные данные

options

Объект конфигурации, определяющий параметры криптографической обработки.

  • Тип: Object
  • Необязательный параметр

Основные поля:

encryption

Алгоритм симметричного шифрования.

  • Пример: aes-256-cbc
integrity

Алгоритм контроля целостности (HMAC).

  • Пример: sha256
ttl

Время жизни зашифрованного значения.

  • Тип: number
  • Значение в миллисекундах
  • После истечения срока данные считаются недействительными при расшифровке
timestampSkewSec

Допустимое отклонение времени при проверке TTL.

  • Тип: number
  • Используется для компенсации расхождения системных часов
saltBits

Размер соли в битах.

  • Тип: number
  • Влияет на стойкость ключевого деривационного процесса
iterationCount

Количество итераций при деривации ключа.

  • Тип: number
  • Чем выше значение, тем выше криптографическая стойкость и нагрузка на процессор
randomSource

Функция генерации случайных значений.

  • Тип: function
  • Используется для замены системного генератора случайных чисел

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

Метод seal возвращает зашифрованную строку.

  • Тип: string

  • Формат: компактная строка, содержащая:

    • зашифрованные данные
    • параметры алгоритмов
    • контрольную сумму
    • служебные метаданные

При использовании async/await результатом является Promise<string>.

Особенности формирования результата

Строка, возвращаемая методом, не является просто шифротекстом. Она представляет собой контейнер, включающий несколько слоёв:

  • сериализованные данные
  • случайно сгенерированная соль
  • ключевые параметры шифрования
  • HMAC-подпись
  • служебные метки версии алгоритма

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

Поведение при ошибках

Метод может завершиться ошибкой в следующих случаях:

  • отсутствует обязательный параметр object или password
  • переданы некорректные криптографические параметры
  • генерация случайных значений невозможна
  • объект содержит несериализуемые циклические структуры

Ошибки выбрасываются как исключения или отклонения промиса.

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

import Iron from '@hapi/iron';

const data = {
  id: 42,
  role: 'admin'
};

const password = 'strong-secret-password';

const options = {
  encryption: 'aes-256-cbc',
  integrity: 'sha256',
  ttl: 60 * 60 * 1000
};

const sealed = await Iron.seal(data, password, options);

console.log(sealed);

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

Влияние параметров на результат

Изменение любого из параметров options приводит к формированию полностью другого токена:

  • смена encryption изменяет способ шифрования
  • изменение iterationCount влияет на производительность и стойкость
  • модификация saltBits меняет исходный криптографический материал
  • изменение ttl не влияет на структуру строки, но влияет на валидность при расшифровке

Даже при одинаковых входных данных результат метода каждый раз отличается из-за использования случайной соли и инициализационных векторов.

Криптографическая модель

Метод seal объединяет несколько механизмов:

  • симметричное шифрование для конфиденциальности
  • HMAC для проверки целостности
  • key derivation function (KDF) для получения ключей из пароля

Это обеспечивает одновременно защиту от чтения и подделки данных.

Практическое поведение TTL

При указании ttl в опциях в зашифрованную структуру включается временная метка. При расшифровке выполняется проверка:

  • текущее время сравнивается с временем создания
  • учитывается timestampSkewSec
  • при превышении срока выбрасывается ошибка истечения срока действия

Совместимость форматов

Строка, созданная seal, является полностью самодостаточной:

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

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

Оглавление