Come generare un CSR su UniFi Cloud Key

Questo tutorial spiega come generare una CSR (Certificate Signing Request) su un Ubiquiti UniFi Cloud Key. Il Cloud Key non dispone di un generatore di CSR integrato nella sua interfaccia web, quindi creerai la CSR tramite SSH utilizzando OpenSSL. Questi passaggi si applicano a Cloud Key Gen1 e Gen2/Gen2+, così come alle installazioni self-hosted dell’applicazione UniFi Network eseguite su Linux.

Generare una CSR su UniFi Cloud Key

Se hai già generato la tua CSR, passa direttamente alle istruzioni per l’installazione SSL su UniFi Cloud Key.

Puoi anche utilizzare il nostro CSR Generator per creare la CSR automaticamente, anziché eseguire comandi OpenSSL sul dispositivo.

Requisiti

• Accesso SSH al tuo Cloud Key (abilita SSH nelle impostazioni di UniFi OS, oppure connettiti direttamente tramite l’IP del dispositivo sulla porta 22).
• Familiarità di base con i comandi da terminale.
• OpenSSL installato (preinstallato sul firmware del Cloud Key).

Passaggio 1: Connettiti al Cloud Key tramite SSH

Apri un terminale (o PuTTY su Windows) e connettiti al tuo Cloud Key:

ssh [email protected]

Sostituisci 192.168.1.x con l’indirizzo IP del tuo Cloud Key. Sui dispositivi UniFi OS (Gen2/Gen2+), accedi con le credenziali impostate durante la configurazione iniziale.

Passaggio 2: Esegui il backup dei file del certificato esistente (facoltativo ma consigliato)

Prima di generare i nuovi file, crea un backup della directory del certificato attuale:

cp -r /etc/ssl/private ~/cloudkey-cert-backup

Questo conserva la chiave e il certificato esistenti, in modo da poterli ripristinare se necessario. Il backup è importante in questo caso: su un Cloud Key Gen1 la directory contiene già il certificato e la chiave che il dispositivo sta utilizzando (cloudkey.crt e cloudkey.key), e il comando al Passaggio 3 sovrascrive la nuova chiave su cloudkey.key. Finché non installi il certificato emesso, il certificato sul dispositivo e la chiave accanto ad esso non corrispondono più, e ripristinare questo backup è l’unico modo per riportare il dispositivo allo stato precedente.

Nota per Gen2 e Gen2+: sui dispositivi che eseguono UniFi OS, il certificato e la chiave attivi sono unifi-core.crt e unifi-core.key in /data/unifi-core/config/, non in /etc/ssl/private. Esegui il backup di quella directory, invece, e genera la richiesta in un percorso a tua scelta.

Passaggio 3: Genera la CSR e la chiave privata

Esegui il seguente comando OpenSSL per creare una chiave privata RSA a 2048 bit e una CSR in un unico passaggio. Sostituisci ogni valore segnaposto con le tue informazioni:

openssl req -new -newkey rsa:2048 -nodes -sha256 
  -subj "/C=US/ST=California/L=San Jose/O=Your Company LLC/CN=unifi.yourdomain.com" 
  -addext "subjectAltName=DNS:unifi.yourdomain.com" 
  -keyout /etc/ssl/private/cloudkey.key 
  -out /etc/ssl/private/cloudkey.csr

Nota: il flag -addext richiede OpenSSL 1.1.1 o versioni successive (incluso su Cloud Key Gen2/Gen2+ e sui dispositivi Gen1 con firmware 1.1.6+). Se il tuo dispositivo ha una versione più datata di OpenSSL, puoi omettere -addext e aggiungere il SAN tramite un file di configurazione OpenSSL, oppure utilizzare il CSR Generator. Su OpenSSL 3.x puoi usare -noenc al posto di -nodes; entrambi producono una chiave privata non cifrata.

Guida ai campi della CSR

Ogni campo nella stringa -subj corrisponde a un attributo del certificato. Compilali come segue:

• C: codice paese di due lettere (ISO 3166), ad esempio US.
• ST: stato o provincia (nome completo, non abbreviato).
• L: città o località.
• O: la ragione sociale della tua organizzazione. Per i certificati Domain Validation (DV) questo campo è facoltativo.
• CN: il nome di dominio completamente qualificato (FQDN) che utilizzerai per accedere al controller del Cloud Key, ad esempio unifi.yourdomain.com.

La riga -addext "subjectAltName=..." imposta il campo Subject Alternative Name (SAN). I browser moderni richiedono che l’hostname sia presente nel SAN, non solo nel CN. Se devi coprire più di un hostname, separali con virgole:

-addext "subjectAltName=DNS:unifi.yourdomain.com,DNS:cloudkey.yourdomain.com"

Passaggio 4: Verifica la CSR

Prima di inviare la CSR, conferma che i dettagli del soggetto e il SAN siano corretti:

openssl req -in /etc/ssl/private/cloudkey.csr -noout -text

Cerca la riga Subject: (dovrebbe corrispondere ai tuoi valori -subj) e la sezione X509v3 Subject Alternative Name (dovrebbe elencare il tuo FQDN). Puoi anche incollare il contenuto della CSR nel CSR Decoder di SSL Dragon per un controllo visivo.

Passaggio 5: Invia la CSR alla tua Certificate Authority

Apri il file CSR in un editor di testo o visualizzalo nel terminale:

cat /etc/ssl/private/cloudkey.csr

Copia l’intero output, incluse le righe -----BEGIN CERTIFICATE REQUEST----- e -----END CERTIFICATE REQUEST-----. Incollalo nel campo CSR durante il processo di ordine del certificato SSL con la tua CA.

Conserva il file della chiave privata (/etc/ssl/private/cloudkey.key) sul Cloud Key. Ne avrai bisogno in seguito quando installerai il certificato SSL nel keystore UniFi.

Passaggio 6: Proteggi la chiave privata

Limita l’accesso al file della chiave in modo che solo root possa leggerlo:

chmod 600 /etc/ssl/private/cloudkey.key

Non condividere né trasferire mai la chiave privata attraverso un canale non cifrato. Se sospetti che sia stata compromessa, genera una nuova CSR e riemetti il certificato.