Come generare un CSR sui server JBoss

Questo tutorial ti mostra come generare un CSR (Certificate Signing Request) su JBoss EAP e WildFly utilizzando l’utility Java keytool. Il flusso prevede due comandi: prima keytool -genkeypair crea un keystore e una chiave privata con un alias scelto, poi keytool -certreq esporta il CSR corrispondente con i Subject Alternative Names che la CA emetterà. Lo stesso alias viene riutilizzato in seguito quando importi il certificato firmato, quindi la chiave, il CSR e il certificato finale risiedono tutti nello stesso posto.

Nota sulle versioni: il JBoss moderno è Red Hat JBoss Enterprise Application Platform (EAP) 8, rilasciato a febbraio 2024 e basato sul progetto upstream WildFly (WildFly 41, rilasciato a luglio 2026, è l’attuale versione della community). Entrambi instradano HTTPS attraverso il sottosistema elytron e l’https-listener di Undertow; la configurazione del connettore Tomcat o Jetty più datata mostrata nelle guide precedenti non è più valida. Il passaggio del CSR in sé, tuttavia, è identico in tutte le versioni recenti perché si tratta di una semplice operazione Java keytool.

Cosa ti serve

• Un’installazione Java (JDK o JRE) affinché il comando keytool sia disponibile. JBoss EAP 8.0 funziona su Java 11 (deprecato) o 17, EAP 8.1 aggiunge Java 21, e WildFly 41 funziona su Java 17, 21 o 25 (Java 11 non è più supportato a monte). Verifica con keytool -help.
• Accesso shell o terminale sul server JBoss che ospiterà la chiave privata. La chiave privata deve rimanere su questo server.
• Il nome di dominio completamente qualificato (FQDN) esatto che vuoi proteggere, ad esempio www.tuodominio.com, oltre a eventuali hostname aggiuntivi che vuoi includere nel campo SAN.
• I dettagli legali della tua organizzazione (paese, stato, località, nome dell’organizzazione) per il Distinguished Name del CSR.

Passaggio 1: crea il keystore e la chiave privata

Se hai già generato il tuo CSR, salta direttamente a invia il CSR e poi a installa il tuo certificato SSL su JBoss.

Apri un terminale sul server JBoss e crea un nuovo keystore in formato PKCS12. PKCS12 è lo standard moderno e portabile (RFC 7292) ed è il formato keystore predefinito in Java a partire da JDK 9; il vecchio formato proprietario JKS è deprecato. Esegui:

keytool -genkeypair 
  -alias jboss 
  -keyalg RSA -keysize 2048 
  -storetype PKCS12 
  -keystore yourdomain.p12 
  -validity 825

Cosa significano i flag:

• -alias jboss: il nome della voce all’interno del keystore. Scegli un’etichetta che riconoscerai (spesso jboss, server, o il tuo dominio). Annotalo. Devi riutilizzare esattamente questo alias quando generi il CSR e di nuovo quando importi il certificato firmato. Usare un alias diverso in fase di importazione è l’errore più comune con keytool.
• -keyalg RSA -keysize 2048: una chiave RSA a 2048 bit è l’attuale minimo pubblico. Per nuovi keystore che intendi mantenere per diversi anni, 3072 bit è un aggiornamento ragionevole. La maggior parte delle CA pubbliche accetta anche ECDSA (-keyalg EC -groupname secp256r1) se preferisci una chiave più piccola e veloce. L’opzione -groupname richiede JDK 13 o successivo; su Java 11 usa invece -keyalg EC -keysize 256, che seleziona la stessa curva secp256r1. keytool rifiuta entrambe le opzioni nello stesso comando.
• -storetype PKCS12: forza il moderno keystore PKCS12. L’estensione corrispondente è .p12 (o .pfx).
• -keystore yourdomain.p12: il file keystore da creare. Sostituisci il nome con qualcosa che riconoscerai e conserva questo file al sicuro; contiene la tua chiave privata.
• -validity 825: per quanto tempo è valido il certificato segnaposto autofirmato all’interno del keystore. Il certificato firmato dalla CA lo sostituirà in seguito, quindi il valore esatto non influisce sulla durata in produzione.

keytool chiede quindi una password del keystore. Scegli una password sicura e conservala nel tuo gestore di credenziali: ti servirà per ogni comando keytool successivo e per il credential-reference Elytron che configurerai in JBoss. Con i keystore PKCS12 la password della chiave coincide con la password del keystore, quindi c’è una sola password da ricordare.

Passaggio 2: inserisci i dettagli della tua organizzazione (DN)

Ora keytool chiede il Distinguished Name (DN): i campi identificativi che vanno nel CSR. Rispondi a ogni richiesta con il valore esatto e legale della tua organizzazione. La punteggiatura e l’accuratezza contano, perché una CA rifiuterà eventuali discrepanze rispetto ai registri pubblici delle aziende.

• Nome e cognome (CN): questa è la formulazione di keytool, ma si tratta del campo Common Name. Inserisci l’esatto FQDN che stai proteggendo, ad esempio www.tuodominio.com, oppure un wildcard come *.tuodominio.com. Non inserire il nome di una persona.
• Unità organizzativa (OU): questo campo non è più emesso dalle CA pubbliche ed è meglio ometterlo. Nota che premere Invio non lo lascia vuoto: keytool sostituisce con un valore predefinito proprio, quindi il DN finisce per contenere OU=Unknown, che poi viene riportato nel CSR. Per omettere davvero il campo, usa la forma non interattiva -dname descritta di seguito e lascia fuori OU dalla stringa.
• Organizzazione (O): la ragione sociale completa della tua azienda, ad esempio Your Company LLC. I certificati OV ed EV lo richiedono; per i certificati DV molte CA lo accettano come informativo, quindi compilarlo è più sicuro che lasciarlo vuoto.
• Città o località (L): il nome completo della città, ad esempio San Jose. Non abbreviare.
• Stato o provincia (ST): il nome completo dello stato o della provincia, ad esempio California. Non usare un codice a due lettere.
• Codice paese (C): il codice ISO a due lettere del paese, ad esempio US, GB, DE.

Dopo l’ultima richiesta, keytool mostra un riepilogo simile a CN=www.tuodominio.com, OU=Unknown, O=Your Company LLC, L=San Jose, ST=California, C=US. Digita yes per confermare. Il file keystore ora esiste con una voce: il tuo alias, contenente la chiave privata e un certificato segnaposto autofirmato.

Se preferisci un comando non interattivo, passa il DN direttamente e salta le richieste:

keytool -genkeypair 
  -alias jboss 
  -keyalg RSA -keysize 2048 
  -storetype PKCS12 
  -keystore yourdomain.p12 
  -dname "CN=www.yourdomain.com, O=Your Company LLC, L=San Jose, ST=California, C=US" 
  -validity 825

Passaggio 3: genera il CSR con SAN

I browser moderni e i client TLS convalidano i certificati in base all’estensione Subject Alternative Name (SAN), non solo in base al Common Name. Richiedi i SAN direttamente nel CSR in modo che la CA li includa nel certificato emesso. Usa lo stesso alias e keystore del Passaggio 1:

keytool -certreq 
  -alias jboss 
  -keystore yourdomain.p12 
  -file yourdomain.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Cosa significano i flag:

• -alias jboss: deve corrispondere all’alias del Passaggio 1. È l’alias la cui chiave privata firma la richiesta.
• -keystore yourdomain.p12: deve corrispondere al keystore del Passaggio 1.
• -file yourdomain.csr: il nome del file di output per il CSR.
• -ext san=dns:…: l’estensione Subject Alternative Name. Elenca ogni hostname che il certificato deve coprire, incluso sia il dominio principale (yourdomain.com) che il sottodominio www. Aggiungi altre voci separate da virgola, ad esempio dns:api.yourdomain.com.

keytool chiede la password del keystore e scrive il CSR nel file yourdomain.csr nella directory corrente.

Importante: conserva alias e keystore

L’errore più comune con keytool su JBoss è importare il certificato firmato con un nuovo alias. Fare ciò memorizza il certificato come voce attendibile a sé stante, senza chiave privata associata, e il key-manager di Elytron non riuscirà ad avviare una sessione TLS. Importa sempre la risposta firmata di nuovo nello stesso alias che contiene la chiave privata (l’alias del Passaggio 1).

Annota questi tre valori ora, prima di chiudere il terminale:

• L’alias (in questa guida, jboss).
• Il percorso del file keystore (ad esempio yourdomain.p12; su JBoss di solito si trova in $JBOSS_HOME/standalone/configuration/).
• La password del keystore.

Se non sei sicuro di quale alias contenga la tua chiave, elenca il contenuto del keystore e cerca la voce il cui tipo è PrivateKeyEntry:

keytool -list -v -keystore yourdomain.p12

Passaggio 4: verifica il CSR prima di inviarlo

Individua eventuali errori di battitura nel DN o SAN mancanti prima che la CA li convalidi. Stampa il CSR con keytool:

keytool -printcertreq -file yourdomain.csr

Oppure, se OpenSSL è installato, puoi usarlo al suo posto:

openssl req -noout -text -in yourdomain.csr

Verifica tre cose nell’output: il campo Subject mostra il tuo DN esatto, il Subject Alternative Name elenca ogni hostname di cui hai bisogno e la dimensione della Public-Key corrisponde a quella richiesta (RSA a 2048 bit, o qualunque valore tu abbia scelto). Puoi anche incollare il CSR nel nostro CSR Decoder per lo stesso controllo nel browser.

Passaggio 5: invia il CSR alla tua Certificate Authority

Apri yourdomain.csr in un qualsiasi editor di testo. Il file è testo semplice, inizia con -----BEGIN NEW CERTIFICATE REQUEST----- e termina con -----END NEW CERTIFICATE REQUEST-----. La parola NEW è ciò che keytool scrive, ed è normale: il contenuto è una richiesta PKCS#10 standard che ogni CA accetta. Copia l’intero blocco, incluse quelle righe di intestazione e piè di pagina, e incollalo nel campo CSR durante il checkout con la tua CA. Su Windows, usa Ctrl + A e poi Ctrl + C per selezionare l’intero testo; su macOS, usa Cmd + A e poi Cmd + C.

Esegui il backup del file keystore prima di fare qualsiasi altra cosa. Se perdi yourdomain.p12 perdi anche la chiave privata, il che significa che il certificato firmato restituito dalla CA sarà inutilizzabile e dovrai ricominciare con un nuovo CSR.

Dopo che la CA ha convalidato la tua richiesta ed emesso il certificato, prosegui con come installare il tuo certificato SSL su JBoss. Importerai il certificato firmato di nuovo nello stesso alias nello stesso keystore, quindi farai riferimento a quel keystore da un key-store, key-manager e server-ssl-context di Elytron collegati all’https-listener di Undertow.

Posso riutilizzare un CSR per un rinnovo?

Puoi, ma la best practice di sicurezza è generare un nuovo keystore, una nuova chiave privata e un nuovo CSR per ogni certificato. Una nuova chiave a ogni rinnovo limita l’impatto nel caso in cui la vecchia chiave venga mai compromessa, e il processo è lo stesso: esegui keytool -genkeypair e keytool -certreq su un nuovo file keystore. Le durate dei certificati TLS pubblici si stanno riducendo secondo le regole del CA/Browser Forum (200 giorni a partire dal 15 marzo 2026, in calo a 100 giorni nel 2027 e a 47 giorni nel 2029), quindi pianifica cicli di CSR più frequenti, oppure automatizza l’emissione tramite ACME dove la tua CA lo supporta.