Wiki

Impronta TLS

Il server genera un certificato autofirmato durante l'installazione. Ogni client conferma la sua impronta alla prima connessione.

È sicuro? Sì. Tutte le connessioni e tutti i trasferimenti di file sono cifrati: nessuno sulla rete può leggere ciò che passa tra le tue postazioni e il tuo server. I tuoi dati restano sulla tua infrastruttura: nulla è ospitato da terzi, nulla passa attraverso uVersion. Solo i membri del tuo team, con le proprie credenziali, possono accedere. E se sulla connessione accade qualcosa di anomalo, il software lo rileva e blocca subito, invece di lasciarlo passare in silenzio.

uVersion cifra tutte le connessioni con HTTPS in modo predefinito, senza nome di dominio né certificato acquistato. Il server genera il proprio certificato al primo avvio, l'amministratore ne condivide l'impronta con il team, e ogni postazione la conferma una volta. È il modello TOFU: fiducia al primo contatto, esattamente come SSH quando ti fa convalidare l'impronta di una macchina la prima volta. In seguito, il client la confronta a ogni connessione e si rifiuta di parlare con un server che sia cambiato.

Impronta del server, o checksum? Entrambe sono SHA-256, ed è ciò che confonde tutti. L'impronta del server identifica il certificato del tuo server: serve a riconoscere la macchina a cui si connettono le tue postazioni. Un checksum verifica che un file scaricato sia integro. Questa pagina parla soltanto della prima.

L'operazione si svolge in due tempi: trovare l'impronta sul server, una volta, poi confermarla su ogni postazione, una volta per postazione. Il resto di questa pagina è materiale di riferimento, da leggere il giorno in cui qualcosa cambia.

Trovare l'impronta

Viene mostrata al termine dell'installazione, accanto alla password di amministratore. Poi ci sono tre modi per ritrovarla, dal più semplice al più manuale.

1. Da un browser, senza installare nulla

Il server espone una pagina informativa senza autenticazione: apri https://IL-TUO-SERVER:8443/api/server-info. Né sudo, né accesso SSH, né un account uVersion: è di gran lunga la via più breve.

Il browser mostra prima un avviso di sicurezza. È normale e previsto: il certificato è autofirmato, nessuna autorità pubblica lo conosce. Prosegui verso il sito.

L'avviso di sicurezza del browser alla prima apertura dell'indirizzo del server, con il link o il pulsante che consente di proseguire nonostante il certificato autofirmato.

La pagina che appare in seguito è un blocco di dati grezzi. L'impronta è il valore del campo tls_fingerprint: una sequenza di byte in esadecimale separati da due punti. È questa stringa, per intero, che trasmetterai al team.

La pagina /api/server-info aperta in un browser: i campi version, build_sha, tls_mode impostato su self_signed, e tls_fingerprint con l'impronta SHA-256 in esadecimale separata da due punti.

Questa pagina dice ciò che il server dichiara È perfetta per pubblicare l'impronta al tuo team, dato che l'amministratore sei tu. Da sola non costituisce una verifica: chi intercettasse la connessione restituirebbe il proprio valore. Ciò che protegge è il confronto che ogni postazione compie tra l'impronta effettivamente presentata dal server e quella che le hai trasmesso per un altro canale (messaggistica interna, a voce, wiki del team). Il client da riga di comando, del resto, fa entrambe le cose e ti avverte quando differiscono.

2. Dai log del server

Il server riscrive l'impronta nei suoi log a ogni avvio. Questo metodo funziona ovunque tu abbia collocato la cartella dei dati:

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

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

3. Nel file `fingerprint`

Questo file viene scritto accanto al certificato, quindi nella cartella di [tls] cert_path così com'è indicata nel tuo config.toml. I percorsi qui sotto sono i valori predefiniti: se hai spostato la cartella dei dati, leggi prima cert_path nella tua configurazione.

# 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

Confermare sul client

Una volta per postazione, e una volta per tutte. Il gesto dipende dallo strumento.

Client desktop

Compila la schermata di accesso come al solito. Alla prima connessione a questo server, invece di farti accedere, si apre una finestra Verify server identity. Confronta l'impronta mostrata con quella condivisa dal tuo amministratore, poi fai clic su Trust this server se corrispondono: la connessione riprende da sola subito dopo. Se differiscono, Cancel, e vai a chiedere il perché.

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 è interattivo: mostra l'host, la versione del server, la modalità TLS e l'impronta, ricorda di confrontare con ciò che l'amministratore ha trasmesso, poi attende una conferma y/N. Qualsiasi altra risposta annulla senza fissare nulla. L'opzione --yes salta questa domanda, per uno script o un'integrazione continua: fissa senza che nessuno guardi, da riservare a una rete che controlli.

uversion login propone da sé la stessa conferma quando il server non è ancora fissato: su una postazione, di norma non c'è nulla da eseguire prima.

Plugin di Unreal Engine

Esegui uversion trust <url> una volta in un terminale prima di aprire il progetto, oppure accedi prima dal client desktop: il plugin ne segue il pinning. Una finestra di dialogo nativa nell'editor è prevista in seguito.

Plugin di Rider

Usa uversion internamente. Un uversion trust <url> una volta, e Rider passa.

Se l'impronta cambia

Il client si rifiuta di connettersi e lo annuncia con chiarezza. Non riconfermare per riflesso: verifica prima con il tuo amministratore, tramite un canale diverso dalla connessione in questione. Tre spiegazioni possibili: una reinstallazione del server, una rotazione volontaria del certificato, oppure qualcuno collocato tra le tue postazioni e il tuo server. Una volta ottenuta la spiegazione:

Client desktop: pulsante Trust new fingerprint nella finestra di avviso.
CLI: uversion mistrust <url> poi uversion login <url>.

Rigenerare il certificato

Il certificato è valido dieci anni in modo predefinito: non c'è alcun rinnovo da prevedere. Per forzare una rotazione (compromissione sospetta, requisito di audit):

# 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

Il server rigenera un certificato e una nuova impronta all'avvio. Avvisa il team e ricondividila: ogni postazione dovrà riconfermare.

Fornire il proprio certificato

Puoi depositare il tuo certificato, emesso dalla tua PKI interna o da un'autorità pubblica. Non c'è alcuna opzione da attivare: all'avvio, il server riutilizza i file presenti nei percorsi [tls] cert_path e [tls] key_path, e ricalcola l'impronta. Questo vale solo se il tuo server porta un nome DNS: nessuna autorità emette un certificato per un indirizzo IP privato.

Tre vincoli di formato, ognuno dei quali è già costato una serata a qualcuno:

il file del certificato contiene la catena completa, la foglia per prima (il fullchain.pem di certbot ha esattamente questa forma);
la chiave privata è un PEM non cifrato: una chiave protetta da passphrase non verrà decifrata;
deposita entrambi i file prima di riavviare. Se ne trova uno solo, il server considera lo stato incompleto e rigenera una coppia autofirmata al di sopra di quello rimasto.

Ciò che questo cambia per le postazioni:

Browser: niente più avviso, a patto di aprire il server con il nome portato dal certificato. Tramite il suo indirizzo IP, l'avviso permane.
Postazioni già fissate: l'impronta cambia, quindi ciascuna vedrà l'avviso descritto sopra e dovrà riconfermare. Avvisa prima dello scambio, altrimenti tutto il team si imbatte in un messaggio di intercettazione nello stesso momento.
Rinnovi: ogni rinnovo cambia l'impronta e fa ripartire questo rituale, e il certificato viene riletto solo all'avvio del server. Con un certificato pubblico di 90 giorni, sono sei riconferme per tutto il team all'anno: preferisci una durata lunga finché questo costo non è assorbito.