Demo
Demo
База знаний PMTA›Блок Global›Директива§ 3.3.1.58.5

http-api-key

Globalкритичнонужен перезапускХаб задаёт сам

Ключи, дающие полный доступ ко всем HTTP-интерфейсам узла
в конфигурации это строкаhttp-api-keyвнутри блока Global
Один ключ — полный доступ к узлу

Строка объявляет ключ, который клиент передаёт заголовком X-API-Key. Длина от 32 до 128 знаков, буквы, цифры и подчёркивание, регистр важен. Строка повторяется — ключей может быть несколько, например по одному на приложение.

Ключ открывает не только монитор, а четыре вещи сразу: сам веб-монитор с правами администратора; API конфигурационных файлов (§ 8.2) — чтение, запись и перечисление файлов конфигурации узла; API конфигурации (§ 8.3) — правку списков адресов и адресов отправки; API команд (§ 8.4) — почти все команды консоли по HTTP.

Ключ сильнее ограничения по адресу. Руководство говорит это дважды и дословно: правильный ключ отменяет всё, что задано в http-access, и запросы принимаются с любого адреса. Это не второй фактор, а обход первого.

Значит, ключ равен доступу к узлу — и к его конфигурации. Тот, у кого он есть, может переписать файл конфигурации через API и перезагрузить MTA.

Главная ловушка — обращаться с ключом как с паролем к панели, а не как с корневым доступом. Он лежит в файле конфигурации открытым текстом; файл читают, копируют, кладут в системы хранения версий и отправляют в поддержку — вместе с ключом. Права на файл здесь значат ровно столько же, сколько сам ключ.
Что делает Хаб. Пишет — по одному ключу на узел, в блоке телеметрии. Ключ хранится в node_engines.api_key_encrypted зашифрованным и в интерфейсе не показывается. Двух действующих ключей одновременно не бывает: конфигурация переписывается целиком, и старая строка исчезает.

🔴 Но на провод ключ уходит открытым текстом. Опрос идёт по обычному http:// — NodePoller, PmtaMonitor и PmtaCommander кладут его в заголовок без шифрования, а в базовой конфигурации у нас стоит http-redirect-to-https false. Ключ, которым можно переписать конфигурацию узла и выполнить любую команду, пересекает сеть в открытую при каждом опросе. Зашифровано хранение, не передача.

Рекомендуемые значения

Ключ длинный и случайный, иначе он не ключ:

Что Как
длина от 32 до 128 знаков
набор латиница, цифры, подчёркивание
регистр важен
сколько сколько нужно; строка повторяется

Разным приложениям — разные ключи. Тогда отзыв одного не рвёт работу остальных: убирается одна строка.

Длина, набор знаков и повторяемость — из руководства (§ 3.3.1.58.5, § 8.1.3). Что ключ отменяет ограничение по адресу и открывает три API — оттуда же (§ 8.2, § 8.3, § 8.4). Разбор нашей схемы хранения и передачи — по коду Хаба.
Пример в конфигурации
# разным приложениям — разные ключи: отзыв одного не рвёт остальные
http-api-key abcd_0123_abcd_0123_abcd_0123_ab   # телеметрия Хабаhttp-api-key 5f6e7e426949e3a5e4ec38e747e71963   # выгрузка отчётов
Пример руководства с нашими комментариями. Комментарий рядом с ключом — единственный способ потом понять, чей он и что сломается при отзыве.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

Типичные ошибки и проблемы

что делают не так и чем это кончается3 ошибки▶

Считают ключ вторым фактором поверх списка адресов

§ 8.2

Чем чреватоКлюч не дополняет список, а отменяет его. Монитор, закрытый по адресам и снабжённый ключом, открыт всему миру для того, у кого ключ есть.
Как заметитьВ списке доступа узкий диапазон, а в журнале успешные запросы извне.
Как правильноСчитать ключ равным корневому доступу к узлу: хранить, передавать и отзывать соответственно.

Передают ключ по незашифрованному соединению

наш опыт

Чем чреватоЗаголовок виден любому на пути. Перехвативший получает право переписать конфигурацию узла и выполнить любую команду.
Как заметитьВ конфигурации http-redirect-to-https false, а клиент ходит по http://.
Как правильноВключить перенаправление на https и научить клиента доверять сертификату монитора — он самоподписанный, лежит файлом /var/lib/pmta/webmon.pem.

Один ключ на все приложения

наш опыт

Чем чреватоОтзыв ключа рвёт работу всех сразу, поэтому его не отзывают никогда — даже когда надо.
Как заметитьВ файле одна строка ключа, а пользователей у него несколько.
Как правильноПо ключу на приложение, комментарий рядом с каждым.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
http-api-key STRING
Значения
строка от 32 до 128 знаков из латиницы, цифр и подчёркивания
Применение
нужен перезапуск сервиса
Очередь
уже поставленное в очередь не затронет
Где писать
Global
Сколько раз
можно повторять
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строки пишутся в корне файла, раздел Global, и действуют на весь узел. Разделения по интерфейсам у ключей нет: любой объявленный ключ открывает все четыре — монитор, оба API конфигурации и API команд. Отдельный ключ подачи по HTTP — это другая строка, api-key в <transmissions-api>.
⇄

Связанные директивы

4 связи

Без чего не работает

Закрыть права на файлы конфигурацииКлюч лежит в файле открытым текстом, поэтому права на файл значат столько же, сколько сам ключ. § 1.6.3

Чем можно заменить

http-accessGlobalДва способа впустить, и этот сильнее: правильный ключ отменяет ограничение по адресу. § 3.3.1.58.5

Где применяется

http-mgmt-portGlobalВсе три интерфейса HTTP, которые открывает ключ, слушают этот порт. § 8.4

Обычно вместе с

Сменить ключ подписи, не прерывая отправкуСмена ключа устроена так же, как смена ключа подписи: новый пишется, старый перестаёт действовать при применении. inference

Сюда ссылаются

http-csrf-protectionGlobalЗапрос с правильным ключом защиту не проходит, а обходит: ключ заменяет собой признак сессии. § 3.3.1.58.4http-enable-api-configGlobalЧтение может пройти по уровню доступа, но правка требует ключа всегда. § 8.3api-key<transmissions-api>Ключ другого входа — веб-монитора и HTTP API управления; названия похожи, права разные. § 3.3.20.1Как узел решает, впустить ли запрос по HTTPКлюч — второй способ представиться, и он сильнее первого. § 8.2

Как проверить на узле
Проверяем ключ тем же способом, каким им пользуются, — с адреса, которому доступ не разрешён:
curl -s -H 'X-API-Key: KEY' -o /dev/null -w '%{http_code}\n' http://NODE:1000/status
200 с неразрешённого адреса означает, что ключ действует и ограничение по адресу для него не работает — то есть всё как задумано вендором. Тот же ключ проверяет и API команд: curl -H ‘X-API-Key: KEY’ http://NODE:1000/command -F command=’show version’ -F format=json.
◇

Что ещё почитать

3 статьи

◇Аналитика вендора — и что уходит с узла ради неёПлатная служба, принимающая данные учёта узла и возвращающая аналитику, оценку здоровья и отчёт по спам-ловушкам; включается по областям и выключена, пока нет её блока.◇Отдача показателей по SNMPУзел умеет отдавать свои показатели по SNMP — второй способ наблюдения помимо веб-монитора.◇Что узел рассказывает о себе и по каким каналамСемь поверхностей наблюдения: веб-монитор, консоль в четырёх форматах, журнал, учёт, поиск по учёту, метрики и выгрузка во внешнюю аналитику.

В Хабе
Управляется
Инфраструктура → Параметры узла
Значение
Хаб подбирает сам — темп, стадия прогрева, метрики
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Безопасность узла · Собрать телеметрию
Важность
критично
Соседние настройки блока Global:http-accessrun-as-roothttp-csrf-protectionhttp-redirect-to-httpslog-file-world-readableВсе 108 директив блока →