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

domain-key

Globalкритично

Ключ подписи DKIM или ARC для домена отправки
в конфигурации это строкаdomain-keyвнутри блока Global
То же имя ещё 3:<domain-key-list>Global<virtual-mta><virtual-mta-pool>— часть из них другие настройки, часть та же самая
Ключ подписи для домена отправки

Связывает три вещи: селектор, домен отправки и приватный ключ — из файла или из хранилища секретов. Объявлений может быть сколько угодно, и они образуют набор, из которого узел выбирает при подписи.

Выигрывает первое подходящее объявление. Узел идёт по списку сверху вниз и берёт первый ключ, чей домен совпал с доменом подписи или является для него родительским. Ключ для example.com подойдёт письмам с mail.example.com, обратное неверно. Ключи внутри <virtual-mta> сильнее общих.

Селектор — это имя записи в DNS. Публичная часть публикуется как <селектор>._domainkey.<домен>, и именно по ней получатель находит ключ. Пара «селектор и домен» должна совпадать с точностью до символа.

Главная ловушка — ротация ключа. Нельзя заменить файл под тем же селектором: письма, стоящие в очереди, подписаны старым ключом, и снятие записи из DNS ломает их проверку у получателя. Ротация — это новый селектор, ожидание, и только потом снятие старого.
Что делает Хаб. Пишет — но не в корне файла, а в блоке адреса отправки: у каждого потока свой ключ. Сами ключи держит на карточке домена в разделе «DNS → Домены и зоны», публикует записи и раскладывает объявления по узлам. Ротация делается по правилам: новый селектор, ожидание опустошения очередей, снятие старого. Срок ожидания считается от bounce-after.
Рекомендуемые значения

Звёздочку — последней. Объявление с доменом * подходит любому письму, а перебор идёт сверху вниз: поставленное выше, оно перехватит письма, для которых ниже лежит точный ключ. Руководство советует ровно это.

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

Два ограничения подстановочного пути. Поддомены он не ловит, а селектор и домен в нём приводятся к нижнему регистру — хранилище к регистру чувствительно, и путь в нём надо создавать строчными.

Порядок объявлений — из рекомендаций руководства; правило про ротацию наше. Из руководства здесь состав строки, правило первого совпадения, приоритет ключей потока и оба ограничения подстановочного пути.
Пример в конфигурации
# точные домены выше, звёздочка последней
domain-key m, mail.port25.com, /etc/pmta/m.pem
domain-key k1, example.org, /etc/pmta/k1.example.org.pemdomain-key base, *, /etc/pmta/base.pem
Обе первые строки из руководства, пути приведены к нашей платформе. Порядок здесь и есть настройка: первое подходящее объявление выигрывает.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

Ставят звёздочку выше точных объявлений

§ 3.3.1.55.1

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

Заменяют файл под тем же селектором

наш опыт

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

Полагаются на подстановочный путь в хранилище для поддоменов

§ 3.3.1.55.1

Чем чреватоТакой путь поддомены не ловит — руководство говорит об этом отдельно. Письма с поддоменов остаются без ключа, хотя для родительского домена он находится.
Как заметитьПодписаны письма с основного домена, с поддоменов — нет.
Как правильноЗаводить поддоменам собственные объявления либо пользоваться обычным путём к файлу.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
domain-key SELECTOR, { DOMAIN | * }, { FILENAME | {vault}:PATH:KEY }
domain-key {selector}, {domain}, {vault}:/path/with/${selector}/and/${domain}
Значения
три значения через запятую — селектор, домен или звёздочка, путь к файлу либо ссылка на хранилище секретов
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
Global, <virtual-mta>
Сколько раз
можно повторять
Всё здесь — из руководства, с разделом.
Наследование
Строка уровня узла: пишется в корне файла и действует на всю почту. Объявления внутри <virtual-mta> имеют приоритет над общими: при совпадении на обоих уровнях выигрывают ключи потока. То же объявление можно собрать в именованный список — блок <domain-key-list> — и выбирать его заголовком письма. Подхватывается по pmta reload.
⇄

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

4 связи

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

domain-macroGlobalОдно объявление может покрыть множество доменов — через макрос. § 3.3.1.55.1

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

Внешнее хранилище секретовКлюч может лежать не на диске, а в хранилище секретов. Тогда вместо пути пишется ссылка, в том числе с подстановкой селектора и домена. § 3.3.1.55.1

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

Сменить ключ подписи, не прерывая отправкуСтрока, которую порядок смены ключа добавляет и убирает. § 1.6.2Как узел подписывает письма и выбирает ключПравило выбора ключа целиком — вместе с приоритетом потоков и поведением при отсутствии совпадения. § 3.3.1.55.1

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

Заголовки, которыми отправитель управляет доставкойЗаголовок с ключом подписи подменяет объявленные ключи на одно письмо. § 3.3.7.46process-x-dkim-options<source>Заголовок выбирает среди ключей, объявленных этой директивой, и не может назвать ключ, которого нет. § 3.3.7.45dkim-sign<domain>Ключи должны быть настроены, иначе включение подписи ничего не даёт — руководство говорит это прямо. § 3.3.10.18dkim-identity<domain>Домен объявления и есть домен подписи; имя подписи обязано совпадать с ним или быть его поддоменом. § 3.3.10.27arc-sign<domain>Ключи должны быть настроены, иначе включение ничего не даёт. § 3.3.10.30domain-key<virtual-mta>Определение строки целиком — состав, правило выбора, работа с хранилищем секретов. § 3.3.1.55.1

Как проверить на узле
Опубликована ли публичная часть, проверяется запросом к DNS; какой ключ достался письму — по заголовку подписи:
dig +short TXT k1._domainkey.example.org
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -5
В заголовке подписи селектор стоит в поле s=, домен — в d=: по ним и сверяют, то ли объявление выиграло. Хаб порядок объявлений выстраивает сам.
◇

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

3 статьи

◇Как узел подписывает письма и выбирает ключКлюч выбирается по домену отправки из заголовков, перебором объявлений сверху вниз.◇Заголовки, которыми отправитель управляет доставкойШесть служебных заголовков позволяют подающей стороне выбрать поток, пометить письмо заданием, задать настройки и ключ подписи, идентификатор конверта и расписание; каждый разрешается отдельно и по источникам.◇Щадящий режим — вторая личность очередиОчередь, которой приёмник начал отказывать, переключается на параллельный набор лимитов, повторов и маршрутов — десять директив, действующих только в этом режиме.

В Хабе
Управляется
DNS → Ключи подписи
Цена ошибки
опасно: последствия переживут откат
Сценарии
Ротация адресов отправки · Ротация ключей · Подпись и аутентификация писем
Важность
критично
Соседние настройки блока Global:http-accesshost-namesmtp-source-hostpostmastersmtp-proxy-source-hostВсе 108 директив блока →