# Добавление удостоверяющего центра

Чтобы **Webim Server** доверял нестандартному сертификату, соответствующий удостоверяющий центр (УЦ, CA) нужно добавить в хранилище, которым реально пользуются процессы **Webim Server**. Одной команды `update-ca-certificates` часто недостаточно: системные компоненты (`openssl`, `curl`) и библиотеки Python (`requests`, `httpx`, `certifi`) читают разные наборы УЦ.

Эту процедуру выполняют и для [входящих](https://webim.ru/kb/devops/tls-certificates/incoming.html), и для [исходящих](https://webim.ru/kb/devops/tls-certificates/outgoing.html) соединений. Меняется только состав файлов УЦ.

!!! Warning "Важно"
    Отключать проверку сертификатов (`smtp_skip_ssl_checks`) вместо добавления УЦ не рекомендуется. Так можно скрыть подмену сертификата и другие атаки на канал.

## Что понадобится

  * права администратора на сервере Webim;

  * актуальные версии пакетов `ca-certificates` и `openssl` (есть в типовой установке Debian 12.5, см. [требования к ПО](https://webim.ru/kb/devops/sys-reqs-for-server/sys-reqs-server-sw.html));

  * файлы УЦ в формате PEM, по одному сертификату в файле, с расширением `.crt`.

Проверьте формат:

```
grep -c -- '-----BEGIN CERTIFICATE-----' custom-ca.crt
openssl x509 -inform PEM -in custom-ca.crt -noout -subject -issuer -dates
```

В каждом файле должна быть ровно одна строка `BEGIN CERTIFICATE`. Если файл в бинарном формате DER, преобразуйте его:

```
openssl x509 -inform DER -in custom-ca.cer -outform PEM -out custom-ca.crt
```

## Почему одного системного хранилища мало

| Кто проверяет сертификат                           | Откуда берёт УЦ                                       | Обновляется `update-ca-certificates` |
|----------------------------------------------------|-------------------------------------------------------|--------------------------------------|
| `openssl`, `curl`, часть системных утилит          | `/etc/ssl/certs/ca-certificates.crt`                  | Да                                   |
| Модуль `ssl` в Python (зависит от сборки)          | пути OpenSSL, см. `ssl.get_default_verify_paths()`    | Обычно да                            |
| `requests`, `httpx` и другие библиотеки с `certifi` | собственный файл `cacert.pem` внутри пакета `certifi` | **Нет**                              |

Компоненты **Webim** используют `requests` и `httpx`. Поэтому после добавления УЦ в ОС нужно либо направить эти библиотеки на системный набор, либо дописать УЦ в файл `certifi`. Первый способ устойчивее: обновление пакета `certifi` не затирает настройку.

## Установка на хост (без Docker) {: #install-on-host }

  1. Скопируйте файлы УЦ в каталог локальных сертификатов. Один сертификат — один файл с расширением `.crt`:

    ```
    sudo install -d -m 0755 /usr/local/share/ca-certificates/webim
    sudo install -m 0644 custom-ca.crt /usr/local/share/ca-certificates/webim/
    ```

  1. Обновите системное хранилище:

    ```
    sudo update-ca-certificates
    ```

    При первом добавлении утилита обычно сообщает `1 added`. Повторный запуск может вывести `0 added`.

  1. Направьте библиотеки Python на системный набор. Для systemd-служб **Webim** создайте drop-in, например `/etc/systemd/system/webim-tornado.service.d/tls.conf` для **Chat Backend** и аналогичный файл для **Admin Backend**:

    ```
    [Service]
    Environment=SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
    Environment=REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
    Environment=CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
    ```

    Затем:

    ```
    sudo systemctl daemon-reload
    sudo systemctl restart webim-tornado
    sudo systemctl restart webim-admin-backend
    ```

    Если в Вашей установке имена служб другие, задайте те же переменные в их unit-файлах или в окружении процессов **Chat Backend** и **Admin Backend**.

  1. Проверьте, что УЦ попал в системный набор и что Python видит тот же файл:

    ```
    ls /etc/ssl/certs | grep -i custom
    python3 -c "import ssl; print(ssl.get_default_verify_paths())"
    python3 -c "import os; print(os.environ.get('SSL_CERT_FILE')); print(os.environ.get('REQUESTS_CA_BUNDLE'))"
    ```

Переменные окружения должны быть заданы **у процесса Webim**, а не только в Вашей терминальной сессии.

### Запасной способ: дописать УЦ в certifi

Если задать переменные окружения нельзя, добавьте УЦ в файл пакета `certifi`. Путь зависит от окружения Python:

```
python3 -c "import certifi; print(certifi.where())"
```

Пример:

```
CERTIFI_BUNDLE="$(python3 -c 'import certifi; print(certifi.where())')"
sudo cp "$CERTIFI_BUNDLE" "${CERTIFI_BUNDLE}.bak"
cat custom-ca.crt | sudo tee -a "$CERTIFI_BUNDLE" >/dev/null
```

Этот файл перезаписывается при обновлении пакета или образа. После обновления Python-зависимостей или смены образа проверку нужно повторить.

## Установка в Docker {: #install-in-docker }

Здесь и далее подразумевается, что YAML от Docker Compose находится в `/etc/webim/docker-compose.yml`. При необходимости замените путь и имя на другое.

Хранилище УЦ хоста контейнерам **не передаётся**.

Для **Chat Backend** и **Admin Backend** подходят три способа ниже. Способ с готовым бандлом устойчив к пересозданию контейнеров и не требует менять `command` сервисов. Для **Delta Proxy** достаточно штатного импорта при запуске контейнера, см. [отдельное описание](#delta-proxy).

Подготовьте каталог на хосте и положите туда PEM-файлы с расширением `.crt`. Директорию `/etc/webim/extra-ca-certificates` **Webim Server** по умолчанию не читает, скрипты образов ждут файл `/etc/webim/ssl/ca-certificates.crt`. Том `/etc/webim` уже смонтирован в образы в стандартном Docker Compose YAML.

### Способ 1. Использовать скрипт start.sh (предпочтительный)

У Docker-образов стандартной поставки Webim есть entrypoint-скрипт `start.sh` (у компонентов **Chat Backend**, **Admin Backend**, **History Backend**, **Image Robot**).

Скрипт при старте берёт `/etc/webim/ssl/ca-certificates.crt` и вызывает `update-ca-certificates`. Достаточно положить УЦ в этот файл и перезапустить сервисы. Собирать полный системный набор по такой директории и добавлять volume напрямую на этот файл в Docker Compose YAML в этом случае не нужно — монтируется `/etc/webim/`.

### Способ 2. Смонтировать готовый PEM-бандл {: #docker-bundle }

Данный способ в стандартной поставке Webim не используется.

Держите исходные УЦ отдельными файлами (`custom-ca.crt`, `russian_trusted_root_ca_pem.crt`) и собирайте из них бандл явно — так в него не попадёт сам `ca-bundle.crt`.

  1. Возьмите системный набор **из контейнера** (он может отличаться от набора хоста) и допишите свои УЦ:

    ```
    docker compose -f /etc/webim/docker-compose.yml exec -T chat_backend \
      cat /etc/ssl/certs/ca-certificates.crt \
      | sudo tee /etc/webim/extra-ca-certificates/ca-bundle.crt >/dev/null
    sudo sh -c 'cat /etc/webim/extra-ca-certificates/custom-ca.crt \
      >> /etc/webim/extra-ca-certificates/ca-bundle.crt'
    ```

    Если УЦ несколько (например, корневой и выпускающий сертификаты Минцифры РФ), допишите каждый файл отдельной командой `cat … >>`.

    Если на хосте и в контейнере одна и та же Debian 12.5, можно сначала выполнить `update-ca-certificates` на хосте и взять за основу `/etc/ssl/certs/ca-certificates.crt` хоста. Если версии ОС или пакета `ca-certificates` различаются, берите базовый набор из контейнера.

  1. В `/etc/webim/docker-compose.yml` для **Chat Backend** и **Admin Backend** добавьте том и переменные окружения:

    ```
    volumes:
      - /etc/webim/extra-ca-certificates/ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt:ro
    environment:
      SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
      REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
      CURL_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
    ```

    Данные переменные по умолчанию заданы в Dockerfile образов (`/etc/ssl/certs/ca-certificates.crt`), представляют интерес, если их значения нужно изменить.

    При этом `CURL_CA_BUNDLE` в Dockerfile нет.

    Точные имена сервисов смотрите в выданном архиве `docker-compose`. Если у сервиса уже есть блок `environment` или `volumes`, допишите строки в него, а не создавайте второй одноимённый блок. Если исходящие запросы выполняет ещё один бэкенд, повторите настройку и для него.

  1. Примените конфигурацию:

    ```
    docker compose -f /etc/webim/docker-compose.yml up -d
    ```

После смены образа заново соберите бандл: базовый набор УЦ в новом образе может отличаться.

### Способ 3. Смонтировать отдельные УЦ и обновить хранилище в контейнере {: #docker-mount-certs }

Используйте, если стандартный `start.sh` почему-то не подходит и Вы хотите выполнить аналогичные действия самостоятельно.

Учитывайте, что по умолчанию эти изменения затрутся в последнем слое контейнера после рестарта.

  1. Смонтируйте каталог с файлами `.crt` в `/usr/local/share/ca-certificates/webim` контейнеров **Chat Backend** и **Admin Backend**.

  1. После создания контейнера выполните:

    ```
    docker compose -f /etc/webim/docker-compose.yml exec chat_backend update-ca-certificates
    ```

    Повторите для **Admin Backend** и остальных бэкендов, которые ходят наружу по HTTPS.

  1. Задайте те же переменные `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` и `CURL_CA_BUNDLE`, что и в способе 2, и перезапустите сервисы:

    ```
    docker compose -f /etc/webim/docker-compose.yml restart chat_backend
    ```

    Команда `restart` сохраняет изменения в файловой системе контейнера. Команды `down` / `up --force-recreate` и смена образа создают контейнер заново — `update-ca-certificates` нужно выполнить снова.

Способ 3 уместен для разовой проверки. Для постоянной эксплуатации надёжнее способ 1.

### Скрипт запуска бэкендов {: #docker-backends }

В образах бэкендов есть и штатный скрипт запуска (`start.sh`). Если при старте существует `/etc/webim/ssl/ca-certificates.crt`, скрипт копирует его в `/usr/share/ca-certificates/` и выполняет `update-ca-certificates`. Так устроены, в частности, **Chat Backend**, **Admin Backend**, **History Backend**, `image_robot`. Каталог `/etc/webim` в типовой поставке уже смонтирован в контейнеры.

  1. Положите PEM-файл с дополнительными УЦ в `/etc/webim/ssl/ca-certificates.crt` на хосте. Если УЦ несколько, объедините их в этот файл:

    ```
    sudo install -d -m 0755 /etc/webim/ssl
    sudo install -m 0644 custom-ca.crt /etc/webim/ssl/ca-certificates.crt
    ```

  1. Перезапустите контейнеры, чтобы скрипт запуска отработал снова:

    ```
    docker compose -f /etc/webim/docker-compose.yml restart chat_backend agent_backend
    ```

После смены образа файл на хосте остаётся на месте: новый контейнер снова прочитает его при старте. Если после `update-ca-certificates` библиотека `requests` всё ещё отвечает `CERTIFICATE_VERIFY_FAILED`, задайте процессу переменные `SSL_CERT_FILE` и `REQUESTS_CA_BUNDLE`, как в [установке на хост](#install-on-host).

Сертификат и ключ, которые **nginx** предъявляет клиентам, — это другие файлы. Их пути фиксированы в образе, см. [Входящие соединения](https://webim.ru/kb/devops/tls-certificates/incoming.html#install-in-docker).

### Delta Proxy {: #delta-proxy }

**Delta Proxy** — отдельный компонент (специальные сборки), который ходит на HTTPS-адрес аккаунта (`ROOT_URL_FORMAT`) как клиент. Production-образ запускается скриптом `start.sh`: Dockerfile добавляет его в `/usr/local/bin` и указывает в `CMD`. Если при старте существует `/etc/webim/ssl/ca-certificates.crt`, скрипт копирует его в `/usr/share/ca-certificates/` и выполняет `update-ca-certificates`. Скрипт задаёт `SSL_CERT_FILE` и `REQUESTS_CA_BUNDLE` равными `/etc/ssl/certs/ca-certificates.crt` и после этого запускает `poetry run python api.py`. Каталог `/etc/webim/ssl/ca-certs` тоже подхватывается: файлы из него копируются в `/usr/local/share/ca-certificates/`.

  1. Положите тот же PEM-файл `/etc/webim/ssl/ca-certificates.crt` на хост. Если в `docker-compose` для Delta Proxy уже смонтирован каталог `/etc/webim`, отдельный том не нужен. Иначе смонтируйте файл явно:

    ```
    volumes:
      - /etc/webim/ssl/ca-certificates.crt:/etc/webim/ssl/ca-certificates.crt:ro
    ```

  1. Перезапустите контейнер, чтобы скрипт запуска отработал снова:

    ```
    docker compose -f /etc/webim/docker-compose.yml restart delta_proxy
    ```

    Имя сервиса возьмите из Вашей поставки Delta Proxy.

Чтобы обновить сертификат, замените файл на хосте и перезапустите контейнер — пересобирать образ не нужно. После `down` / `up --force-recreate` или смены образа файл на хосте остаётся на месте: новый контейнер снова копирует его в хранилище УЦ при старте.

## Что не нужно делать

  * Не кладите в хранилище УЦ **закрытый ключ** серверного сертификата.

  * Для файлов в `/usr/local/share/ca-certificates/`: не кладите в каталог УЦ сразу всю цепочку одним файлом: `update-ca-certificates` ожидает один сертификат в каждом `.crt`. Готовый бандл из способа 2 и файл `/etc/webim/ssl/ca-certificates.crt` для скрипта запуска — отдельные случаи: туда как раз собирают несколько PEM-блоков.

  * Для штатного `/etc/webim/ssl/ca-certificates.crt` наоборот: в один файл можно дописать несколько PEM-блоков (корневой и промежуточный Минцифры РФ).

  * Не ограничивайтесь установкой УЦ в браузер администратора: процессы **Webim Server** этот набор не используют.

  * Не считайте достаточной установку только в хранилище хоста, если **Webim** работает в Docker: контейнер должен увидеть УЦ через один из способов выше.

  * Не путайте файл дополнительных УЦ (`/etc/webim/ssl/ca-certificates.crt`) с сертификатом и ключом **nginx** (`/etc/webim/ssl/server.crt`, `/etc/webim/ssl/server.key`).

Дальше вернитесь к сценарию, из-за которого Вы добавляли УЦ: [входящие соединения](https://webim.ru/kb/devops/tls-certificates/incoming.html) или [исходящие соединения](https://webim.ru/kb/devops/tls-certificates/outgoing.html). Проверка и разбор ошибок — в статье [Диагностика ошибок TLS](https://webim.ru/kb/devops/tls-certificates/troubleshooting.html).

---

Источник: https://webim.ru/kb/devops/tls-certificates/adding-ca.html
