iron.defaults

Параметр iron.defaults представляет собой централизованный набор значений по умолчанию, используемых библиотекой для операций сериализации, шифрования и защиты данных. Он задаёт базовую конфигурацию, которая применяется при вызовах функций упаковки и распаковки защищённых объектов, если разработчик явно не передал собственные настройки.

Основная цель iron.defaults — обеспечить единообразное поведение криптографических операций и снизить вероятность ошибок, связанных с неполной или некорректной конфигурацией.

Роль defaults в архитектуре библиотеки

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

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

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

Общая структура iron.defaults

Типичная структура объекта iron.defaults включает набор параметров, связанных с криптографией, временем жизни защищённых данных и алгоритмами проверки целостности.

Пример логической структуры:

iron.defaults = {
    password: undefined,
    encryption: 'aes-256-cbc',
    integrity: 'sha256',
    ttl: 0,
    timestampSkewSec: 60,
    localtimeOffsetMsec: 0
};

Каждое поле отвечает за определённый аспект безопасности или поведения библиотеки.

password

Поле password является базовым элементом конфигурации. Оно используется как ключевой секрет для симметричного шифрования данных.

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

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

В контексте iron.defaults это поле часто оставляют пустым, чтобы требовать явного задания ключа на уровне приложения.

encryption

Поле encryption определяет алгоритм симметричного шифрования, применяемого к полезной нагрузке.

Наиболее часто используемое значение:

  • aes-256-cbc

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

Роль в системе

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

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

integrity

Поле integrity определяет алгоритм проверки целостности данных.

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

  • sha256

Назначение:

  • защита от подмены данных;
  • обеспечение проверки аутентичности;
  • формирование HMAC-подобных контрольных значений.

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

ttl (Time To Live)

ttl задаёт время жизни защищённого объекта в миллисекундах.

Поведение:

  • 0 — отсутствие ограничения по времени;
  • положительное значение — автоматическое устаревание данных;
  • используется при проверке при распаковке.

Применение:

TTL особенно важен в сценариях:

  • токенов авторизации;
  • одноразовых ссылок;
  • временных сессий;
  • защищённых сообщений с ограниченным сроком действия.

timestampSkewSec

Параметр timestampSkewSec определяет допустимое отклонение системного времени при проверке TTL.

Зачем нужен:

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

Пример поведения:

  • если TTL истёк, но разница во времени меньше допустимого skew — данные считаются валидными;
  • предотвращает ложные ошибки истечения срока жизни.

localtimeOffsetMsec

Этот параметр задаёт смещение локального времени относительно UTC в миллисекундах.

Основные задачи:

  • корректировка временных меток;
  • синхронизация данных между системами с разными часовыми поясами;
  • унификация проверки TTL.

В большинстве случаев значение устанавливается автоматически или остаётся равным нулю.

Механизм применения defaults

iron.defaults используется как базовый слой конфигурации. При вызове функций типа seal/unseal происходит следующая логика:

  1. Берётся объект defaults.
  2. Он клонируется во внутреннюю конфигурацию.
  3. Пользовательские параметры накладываются поверх.
  4. Итоговый объект используется в криптографических операциях.

Такой подход позволяет:

  • избегать мутаций глобальных настроек;
  • сохранять предсказуемость;
  • упрощать переопределение параметров на уровне вызова.

Приоритеты конфигурации

В системе настроек действует строгая иерархия:

  1. Явно переданные параметры функции (наивысший приоритет)
  2. Значения из iron.defaults
  3. Внутренние значения библиотеки (fallback)

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

Безопасность и defaults

Использование iron.defaults напрямую связано с моделью безопасности библиотеки.

Ключевые аспекты:

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

Особенно важно, что password не должен иметь разумного дефолтного значения, так как это нарушило бы модель безопасности.

Расширение и кастомизация

Разработчики могут изменять iron.defaults для адаптации библиотеки под конкретные требования:

  • повышение времени жизни токенов;
  • смена алгоритмов (при совместимости);
  • настройка временных допусков;
  • интеграция с существующей инфраструктурой безопасности.

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

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

Если часть параметров не задана:

  • используются безопасные значения из defaults;
  • критически важные поля требуют явного задания;
  • операции могут быть заблокированы при недостатке конфигурации.

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

Оглавление