Перейти к основному содержимому

Сертификаты и HTTPS

MonoPbx управляет собственными сертификатами TLS: встроенный ACME (Let's Encrypt или любой центр сертификации по RFC 8555) с автоматическим продлением либо загруженные вами сертификаты. Каждая компания в установке с несколькими компаниями может иметь собственный сертификат для своего веб-адреса <slug>.<base domain>.

Значения по умолчанию​

HTTPS использует самоподписанный сертификат, пока не будет выпущен или загружен настоящий сертификат, поэтому установка доступна с первого запуска. Центр сертификации не обращаются, пока вы не настроите каталог ACME; при его настройке вы принимаете соглашение абонента этого центра.

Настройка​

Страница сертификатов с кнопками запроса и загрузки.

Страница «Сертификаты».

При установке на виртуальной машине команда --domain pbx.example.com --accept-acme-terms записывает это за вас и открывает порты 80 и 443. Сам установщик не обращается к центрам сертификации. Вручную настройки такие:

[http]
base_domain = "pbx.example.com"          # company addresses are <slug>.pbx.example.com

[tls]
listen = "0.0.0.0:443"
http_listen = "0.0.0.0:80"               # ACME HTTP-01 answers and redirect to HTTPS
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"
acme_contact = "hostmaster@example.com"  # optional expiry notices

Любой ключ также работает как переменная окружения (MPBX__TLS__LISTEN и так далее).

Let's Encrypt (ACME)​

Порты 80 и 443 должны быть доступны серверу, а имя должно разрешаться в его адрес (HTTP-01). Запросите сертификат через API, от имени владельца системы или администратора системы:

POST /api/v1/system/certificates/acme    {"domains": ["pbx.example.com"]}     -> 202, status "pending"
POST /api/v1/certificates/acme           {}     (a company admin: the company's own address) -> 202

Модуль продления выпускает его в течение минуты. Wildcard-сертификаты требуют DNS-01, который пока не реализован: загрузите вместо этого wildcard-сертификат (*.pbx.example.com обслуживает адреса всех компаний).

Сертификаты продлеваются автоматически в момент not_after - min(30 days, lifetime / 3). Неудачное продление повторяется через 10 минут, с удвоением интервала до 12 часов, а сертификат в работе всё это время остаётся в работе. POST /api/v1/system/certificates/{id}/renew продлевает сертификат немедленно.

Загрузка собственного сертификата​

POST /api/v1/system/certificates   {"certificate_chain_pem": "...", "private_key_pem": "..."}
POST /api/v1/certificates          (a company: must cover <slug>.<base domain>)

Цепочка начинается с конечного сертификата (leaf), затем идут промежуточные. Прежде чем что-либо сохранить, сервер проверяет синтаксис PEM, порядок цепочки и подписи, соответствие ключа конечному сертификату, действительность конечного сертификата на текущий момент и наличие DNS-имён. Повторная загрузка под тем же именем заменяет сертификат. Закрытый ключ доступен только для записи: он хранится в зашифрованном виде и никогда не возвращается. Загрузки не используют Idempotency-Key.

POST /api/v1/system/certificates/{id}/default назначает сертификат установки сертификатом по умолчанию.

Какой сертификат получает соединение​

  1. Сертификат компании, адрес которой запросил клиент. Сертификат компании обслуживается только для адреса этой компании.
  2. Сертификат установки с точно таким именем.
  3. Wildcard-сертификат установки, который его покрывает.
  4. Сертификат по умолчанию (если имя сервера не указано, передан IP-адрес или неизвестное имя), иначе самоподписанный сертификат.

Сертификаты перезагружаются на каждом узле примерно за 10 секунд без перезапуска. Истекшие сертификаты продолжают обслуживаться, пока продление не удаётся, а оповещения сообщают о них.

Мониторинг​

Метрики: mpbx_tls_cert_expiry_seconds, mpbx_tls_cert_renewal_failures, mpbx_tls_cert_renewals_total, mpbx_tls_certs. В репозиторий входят правила оповещений Prometheus для сертификатов, срок действия которых истекает менее чем через 14 дней и менее чем через 3 дня, а также для повторных неудачных продлений.

Права и аудит​

Маршруты установки (/system/certificates...) требуют system.settings:read или system.settings:write. Загрузки сертификатов, запросы ACME, продления, удаления, выбор сертификата по умолчанию и результаты выпуска записываются в журнал аудита с именами и отпечатками, но никогда не с ключевым материалом.

Загрузки сертификатов через командную строку нет; используйте API.