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

tls-certificate

<transmissions-api-listener>

Сертификат, который вход Transmissions API предъявляет клиентам
в конфигурации это строкаtls-certificateвнутри блока <transmissions-api-listener>
То же имя ещё 2:<smtp-listener><smtp-user><transmissions-api-listener>— часть из них другие настройки, часть та же самая
Единственная обязательная строка входа по API

Transmissions API — второй способ подать письмо в MTA, кроме SMTP: клиент шлёт POST с телом JSON. Вход объявляется блоком <transmissions-api-listener> на своём адресе и порту, и эта строка задаёт сертификат, который он предъявляет.

Строка обязательна, и это главное отличие от подачи по SMTP. Руководство пишет прямо: разговор с клиентами идёт по HTTPS, и сертификат нужен каждому входу (§ 8.1.1); в примере оттуда так и помечено — обязательна она одна, остальные строки блока необязательны. Незашифрованного пути у этого входа нет вовсе — в отличие от подачи по SMTP, где STARTTLS можно и не начинать.

Самоподписанный делается своим инструментом MTA: pmtakeytool newcert > /etc/pmta/transmissions-api-certificate.pem. Настоящий от удостоверяющего центра подставляется в ту же строку.

Пароль и сам сертификат могут лежать в хранилище — запись {vault}:ПУТЬ/КЛЮЧ вместо пути к файлу, как у smtp-server-tls-certificate.

Главная ловушка — забыть про пароль второй частью строки. Сертификат с зашифрованным ключом без пароля MTA не прочитает, а пароль, записанный рядом, попадает в конфигурацию открытым текстом и в её резервные копии. Либо ключ без пароля и права на файл, либо хранилище.
Что делает Хаб. Не пишет: подача у нас идёт по SMTP на отдельный порт, блока входа по API в конфигурации нет вовсе.

Стоит держать в уме при разговоре о втором способе подачи: у API шифрование не выбирается — оно есть всегда. Ту дыру, что нашлась на подаче по SMTP (пароль может уйти открытым текстом), здесь устроить нечем.

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

Выбор — откуда берётся сертификат:

Значение Когда
путь к PEM обычный случай
путь к PEM плюс пароль ключ зашифрован, хранилища нет
{vault} ключи парка отзываются в одном месте

Умолчания нет: без этой строки вход по API не поднимется.

Синтаксис с хранилищем — из руководства (§ 3.3.21.1), обязательность строки и рецепт pmtakeytool — из главы 8 (§ 8.1.1, § 8.1.2). Замечание про пароль в резервных копиях — наше.
Пример в конфигурации
# вход по API: обязательна одна строка, остальные необязательны
<transmissions-api-listener 1.2.3.4:8585>
    tls-certificate /etc/pmta/transmissions-api-certificate.pem</transmissions-api-listener>

<transmissions-api>
    api-key 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
</transmissions-api>
Два блока работают только вместе: вход даёт шифрование, ключ — право подавать. Порт в примере руководства 8585, но он произвольный.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

Поднимают вход по API без сертификата

§ 8.1.1

Чем чреватоРазговор идёт по HTTPS, и без сертификата предъявлять нечего. Вход не заработает — это не «шифрование выключено», а неработающий вход.
Как заметитьБлок в конфигурации есть, клиент не подключается.
Как правильноЗадать сертификат — свой или самоподписанный через pmtakeytool newcert.

Пишут пароль к ключу второй частью строки

наш опыт

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

Проверяют самоподписанный сертификат обычным клиентом

§ 8.1.4

Чем чреватоКлиент отказывается: цепочка не проверяется. Выглядит как неработающий вход, хотя вход исправен.
Как заметитьОшибка проверки сертификата вместо ответа API.
Как правильноНа время проверки — –insecure у curl, как в примере руководства. Постоянное решение — сертификат от центра.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
tls-certificate { FILENAME | {vault}:PATH/KEY } [PASSWORD | {vault}:PATH/KEY]
Значения
путь к файлу PEM или ключ хранилища, вторым словом — пароль
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<transmissions-api-listener>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строка действует внутри своего <transmissions-api-listener> — на его адрес и порт. Входов может быть несколько, и у каждого сертификат свой. С блоком почтового слушателя связи нет никакой: это разные входы, а не уровни одного.
⇄

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

2 связи

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

tls-certificate<smtp-listener>Одноимённая строка у слушателя почты; здесь она про отдельный вход, свой у API. § 3.3.21.1

Работают в паре

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

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

tls-ca-file<transmissions-api-listener>Одна строка говорит, кто этот вход; другая — чьим клиентским сертификатам он верит. inference

Как проверить на узле
Смотрим, какой сертификат предъявляет вход, — порт берём из своего блока:
openssl s_client -connect NODE:8585 -brief </dev/null
Peer certificate: CN=… показывает предъявленный сертификат, verify error:num=18 — что он самоподписанный. Полную подачу проверяют запросом: curl –insecure -H “Authorization: КЛЮЧ” -H “Content-Type: application/json” –data @msg.json https://NODE:8585/api/v1/transmissions.
◇

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

3 статьи

◇Кому разрешено сдавать почту и для кого её приниматьИз коробки узел принимает подачу только с самой машины; два разных вопроса — «кто может слать через нас» и «на чьи адреса мы принимаем» — решаются разными директивами.◇Группа, дающая право управлятьЧленство в группе pmta даёт непривилегированному пользователю право звать команды узла и пользоваться подачей.◇Как узел выбирает источник и складывает его настройкиСоединение попадает под все блоки источника, чьи адреса его накрывают, и действуют они слитно — узкий перекрывает широкий; именованные блоки подключаются только по прямой ссылке.

В Хабе
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Безопасность узла
Соседние настройки блока <transmissions-api-listener>:tls-min-versiontls-max-versiontls-ca-filetls-cipher-server-preferencetls-ciphersВсе 15 директив блока →