Impressão digital TLS

A uVersion criptografa todas as conexões com HTTPS por padrão, sem nome de domínio nem certificado comprado. O servidor gera seu certificado na primeira inicialização, o administrador compartilha a impressão digital dele com a equipe, e cada estação a confirma uma vez. É o modelo TOFU: confiança no primeiro contato, exatamente como o SSH quando faz você validar a impressão digital de uma máquina na primeira vez. Depois, o cliente a compara a cada conexão e se recusa a falar com um servidor que tenha mudado.

A operação tem dois momentos: encontrar a impressão digital no servidor, uma vez, e depois confirmá-la em cada estação, uma vez por estação. O resto desta página é referência, para ler no dia em que algo mudar.

Encontrar a impressão digital

Ela é exibida ao final da instalação, ao lado da senha de administrador. Depois, há três maneiras de recuperá-la, da mais simples à mais manual.

1. Pelo navegador, sem instalar nada

O servidor expõe uma página de informações sem autenticação: abra https://SEU-SERVIDOR:8443/api/server-info. Sem sudo, sem acesso SSH, sem conta uVersion: é de longe o caminho mais curto.

O navegador exibe primeiro um aviso de segurança. Isso é normal e esperado: o certificado é autoassinado, nenhuma autoridade pública o conhece. Prossiga para o site.

A página que aparece em seguida é um bloco de dados bruto. A impressão digital é o valor do campo tls_fingerprint: uma sequência de bytes em hexadecimal separados por dois-pontos. É essa cadeia, inteira, que você vai repassar à equipe.

2. Pelos logs do servidor

O servidor reescreve a impressão digital nos seus logs a cada inicialização. Este método funciona onde quer que você tenha colocado o diretório de dados:

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

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

3. No arquivo fingerprint

Esse arquivo é gravado ao lado do certificado, ou seja, no diretório de [tls] cert_path tal como aparece no seu config.toml. Os caminhos abaixo são os valores padrão: se você moveu o diretório de dados, leia primeiro cert_path na sua configuração.

# 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

Confirmar no cliente

Uma vez por estação, e de uma vez por todas. O gesto depende da ferramenta.

Cliente desktop

Preencha a tela de login normalmente. Na primeira conexão a este servidor, em vez de fazer o login, abre-se uma janela Verify server identity. Compare a impressão digital exibida com a que o seu administrador compartilhou e clique em Trust this server se corresponderem: a conexão prossegue sozinha logo em seguida. Se divergirem, Cancel, e vá perguntar o porquê.

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

O uversion trust é interativo: exibe o host, a versão do servidor, o modo TLS e a impressão digital, lembra de comparar com o que o administrador transmitiu e então aguarda uma confirmação y/N. Qualquer outra resposta cancela sem fixar nada. A opção --yes pula essa pergunta, para um script ou uma integração contínua: fixa sem ninguém olhar, a reservar para uma rede que você controla.

O uversion login propõe a mesma confirmação por conta própria quando o servidor ainda não está fixado: numa estação, em geral não há nada a executar antes.

Plugin do Unreal Engine

Execute uversion trust <url> uma vez em um terminal antes de abrir o projeto, ou faça login primeiro pelo cliente desktop: o plugin segue a fixação (pin) dele. Um diálogo nativo no editor está planejado para mais adiante.

Plugin do Rider

Ele usa o uversion por baixo. Um uversion trust <url> uma vez, e o Rider passa.

Se a impressão digital mudar

O cliente se recusa a conectar e anuncia isso com clareza. Não reconfirme por reflexo: verifique primeiro com o seu administrador, por um canal diferente da conexão em questão. Três explicações possíveis: uma reinstalação do servidor, uma rotação intencional do certificado, ou alguém posicionado entre as suas estações e o seu servidor. Uma vez obtida a explicação:

• Cliente desktop: botão Trust new fingerprint no diálogo de alerta.
• CLI: uversion mistrust <url> e depois uversion login <url>.

Regenerar o certificado

O certificado é válido por dez anos por padrão: não há nenhuma renovação a prever. Para forçar uma rotação (suspeita de comprometimento, exigência de auditoria):

# 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

O servidor regenera um certificado e uma nova impressão digital na inicialização. Avise a equipe e compartilhe-a novamente: cada estação terá de confirmar de novo.

Fornecer seu próprio certificado

Você pode colocar o seu próprio certificado, emitido pela sua PKI interna ou por uma autoridade pública. Não há nenhuma opção a ativar: na inicialização, o servidor reutiliza os arquivos presentes nos caminhos [tls] cert_path e [tls] key_path, e recalcula a impressão digital. Isso só vale se o seu servidor tiver um nome DNS: nenhuma autoridade emite certificado para um endereço IP privado.

Três restrições de formato, cada uma das quais já custou uma noite a alguém:

• o arquivo de certificado contém a cadeia completa, a folha primeiro (o fullchain.pem do certbot tem exatamente essa forma);
• a chave privada é um PEM não criptografado: uma chave protegida por frase secreta não será descriptografada;
• coloque os dois arquivos antes de reiniciar. Se encontrar apenas um, o servidor considera o estado incompleto e regenera um par autoassinado por cima do que restou.

O que isso muda para as estações:

• Navegador: acabam os avisos, desde que você abra o servidor pelo nome que o certificado carrega. Pelo endereço IP, o aviso permanece.
• Estações já fixadas: a impressão digital muda, então cada uma verá o alerta descrito acima e terá de confirmar de novo. Avise antes da troca, senão a equipe inteira encontra uma mensagem de interceptação no mesmo momento.
• Renovações: cada renovação muda a impressão digital e reinicia esse ritual, e o certificado só é relido na inicialização do servidor. Com um certificado público de 90 dias, isso dá seis reconfirmações para toda a equipe por ano: prefira uma duração longa enquanto esse custo não for absorvido.