Demo
Demo
База знаний PMTA›Блок <transmissions-api>›Директива§ 3.3.20.1

api-key

<transmissions-api>

Ключи, дающие право пользоваться Transmissions API
в конфигурации это строкаapi-keyвнутри блока <transmissions-api>
То же имя ещё 2:<inline-seeding><signals><transmissions-api>— часть из них другие настройки, часть та же самая
Пропуск в подачу по HTTP

Строка задаёт ключ для приложений, подающих почту через Transmissions API. Приложение передаёт его в заголовке Authorization, и с верным ключом получает право пользоваться этим входом.

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

Требование к значению руководство ставит жёсткое: буквы, цифры и подчёркивание, длиной от 32 до 128 знаков.

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

Главная ловушка — один ключ на всех. Возможность завести несколько ключей существует ровно ради отзыва: приложение, которому доверять перестали, лишается доступа снятием одной строки. С единственным ключом отзыв означает смену ключа у всех сразу — то есть остановку всей подачи по API.

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

Что делает Хаб. Не пишет: блока Transmissions API в его конфигурации нет вовсе — подача идёт обычным SMTP под логином.

Ключ, который Хаб действительно выписывает, — другой: http-api-key для веб-монитора и HTTP API управления. Их легко перепутать по названию, но это разные входы с разными правами.

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

Что ставить. Значение — сам ключ; правила приходят из требования руководства и из здравого смысла:

Свойство Почему
32–128 знаков, буквы, цифры, подчёркивание требование MTA: короче или с другими символами он не примет
случайный ключ передаётся заголовком и лежит в файле открытым
свой на приложение иначе отзыв одного доступа останавливает все

Строк в блоке должно быть столько, сколько приложений подаёт, — это не избыточность, а единственный способ отзыва.

Заголовок Authorization, повторяемость директивы и требования к значению — из руководства, § 3.3.20.1. Совет о ключе на приложение — наш, по тем же соображениям, что и с паролями логинов.
Пример в конфигурации
# по ключу на приложение — иначе отзыв одного останавливает все
<transmissions-api>
    api-key 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf    api-key 476d2e5b1d2bad079bf14ac5499cfdd2bb2859e4
</transmissions-api>
Снятие одной строки отзывает доступ у одного приложения. Остальные продолжают работать, и менять у них ничего не нужно.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

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

§ 3.3.20.1

Чем чреватоОтозвать доступ одному приложению нельзя: смена ключа останавливает подачу у всех разом. Возможность повторять директиву существует именно ради этого.
Как заметитьВ блоке одна строка ключа, а подающих приложений несколько.
Как правильноЗавести по ключу на приложение и раздать их порознь.

Берут короткий или «читаемый» ключ

§ 3.3.20.1

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

Путают этот ключ с ключом управления

наш опыт

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

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

2 связи

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

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

То же имя в других блоках

http-api-keyGlobalКлюч другого входа — веб-монитора и HTTP API управления; названия похожи, права разные. § 3.3.20.1

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

tls-certificate<transmissions-api-listener>Шифрование доказывает, кто слушатель; ключ доказывает, кто клиент. Вход по API требует и того и другого. § 8.1

Как проверить на узле
Ключи видно в конфигурации; проверять стоит и права на файл:
grep -c '^ *api-key ' /etc/pmta/config
ls -l /etc/pmta/config
Первая команда показывает, сколько ключей заведено; единица при нескольких подающих приложениях означает, что отозвать доступ одному нельзя. Вторая — что файл с ключами закрыт от посторонних.
◇

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

3 статьи

◇Как письмо попадает в MTAШесть описанных способов подачи: расширенный SMTP, четыре языковые обвязки и каталог, за которым узел следит на диске.◇Кому разрешено сдавать почту и для кого её приниматьИз коробки узел принимает подачу только с самой машины; два разных вопроса — «кто может слать через нас» и «на чьи адреса мы принимаем» — решаются разными директивами.◇Заголовки, которыми отправитель управляет доставкойШесть служебных заголовков позволяют подающей стороне выбрать поток, пометить письмо заданием, задать настройки и ключ подписи, идентификатор конверта и расписание; каждый разрешается отдельно и по источникам.

В Хабе
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Подключить платформу отправки
Соседние настройки блока <transmissions-api>:max-message-sizelog-datalog-requestslog-tlsВсе 5 директив блока →