Подключение сертификата

Оглавление

Обзор
Порядок применения сертификатов
- SNI
Способы настройки

Обзор

Сертификаты используются для установки защищенных соединений. В тестовой системе сертификат может понадобиться для подключения к системе веб-софтфона из браузера.

Существует несколько случаев:

Мастер-домен совпадает с публичным DNS-именем, и DNS-сервер связывает его с адресом сервера платформы.
Имя одного из рабочих доменов системы связывается DNS-сервером с адресом сервера платформы.
Мастер-домен совпадает с публичным DNS-именем, но DNS-сервер не связывает его с адресом сервера платформы.
Имена всех логических доменов платформы, начиная с мастер-сервера, являются локальными.

Основные варианты настройки случаев 1 и 2:

Автоматическая выписка сертификата с помощью сервиса ACME через серверы LetsEncrypt.
Выписка сертификата вручную или взятие готового сертификата и подключение его к системе через конфигурацию. Потребуется обновление сертификата по истечении срока его действия.

При этом обращения на сервер должны производиться по публичным доменным именам, которые связываются DNS-сервером с платформой и для которых выписан/загружен/настроен сертификат.

Ситуация 3 настраивается так же как ситуация 4, несмотря на возможно настраиваться путем загрузки имеющегося сертификата и подключения его к системе через конфигурацию.

Ситуация 4 может настраиваться путем выписки самоподписного сертификата для доменного имени мастер-домена и подключения его к системе через конфигурацию. При этом на локальном DNS либо в файле hosts клиентских машин необходимо устанавливать связь IP-адреса сервера платформы c именем мастер-домена. А в браузерах придется добавлять имя в исключения по безопасности.

За две недели до истечения срока действия текущего сертификата мониторинг состояния системы начнет сигнализировать.

Порядок применения сертификатов

Сначала делается попытка применить сертификат по SNI.
При неудаче применяется сертификат, заданный в конфигурации в параметре 'certdir' той роли (экземпляра микросервиса), что обслуживает этот запрос - ws или sg.
В последнюю очередь, если в конфигурации не задан или задан некорректно параметр 'certdir', то применяется поставляемый с платформой сертификат по умолчанию.

SNI

Если в доменном дереве платформы нашелся домен, соответствующий по имени SNI, а в нем задан параметр 'certificate_pem', то применяется его значение.

Если же параметр 'certificate_pem' в найденном по SNI домене не задан, то осуществляется поиск в родительском домене, и так вплоть до мастер-домена.

Если нигде в родительских доменах вплоть до мастер-домена не задан параметр 'certificate_pem', то поиск сертификата по SNI прекращается.

Если в доменном дереве платформы не найден домен, соответствующий по имени SNI, то поочередно проверяются все родительские имена относительно полученного SNI-имени. Последним в любом случае проверяется мастер-домен. Как и выше, если в каком-то из обнаруженных в доменном дереве платформы доменов задан параметр 'certificate_pem', то применяется его значение. В противном случае поиск сертификата по SNI прекращается.

Способы настройки

1. ACME LetsEncrypt

Необходимые условия:

В доменном дереве существует домен, чье имя известно публичным DNS-серверам и связывается с публичным IP-адресом сервера текущего экземпляра платформы, либо публичным IP-адресом локального раутера.
Сервер имеет выход в интернет.
Обращение из интернет по доменному имени на порт 80 по http не блокируется раутерами и файрволлами и маршрутизируется на сервер платформы.
Адресуемый сервер содержит микросервис WS, который слушает порт 80 (или другой, если раутер производит подмену портов).

В подходящем домене необходимо в настройках задать опцию acme_account_email и включить опцию acme_enabled.

Через некоторое время в опции certificate_pem появится PEM-содержимое сгенерированного сертификата. При этом в заголовке появятся несколько специальных полей, указывающих на автоматическую выписку сертификата.

В дальнейшем при обращении по доменному имени платформа будет использовать сертификат текущего домена.

Сертификат выписывается сроком на 3 месяца, и система приступает к автоматическому его обновлению через 2 месяца.

Выписка сертификатов обеспечивается микросервисом mware, и поэтому информация о процессе обновления и возможных неудачах размещается в его лог-журнале.

2. Загрузка готового сертификата на диск и подключение через конфигурацию

Сформируйте из имеющихся сертификатов файлы server.key и server.crt.
Разместите их на диске в том месте, где они будут в безопасности и сохранности. Например, каталог syncroot/common/cert (внутри контейнера это /var/lib/era_files/syncroot/common/cert, в хосте в зависимости от выбранных при установке путей, по умолчанию /opt/era/syncroot/common/cert). Он недоступен из API, и автоматически синхронизируется между всеми серверами платформы, что дает возможность скопировав его на один сервер использовать на любом сервере системы.
Убедитесь, что в конфигурационном файле в разделе алиасов есть соответствующий алиас, указывающий на используемую вами папку внутри контейнера. Например, для предложенного в пункте 2 пути:
```
{
  "alias": "default_certdir",
  "value": "/var/lib/era_files/syncroot/common/cert"
}
```
Установите всем экземплярам микросервисов WS и SG конфигурационную опцию использования сертификата из конфига, указывающую на созданный ранее алиас. Например:
```
  "certdir": "alias://paths/default_certdir"
```
Активируйте измененную конфигурацию.

Сертификат, загруженный в домен в поле certificate_pem, при обращении к серверу через это доменное имя имеет приоритет перед сертификатом, установленным через конфигурацию.

3. Загрузка готового сертификата в домен

Необходимо сформировать объединенное содержимое: Сначала ключ, потом сертификат, потом цепочка сертификатов (при наличии). В домен, чье имя совпадает с доменным именем сертификата, следует вставить содержимое сертификата в опцию certificate_pem.

Пример содержимого:

date=2023-11-29
-----BEGIN RSA PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCczvGDUx8MMwnj
v+CUjlyDRZ9pbI7veOTWgq/mj+f+aw6zHyjERIGv7x9lFTF/zoPSUxf4CxHiPjid
...
N7oVoQ2dzIe9rjkLPrwKf+o3QfMnsotrE773dc67om2ynrY2fJIoa5TzVEtcB6A0
2+XrTNfre/PEPz3+uL2WCVja
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIE6zCCA9OgAwIBAgISBPPhdaDZBu7SUParH1/Pb1QqMA0GCSqGSIb3DQEBCwUA
MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD
...
SKDVqkLi0yhp3LpS0OYRMrQddVtxS4tqInxGSt0CvIK5xeOB3abY5ShW0JYYUARz
YR7I9fkBPg4p+b9KxrfG
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFFjCCAv6gAwIBAgIRAJErCErPDBinU/bWLiWnX1owDQYJKoZIhvcNAQELBQAw
TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
...
MldlTTKB3zhThV1+XWYp6rjd5JW1zbVWEkLNxE7GJThEUG3szgBVGP7pSWTUTsqX
nLRbwHOoq7hHwg==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFYDCCBEigAwIBAgIQQAF3ITfU6UK47naqPGQKtzANBgkqhkiG9w0BAQsFADA/
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
...
he8Y4IWS6wY7bCkjCWDcRQJMEhg76fsO3txE+FiYruq9RUWhiF1myv4Q6W+CyBFC
Dfvp7OOGAN6dEOM4+qR9sdjoSYKEBpsr6GtPAQw4dy753ec5
-----END CERTIFICATE-----

При этом перед каждым разделом в заголовке может содержаться или не содержаться мета-информация, например:

Bag Attributes
    localKeyID: 01 00 00 00
    1.3.6.1.4.1.311.17.3.20: 9E D3 D5 AE 59 ED 75 B8 B7 87 6D 7F 60 46 23 F4 01 BA E7 AA
    friendlyName: [IIS] era, (any host) @ 2021.4.6 21:29:54
subject=/CN=era-platform.ru
issuer=/C=US/O=Let's Encrypt/CN=R3

Если у вас имеются несколько файлов, например domain.key, domain.crt, ca.pem, то чтобы сформировать требуемое значение, необходимо сцепить их в следующем порядке: сначала приватный ключ (key), затем сам сертификат, и затем цепочка сертификатов (ca).

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

При обращении к серверу по доменному имени, наличии этого домена среди доменов платформы и отсутствии в домене установленного сертификата в поле certificate_pem, производится его поиск в родительском домене вплоть до мастера.

При обнаружении где-либо в родительских доменах установленного сертификата certificate_pem, он применяется.

Если ни в одном из родительских доменов сертификат не установлен в поле certificate_pem, то применяется сертификат из конфигурации.

Поэтому, если планируется обращаться к дочерним доменам по их именам в URL, следует:

либо устанавливать собственные сертификаты для каждого из таких доменов;
либо в родительский домен добавлять поддержку всех таких дочерних доменов в поле acme_subdomains;
либо использовать wildcard сертификат, который накрывает все такие дочерние домены, и загружать его в мастер-домен или один из корневых доменов;
либо использовать wildcard сертификат, который накрывает все такие дочерние домены, и использовать его через конфигурационную настройку.

4. Выписка самоподписного сертификата для локального доменного имени

Команда для выписки сертификата с помощью утилиты openssl:

openssl req -newkey rsa:2048 -nodes -keyout server.key -x509 -days 1095 -out server.crt

В ходе исполнения команды потребуется ввести целевое доменное имя. Преимущественно это имя мастер-домена.

В результате выполнения команды появляются файлы server.key и server.crt

Если планируется их загружать на диск, то их имена должны быть именно такими: server.key, server.crt, поскольку в конфигурации устанавливается лишь каталог, где размещены эти файлы.

Если планируется их устанавливать в параметр домена certificate_pem, то следует сформировать объединенное тело: сначала содержимое server.key, затем содержимое server.crt.

При использовании локального имени необходимо обеспечить его связывание с IP-адресом сервера на клиентских машинах:

либо через файл hosts (linux: /etc/hosts, windows: windows/system32/drivers/etc/hosts),
либо через локальный DNS-сервер.

При использовании самоподписного сертификата необходимо в браузерах доменное имя добавлять в исключения по безопасности.