Коды ошибок ​

Общие коды ошибок для официально поддерживаемых DAT клиентских библиотек.

Каждому коду присвоены два значения — влияние и повтор, а некоторым дополнительно ставится метка подозрение.

Влияние — урон для сервиса ​

Это критерий для алертов. Смотрим только на одно: «сервис сейчас стоит или нет».

Без влияния — не повод для алерта. Если каждый неверный ввод обязана проверять вся дежурная смена, алерты теряют смысл.

Подозрение — расследуйте, если повторяется ​

Коды с меткой Подозрение в единичном случае являются частью нормальной эксплуатации. Клиент в любой момент может прислать неверное значение, и отфильтровать его — прямая обязанность библиотеки.

Но если такие ошибки идут постоянно или лавиной из одного источника, причина одна из двух.

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

Поэтому такие коды правильно вести как метрику по количеству. Оповещать имеет смысл только при превышении порога.

Повтор ​

Токен ​

Проблемы самой строки полученного токена.

Сертификат ​

Проблемы формата строки сертификата и того, можно ли использовать этот сертификат прямо сейчас.

DAT_CERT_NOT_FOUND и DAT_CERT_NOT_SYNCED внешне выглядят одинаково, но реакции разные. В первом случае это cid, который мы никогда не выпускали, — ожидание не поможет; во втором достаточно дождаться синхронизации.

Единичный DAT_CERT_NOT_FOUND достаточно просто отфильтровать, но резкий рост означает, что деплой разошёлся либо ходят поддельные токены.

Подпись ​

Шифрование ​

Проблемы шифрования и расшифровки полезной нагрузки secure.

Пустая полезная нагрузка secure не является ошибкой. Пустой вход даёт пустой выход и не порождает никакого кода.

На пути, где проверка подписи пропускается, тег GCM — единственная проверка целостности. Поэтому DAT_CRYPTO_TAG_MISMATCH не объединяется одним кодом с остальными сбоями расшифровки.

Ключ ​

Три похожих, но разных случая:

Менеджер ​

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

Причина (cause) у DAT_MANAGER_NO_ISSUABLE_CERTIFICATE — одна из четырёх. Для каждой причины нужны совершенно разные действия.

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

Конфигурация ​

Проблемы значений, переданных вызывающей стороной. Все коды семейства CONFIG — ошибки, требующие правки кода; если они возникают в проде, значит деплой сделан неверно.

Внутренние ​

Проблемы среды исполнения и рантайма.

DAT_INTERNAL_UNAVAILABLE решается исправлением среды развёртывания, а DAT_INTERNAL_UNKNOWN — обычно сбой рантайма либо баг библиотеки.

Синхронизация CMS ​

Если синхронизация CMS не используется, эти коды не появляются.

Коды, при которых синхронизация признаётся окончательно провалившейся (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED), все критичны. Повтор их не решает, а сертификаты продолжают истекать, поэтому без вмешательства сервис неизбежно остановится.

Напротив, UNREACHABLE и SERVER_ERROR — частичные. Работа продолжается на прежних сертификатах, и в следующем цикле всё восстанавливается само. Но при непрерывных сбоях это в итоге переходит в критичное. Настраивайте алерт по числу подряд идущих неудач.

Сервер ​

Коды, которые выдаёт сервер CMS. Клиент эти коды не создаёт, а только принимает.

Конверт ответа:

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

Ошибки, возникающие при создании и обработке сертификатов, сервер отдаёт теми же общими кодами, что описаны выше (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

Когда приходит код сервера ​

Клиент оборачивает код сервера в собственный код CMS, а оригинал сохраняет в cause.

Поиск по симптомам ​

Приложение ​

Синтаксис кода ​

DAT_<область>_<причина>

• Если одна и та же причина возникает в разных областях, имя причины совпадает. DAT_TOKEN_MALFORMED и DAT_CERT_MALFORMED отличаются только объектом, смысл у них один.
• _UNKNOWN — только запасной вариант для своей области. Он не используется в значении «неизвестный алгоритм» (для этого есть _UNSUPPORTED).
• Строка кода — это публичный контракт. Сообщение можно менять свободно, код — нет.

Доступ по клиентам ​

Событие безопасности возвращает true только для двух кодов, где подделка или подмена установлены точно (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). Метка подозрение в этом документе охватывает более широкий круг (включая подделанные токены, ключи и запросы) и пока является лишь документной классификацией, не выведенной в API клиентов.

Класс влияния — тоже документная классификация. Один и тот же код бьёт по-разному в зависимости от места возникновения: например, DAT_KEY_INVALID не влияет ни на что при фильтрации входящего токена, но при чтении сертификата во время синхронизации CMS обрушивает всю синхронизацию.

Первопричина не теряется. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE и DAT_CMS_IMPORT_FAILED передают причину через цепочку исключений соответствующего языка (cause / __cause__ / InnerException / Unwrap()).