Wiki

Отпечаток TLS

Сервер создаёт самоподписанный сертификат при установке. Каждый клиент подтверждает его отпечаток при первом соединении.

Это безопасно? Да. Все соединения и все передачи файлов зашифрованы: никто в сети не может прочитать то, что передаётся между вашими рабочими станциями и вашим сервером. Ваши данные остаются в вашей собственной инфраструктуре: ничего не размещается у третьих лиц и ничего не проходит через uVersion. Доступ есть только у участников вашей команды с их собственными учётными данными. А если в соединении происходит что-то необычное, программа это обнаруживает и немедленно блокирует, вместо того чтобы молча пропустить.

uVersion по умолчанию шифрует все соединения по HTTPS, без доменного имени и без купленного сертификата. Сервер создаёт свой сертификат при первом запуске, администратор делится его отпечатком с командой, и каждая рабочая станция подтверждает его один раз. Это модель TOFU: доверие при первом контакте, точно как SSH, когда он в первый раз просит вас сверить отпечаток машины. Затем клиент сверяет его при каждом соединении и отказывается общаться с сервером, который изменился.

Отпечаток сервера или контрольная сумма? И то и другое является SHA-256, и именно это всех сбивает с толку. Отпечаток сервера идентифицирует сертификат вашего сервера: он служит для того, чтобы распознать машину, к которой подключаются ваши рабочие станции. Контрольная сумма проверяет, что скачанный файл цел. Эта страница говорит только о первом.

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

Найти отпечаток

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

1. Из браузера, ничего не устанавливая

Сервер предоставляет информационную страницу без аутентификации: откройте https://ВАШ-СЕРВЕР:8443/api/server-info. Ни sudo, ни доступа по SSH, ни учётной записи uVersion: это, безусловно, самый короткий путь.

Браузер сначала показывает предупреждение безопасности. Это нормально и ожидаемо: сертификат самоподписанный, ни один публичный удостоверяющий центр его не знает. Продолжите переход на сайт.

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

Появляющаяся затем страница представляет собой необработанный блок данных. Отпечаток является значением поля tls_fingerprint: последовательность байтов в шестнадцатеричном виде, разделённых двоеточиями. Именно эту строку целиком вы передадите команде.

Страница /api/server-info, открытая в браузере: поля version, build_sha, tls_mode со значением self_signed и tls_fingerprint с отпечатком SHA-256 в шестнадцатеричном виде, разделённым двоеточиями.

Эта страница показывает то, что заявляет сервер Она идеальна, чтобы опубликовать отпечаток для вашей команды, ведь администратор здесь вы. Сама по себе она не является проверкой: тот, кто перехватил бы соединение, вернул бы своё собственное значение. Защищает именно сравнение, которое каждая рабочая станция делает между отпечатком, действительно предъявленным сервером, и тем, который вы передали ей по другому каналу (внутренний мессенджер, устно, командная вики). Клиент командной строки, кстати, делает и то и другое и предупреждает вас, когда они различаются.

2. Из журналов сервера

Сервер при каждом запуске заново записывает отпечаток в свои журналы. Этот способ работает независимо от того, куда вы поместили каталог данных:

# Linux (paquet .deb)
sudo journalctl -u uversion-server | grep "TLS fingerprint" | tail -1

# Docker
docker compose logs server | grep "TLS fingerprint" | tail -1

3. В файле `fingerprint`

Этот файл записывается рядом с сертификатом, то есть в каталоге [tls] cert_path, как он указан в вашем config.toml. Пути ниже являются значениями по умолчанию: если вы переместили каталог данных, сначала прочитайте cert_path в вашей конфигурации.

# Linux, dossier de donnees par defaut
sudo cat /var/lib/uversion/data/tls/fingerprint

# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

# Docker : chemin fixe par l'entrypoint, sur le volume de donnees
docker compose exec server cat /data/tls/fingerprint

Подтвердить на клиенте

Один раз на рабочую станцию, и раз и навсегда. Действие зависит от инструмента.

Настольный клиент

Заполните экран входа как обычно. При первом соединении с этим сервером вместо входа откроется окно Verify server identity. Сравните показанный отпечаток с тем, которым поделился ваш администратор, и нажмите Trust this server, если они совпадают: соединение сразу же продолжится само. Если они различаются, Cancel, и идите выяснять почему.

Окно Verify server identity настольного клиента: адрес сервера, полностью показанный отпечаток SHA-256, версия сервера и режим TLS, а затем кнопки Cancel и Trust this server.

CLI `uversion`

uversion trust https://uversion.example.com:8443          # interactif
uversion trust https://uversion.example.com:8443 --yes    # sans question (CI, script)
uversion trusted                                          # liste les serveurs epingles
uversion login <url>                                      # propose l'epinglage si besoin

uversion trust является интерактивным: он показывает хост, версию сервера, режим TLS и отпечаток, напоминает сравнить с тем, что передал администратор, а затем ждёт подтверждения y/N. Любой другой ответ отменяет, ничего не закрепляя. Опция --yes пропускает этот вопрос, для скрипта или непрерывной интеграции: она закрепляет без чьего-либо участия, и её стоит приберечь для сети, которую вы контролируете.

uversion login сам предлагает то же подтверждение, когда сервер ещё не закреплён: на рабочей станции обычно нечего запускать заранее.

Плагин Unreal Engine

Выполните uversion trust <url> один раз в терминале перед открытием проекта или сначала войдите из настольного клиента: плагин следует его закреплению (pin). Нативное диалоговое окно в редакторе запланировано на будущее.

Плагин Rider

Он использует uversion под капотом. Один раз uversion trust <url>, и Rider проходит.

Если отпечаток изменился

Клиент отказывается подключаться и прямо об этом сообщает. Не подтверждайте повторно на автомате: сначала сверьтесь с вашим администратором, по каналу, отличному от рассматриваемого соединения. Три возможных объяснения: переустановка сервера, намеренная ротация сертификата или кто-то, вставший между вашими рабочими станциями и вашим сервером. Получив объяснение:

Настольный клиент: кнопка Trust new fingerprint в окне предупреждения.
CLI: uversion mistrust <url>, затем uversion login <url>.

Перегенерировать сертификат

Сертификат по умолчанию действителен десять лет: никакого продления планировать не нужно. Чтобы принудительно выполнить ротацию (подозрение на компрометацию, требование аудита):

# Linux
sudo rm /var/lib/uversion/data/tls/cert.pem /var/lib/uversion/data/tls/key.pem
sudo systemctl restart uversion-server

# Windows
Remove-Item "C:\ProgramData\uVersion\data\tls\cert.pem"
Remove-Item "C:\ProgramData\uVersion\data\tls\key.pem"
Restart-Service uVersionServer

Сервер при запуске заново создаёт сертификат и новый отпечаток. Предупредите команду и поделитесь им снова: каждой рабочей станции придётся подтвердить заново.

Использовать свой сертификат

Вы можете положить свой собственный сертификат, выпущенный вашим внутренним PKI или публичным удостоверяющим центром. Никакой опции включать не нужно: при запуске сервер повторно использует файлы, имеющиеся по путям [tls] cert_path и [tls] key_path, и пересчитывает отпечаток. Это работает, только если ваш сервер имеет имя DNS: ни один центр не выпускает сертификат для частного IP-адреса.

Три требования к формату, каждое из которых уже стоило кому-то вечера:

файл сертификата содержит полную цепочку, конечный сертификат первым (файл fullchain.pem от certbot имеет ровно такой вид);
приватный ключ является незашифрованным PEM: ключ, защищённый парольной фразой, расшифрован не будет;
положите оба файла перед перезапуском. Если найдётся только один, сервер сочтёт состояние неполным и заново создаст самоподписанную пару поверх оставшегося.

Что это меняет для рабочих станций:

Браузер: больше никаких предупреждений, при условии что вы открываете сервер по имени, которое несёт сертификат. По его IP-адресу предупреждение остаётся.
Уже закреплённые рабочие станции: отпечаток меняется, поэтому каждая увидит описанное выше предупреждение и должна будет подтвердить заново. Предупредите до замены, иначе вся команда столкнётся с сообщением о перехвате в один и тот же момент.
Продления: каждое продление меняет отпечаток и заново запускает этот ритуал, а сертификат перечитывается только при запуске сервера. С публичным сертификатом на 90 дней это выходит шесть общекомандных повторных подтверждений в год: предпочитайте длительный срок, пока эта издержка не будет устранена.