docs: focus public documentation on product usage

This commit is contained in:
2026-08-26 10:15:07 +02:00
parent 23bc2f6555
commit a54d4769dd
67 changed files with 290 additions and 9963 deletions
+25 -34
View File
@@ -1,49 +1,40 @@
# TLS per DWH REST
La chiave DWH è accettabile solo sopra TLS verificato. Un errore `401` o `503` non autorizza mai a
ridurre la verifica del certificato.
La chiave DWH è accettabile solo sopra TLS verificato. Errori di autorizzazione o disponibilità
non autorizzano mai a disabilitare la verifica del certificato.
## Stato PSD
## CA privata
L'origine REST PSD corrente usa il certificato self-issued/private di Nginx. Il SAN copre
`supabase-aritmolab.policlinicosandonato.it`, l'origine `.it` approvata, e non copre un dominio
`.com`. Non usare `.com` finché non è incluso esplicitamente nel SAN.
Quando il DWH REST usa una CA aziendale, consegnare il certificato separatamente dalla chiave
API. La CA non è una credenziale, ma la sua integrità è un confine di sicurezza: deve restare
fuori da Git e non essere scrivibile da utenti non autorizzati.
Chi non dispone già di trust equivalente approvato riceve la CA separatamente e configura
`TLS_CA_FILE`. La CA non è una credenziale, ma la sua integrità è un confine di sicurezza: fuori da
Git e non scrivibile da utenti non autorizzati.
Esempio ACME Limited:
```dotenv
THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem
```
## Fingerprint fuori banda
Calcolare localmente il fingerprint del file ricevuto:
Calcolare il fingerprint del file ricevuto e confrontarlo attraverso un canale indipendente:
```bash
openssl x509 -noout -fingerprint -sha256 -in /absolute/protected/psd-dwh-ca.pem
openssl x509 -noout -fingerprint -sha256 \
-in /absolute/protected/acme-ebikes-dwh-ca.pem
```
Confrontarlo con il responsabile autorizzato tramite un canale indipendente dalla consegna (vault
aziendale o canale telefonico verificato). Nell'evidenza registrare solo conferma, approvatore e
timestamp; mai corpo certificato, fingerprint completo o output grezzo.
Il SAN del certificato deve includere il nome esatto usato dal binding, per esempio
`dwh.acme.example`.
## Binding e ping
## Rinnovo
Il binding headless PSD effettivo è:
1. Preparare certificato e chain nuovi.
2. Confermare SAN e fingerprint fuori banda.
3. Distribuire la nuova CA ai client mantenendo temporaneamente la precedente.
4. Aggiornare il binding e confermare la connettività con TLS normale.
5. Installare il certificato server.
6. Ritirare il trust precedente dopo la finestra concordata.
```dotenv
THT_WS_PSD_CLINICAL_DWH_TLS_CA_FILE=/run/secrets/psd-clinical-dwh-ca.pem
```
Il file sorgente locale è collegato da file operatore non tracciato. Usare URL `.it`, poi
**Test workspace connections** su `/rpc/ping`. Non disabilitare TLS e non usare `curl -k`.
## Rinnovo coordinato
1. Preparare certificato e chain nuovi; verificare prima SAN `.it` e assenza di falsa copertura `.com`.
2. Confermare fuori banda il nuovo fingerprint.
3. Consegnare la CA/chain nuova ai client con `TLS_CA_FILE`, senza rimuovere ancora la precedente.
4. Aggiornare vault/binding e verificare ping con TLS normale.
5. Solo con gate Nginx approvato installare il certificato server e ripetere il ping.
6. Ritirare il trust precedente dopo la finestra approvata.
Il rinnovo non modifica chiavi `dwh-auth`, record o ruoli PostgreSQL. TLS e rollback della route
restano approvazioni e backup distinti.
Non usare `curl -k`, non disabilitare TLS e non incorporare certificati o fingerprint completi
nei documenti condivisi.