Библиотека Iron реализует механизм «sealing» — криптографическое упаковывание данных с последующей аутентификацией и шифрованием. Внутри используется набор параметров, которые задают поведение алгоритмов шифрования и проверки целостности.
В Iron ключевыми являются настройки, которые часто рассматриваются как константы уровня конфигурации:
encryption — алгоритм симметричного шифрования
данных По умолчанию используется aes-256-cbc,
обеспечивающий баланс между производительностью и
криптостойкостью.
integrity — алгоритм вычисления HMAC Часто
применяется sha256, который отвечает за проверку
целостности и подлинности данных.
minPasswordlength — минимальная длина пароля
Обычно задана значением 32, что связано с требованиями
криптографической стойкости ключевого материала.
ttl (time to live) — время жизни защищённого объекта Определяет срок действия sealed-данных. По умолчанию может быть не задан, что означает отсутствие автоматического истечения.
timestampSkewSec — допустимое отклонение времени Используется при проверке временных меток для компенсации рассинхронизации часов между системами.
localtimeOffsetMsec — локальная поправка времени Позволяет учитывать смещение локального времени относительно серверного.
Эти параметры формируют основу поведения Iron и задают криптографическую модель работы библиотеки.
Iron не стремится к большому числу жёстко зашитых констант. Вместо этого используется подход конфигурационной предсказуемости: значения по умолчанию определены библиотекой, но могут быть переопределены пользователем.
Такой подход снижает связанность кода и позволяет адаптировать библиотеку под разные требования безопасности:
Модель обработки ошибок в Iron построена вокруг набора
специализированных классов, отражающих конкретные этапы процесса
seal и unseal.
Все ошибки наследуются от базового типа Error, но
разделяются по причинам возникновения.
Bad Format Error
Возникает при попытке распарсить строку, не соответствующую внутреннему формату sealed-данных.
Причины:
Bad HMAC Error
Возникает при несоответствии контрольной суммы.
Это означает, что данные были изменены после упаковки или ключ аутентификации неверен.
Характерные сценарии:
Decryption Error
Возникает при невозможности расшифровать payload.
Причины:
Invalid Password Error
Возникает при использовании некорректного пароля, который не может быть использован для расшифровки или проверки целостности.
В контексте Iron пароль является основным источником ключевого материала, поэтому ошибка указывает на полное несоответствие криптографического контекста.
Expiration Error
Возникает при истечении срока действия данных (TTL).
Проверка выполняется на этапе unseal и учитывает:
Seal Error
Обобщённая ошибка, возникающая при невозможности корректно выполнить операцию упаковки данных.
Может быть связана с:
Unsealing Error
Возникает при невозможности извлечь исходные данные из sealed-строки.
Является контейнерной ошибкой, которая может оборачивать другие типы:
Ошибки Iron не являются случайным набором классов. Их структура отражает этапы жизненного цикла данных:
Парсинг
Проверка целостности
Расшифровка
Валидация доступа
Обобщённый уровень
Такая иерархия позволяет точно локализовать проблему без необходимости ручного анализа криптографических деталей.
Механизм ошибок спроектирован так, чтобы минимизировать утечку чувствительной информации:
Это делает библиотеку безопасной для использования в серверных приложениях, где токены и сессионные данные проходят через публичные интерфейсы.
При вызове Iron.unseal() ошибка всегда возвращается в
синхронной форме как исключение.
Типичный порядок обработки:
Любой сбой на любом этапе приводит к прерыванию цепочки обработки.
Ошибки Iron напрямую отражают этапы симметричного шифрования:
Таким образом, каждая ошибка соответствует конкретному уровню криптографической защиты, а не абстрактному программному сбою.