Come generare un CSR su IBM HTTP Server

Questa guida mostra come generare una CSR (Certificate Signing Request) su IBM HTTP Server (IHS), e come eseguire la stessa operazione su HCL Domino (precedentemente IBM Domino).

IBM HTTP Server memorizza chiavi e certificati in un database di chiavi CMS (un file .kdb più uno stash .sth), che si gestisce con lo strumento grafico IKEYMAN o con l’utility da riga di comando gskcapicmd dell’IBM Global Security Kit (GSKit) fornito con IHS.

I passaggi seguenti trattano entrambi i percorsi su IHS 9.0.5.x (la versione attualmente supportata), quindi i due flussi CSR per HCL Domino: il classico database Server Certificate Administration (mantenuto per installazioni legacy) e la moderna attività Certificate Manager con certstore.nsf, che HCL raccomanda su Domino 12 e versioni successive.

Generare una CSR su IBM HTTP Server

Se hai già generato la tua CSR, passa direttamente a come installare un certificato SSL su IBM HTTP Server.

Puoi creare la richiesta in due modi su IHS: tramite l’interfaccia grafica IKEYMAN (l’utility classica punta e clicca), oppure con gskcapicmd da riga di comando. Entrambi scrivono la chiave privata nello stesso database di chiavi CMS e producono una richiesta PKCS #10 come file .arm che sottometti alla tua Certificate Authority. Scegli l’interfaccia grafica su un desktop o un server con display; scegli la CLI su una macchina headless o quando desideri uno script ripetibile.

Prerequisiti: IBM HTTP Server è installato, GSKit è presente sul sistema (viene fornito all’interno del pacchetto IHS), e la directory bin di IHS è presente nel tuo PATH oppure conosci il suo percorso completo (tipicamente /opt/IBM/HTTPServer/bin/ su Linux/AIX, o C:Program FilesIBMHTTPServerbin su Windows). Serve anche una directory di lavoro in cui poter scrivere il nuovo database di chiavi e il file CSR, e un luogo dove registrare la password del database di chiavi.

Metodo 1. Generare una CSR con IKEYMAN (GUI)

Passo 1. Creare un nuovo database di chiavi CMS (.kdb)

• Avvia IKEYMAN. Su Windows, apri Start > IBM HTTP Server > Start Key Management Utility. Su Linux, AIX, o altri sistemi UNIX, esegui ikeyman dalla directory bin di IHS (ad esempio /opt/IBM/HTTPServer/bin/ikeyman); serve un display X11 funzionante.
• Dal menu, scegli Key Database File > New.
• Nel menu a discesa Key database type, seleziona CMS. Questo è il formato letto da IBM HTTP Server.
• In File Name, inserisci un nome per il nuovo database (ad esempio key.kdb).
• In Location, indica una cartella che potrai ritrovare facilmente (ad esempio /opt/IBM/HTTPServer/ssl/ su Linux, o C:IBMHTTPServerssl su Windows). Fai clic su OK.
• Impostare una password forte, quindi selezionare Stash password to a file in modo che IKEYMAN scriva un file stash .sth corrispondente accanto al .kdb. IHS legge lo stash all’avvio, così non devi digitare la password ogni volta che il server si avvia. Fai clic su OK.

IKEYMAN crea due file in quella cartella: il database stesso (key.kdb) e lo stash (key.sth). Trattali entrambi come informazioni segrete. Mantieni le loro autorizzazioni di file rigide (leggibili solo dall’utente IHS) e fai un backup in un luogo sicuro, perché senza di essi non puoi recuperare la chiave privata.

Passo 2. Creare la richiesta di certificato

• Con il nuovo database aperto, trova il menu a discesa Key database content e cambialo in Personal Certificate Requests.
• Fai clic su New. Si apre la finestra di dialogo Create New Key and Certificate Request.

Compila i campi utilizzando solo caratteri ASCII standard; le lettere non latine interrompono la richiesta:

• Key Label: un breve identificativo per questo certificato all’interno del database di chiavi, ad esempio www.example.com. Farai riferimento a questa etichetta più avanti in httpd.conf con la direttiva SSLServerCert.
• Key Size: seleziona 2048. Questo è il minimo attuale accettato da ogni CA pubblica. Scegli 3072 o 4096 solo se la tua policy richiede una chiave più grande; il compromesso è un handshake TLS leggermente più lento.
• Signature Algorithm: scegli SHA256WithRSA (o più forte, come SHA384WithRSA). Evita qualsiasi cosa con SHA-1; le CA pubbliche non emetteranno certificati con questo algoritmo.
• Common Name: il nome di dominio completo (FQDN) che vuoi proteggere, ad esempio www.example.com. Per un certificato wildcard, metti un asterisco davanti al dominio principale, ad esempio *.example.com.
• Organization: il nome legale completo della tua azienda, esattamente come registrato. Obbligatorio per i certificati OV ed EV; ignorato per i DV.
• Organizational Unit: questo attributo è deprecato per i certificati pubblici (il CA/Browser Forum lo ha eliminato gradualmente). Lascialo vuoto o inserisci un’etichetta breve come IT.
• Locality: il nome completo della città (ad esempio Seattle, non SEA).
• State/Province: il nome completo dello stato o della provincia (ad esempio Washington, non WA).
• Country: il codice paese ISO a due lettere, ad esempio US, GB, o DE.
• Subject Alternative Names (SAN): aggiungi ogni hostname che dovrà apparire sul certificato, incluso il valore inserito nel Common Name. I browser moderni ignorano il Common Name e validano solo rispetto all’elenco SAN, quindi un certificato multi-nome ha bisogno di voci qui.
• Enter the name of a file in which to store the certificate request: un percorso e un nome che termina in .arm, ad esempio /opt/IBM/HTTPServer/ssl/www_example_com.arm. Salvalo nella stessa cartella del database di chiavi affinché i due rimangano insieme.

Fai clic su OK. IKEYMAN genera la coppia di chiavi all’interno del database di chiavi, memorizza la richiesta come voce in sospeso e scrive la CSR PKCS #10 nel file .arm che hai nominato.

Passo 3. Copiare la CSR e sottometterla alla CA

Apri il file .arm in un qualsiasi editor di testo (Notepad, vi, nano). Vedrai un blocco simile a questo:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIDXjCCAkYCAQAwgZQxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApXYXNoaW5ndG9u
... (many lines of base64) ...
-----END NEW CERTIFICATE REQUEST-----

Seleziona l’intero blocco, incluse le righe BEGIN ed END, copialo e incollalo nel campo CSR del tuo modulo d’ordine. La chiave privata rimane nel database di chiavi sul server; solo il testo della CSR lascia la macchina.

Metodo 2. Generare una CSR con gskcapicmd (CLI)

L’utility gskcapicmd (talvolta elencata come gskcmd per il wrapper Java, o come gsk8capicmd_64 nelle installazioni GSKit a 64 bit) svolge lo stesso lavoro di IKEYMAN senza una sessione grafica. Eseguila dalla directory bin di IHS.

Passo 1. Creare il database di chiavi CMS e il file stash

Scegli una cartella per il database di chiavi, quindi esegui:

gskcapicmd -keydb -create 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -type cms 
  -stash

Spiegazione degli argomenti:

• -db: il percorso completo del nuovo file .kdb.
• -pw: la password che protegge il database di chiavi.
• -type cms: il formato letto da IHS.
• -stash: scrive un file stash .sth corrispondente accanto al database, affinché IHS possa leggerlo senza chiedere la password all’avvio.

Sulla riga di comando, la password è visibile negli elenchi dei processi e nella cronologia della shell. Dopo che il database esiste, cambia la password con una che non sia registrata nella cronologia usando gskcapicmd -keydb -changepw, oppure passa la password tramite una variabile d’ambiente e poi annullala.

Passo 2. Creare la richiesta di certificato

Genera la coppia di chiavi e la CSR PKCS #10 in un solo passaggio, con voci SAN per ogni hostname che desideri sul certificato:

gskcapicmd -certreq -create 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -label www.example.com 
  -dn "CN=www.example.com,O=Example Inc,L=Seattle,ST=Washington,C=US" 
  -size 2048 
  -sigalg SHA256WithRSA 
  -san_dnsname "www.example.com,example.com" 
  -file /opt/IBM/HTTPServer/ssl/www_example_com.arm

Spiegazione degli argomenti:

• -label: l’identificativo per questo certificato all’interno del database di chiavi. Fai riferimento a esso più avanti da httpd.conf con la direttiva SSLServerCert.
• -dn: il Distinguished Name, scritto come una singola stringa con attributi separati da virgola. Usa CN= per l’FQDN e il codice ISO a due lettere in C=.
• -size: 2048 è il minimo. Usa 3072 o 4096 solo se la tua policy lo richiede.
• -sigalg: SHA256WithRSA (o SHA384WithRSA). Non usare SHA-1.
• -san_dnsname: un elenco separato da virgole di ogni hostname che deve apparire sul certificato. Includi in questo elenco il valore del Common Name. I browser e la maggior parte delle librerie TLS validano solo il SAN, non il CN.
• -file: il percorso in cui gskcapicmd scrive il file CSR .arm.

Se hai bisogno di una chiave ECDSA invece di RSA, sostituisci -sigalg SHA256WithRSA con -sigalg SHA256WithECDSA e cambia -size per adattarla alla curva desiderata (-size 256 per P-256, -size 384 per P-384). Le curve supportate sono secp256r1 (P-256), secp384r1 (P-384), e secp521r1 (P-521). Il supporto ECDSA in IHS è completamente esposto solo tramite gskcapicmd; IKEYMAN non permette di scegliere ECDSA sulle versioni IHS più vecchie. Per ECDSA su una versione IHS specifica, segui le linee guida IBM sulla gestione dei certificati.

Passo 3. Elencare e verificare la richiesta

Confermare che la richiesta sia stata aggiunta al database di chiavi:

gskcapicmd -certreq -list 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password

Per leggere nuovamente la CSR e verificare il Common Name, le voci SAN, la dimensione della chiave e l’algoritmo di firma:

gskcapicmd -certreq -details 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -label www.example.com

Quindi apri il file .arm in un editor di testo, copia il blocco completo da BEGIN NEW CERTIFICATE REQUEST a END NEW CERTIFICATE REQUEST, e sottomettilo nel modulo d’ordine della tua CA.

Verificare la CSR prima di sottometterla (opzionale)

Se hai OpenSSL installato, esegui questo comando sulla stessa macchina per confermare il soggetto, l’elenco SAN e la dimensione della chiave:

openssl req -noout -text -in www_example_com.arm

Preferisci uno strumento online? Incolla il contenuto della richiesta nel Decodificatore CSR di SSL Dragon per leggere di nuovo gli stessi dettagli. Conferma che il Common Name corrisponda all’hostname che utilizzeranno i client e che ogni hostname richiesto appaia sotto Subject Alternative Name.

Dopo che la CA emette il tuo certificato

Il certificato firmato deve tornare nello stesso database di chiavi che ha prodotto la CSR, con la stessa etichetta. Riceverlo con la CLI:

gskcapicmd -cert -receive 
  -db /opt/IBM/HTTPServer/ssl/key.kdb 
  -pw your_strong_password 
  -file www_example_com.crt

Oppure fai la stessa cosa in IKEYMAN sotto Personal Certificates > Receive. Aggiungi prima i certificati root e intermedi come certificati firmatari, poi aggiorna httpd.conf con le direttive KeyFile e SSLServerCert e riavvia IHS. La procedura completa è trattata in come installare un certificato SSL su IBM HTTP Server.

Generare una CSR su HCL Domino

Nota: IBM Domino è ora HCL Domino. HCL ha chiuso l’acquisizione del portafoglio di collaborazione di IBM (incluso Notes/Domino) il 1° luglio 2019. Su Domino 12 e versioni successive, HCL raccomanda l’attività Certificate Manager (con certstore.nsf e documenti TLS Credentials) per tutte le nuove operazioni TLS. Il database classico Server Certificate Administration (CERTSRV.NSF) funziona ancora per le installazioni legacy ed è documentato di seguito, ma i nuovi deployment dovrebbero usare Certificate Manager.

Metodo A. Creare una CSR con Certificate Manager (Domino 12+ / 14.x)

• Aggiungi l’attività CertMgr sul server designato come Certificate Manager, in modo che crei certstore.nsf. Su ogni server Domino che deve leggere le chiavi TLS, esegui anche CertMgr affinché il database si replichi.
• Apri certstore.nsf, vai a TLS Credentials, e fai clic su Add TLS Credentials.
• Host names: inserisci l’FQDN esatto che utilizzeranno i client, e aggiungi ogni hostname aggiuntivo come Subject Alternative Name.
• Servers with access: seleziona i server Domino che devono poter leggere la chiave privata.
• Certificate Provider: scegli Manual per qualsiasi CA di terze parti. (Scegli Let’s Encrypt solo se desideri che CertMgr ottenga automaticamente un certificato gratuito emesso tramite ACME.)
• Key type: scegli RSA o ECDSA.
• RSA: seleziona 2048 bit (o più grande se la tua policy lo richiede).
• ECDSA: scegli una curva (P-256 o P-384; P-384 è l’impostazione predefinita indicata).
• Fai clic su Submit Request. CertMgr genera la coppia di chiavi, firma la CSR e il documento passa a Status = Waiting.
• Apri il documento, copia il valore di Certificate signing request (CSR) (o usa l’azione Copy CSR che appare dopo l’elaborazione), e incolla il blocco PEM nel modulo d’ordine della tua CA.

La chiave privata rimane all’interno di certstore.nsf, crittografata per i server che hai autorizzato. Non la esporti mai. Quando la CA emette il tuo certificato, incolla il certificato firmato (più la catena di emissione) di nuovo nello stesso documento TLS Credentials e CertMgr lo installerà per te. Il riferimento completo si trova nella documentazione di Certificate Manager di HCL.

Metodo B. Server Certificate Administration classico (Domino legacy)

Usa questo metodo solo su versioni di Domino che si basano ancora su file key ring (.kyr + .sth). HCL lo contrassegna come legacy su Domino 12 e versioni successive.

• Nel client Domino Administrator, apri Server Certificate Administration.
• Scegli Create Key Ring. Inserisci un nome per il key ring e una password forte.
• Key Size: seleziona 2048 bit.
• Compila il Distinguished Name:
• Common Name: l’FQDN che vuoi proteggere, ad esempio www.example.com.
• Organization: il nome legale completo della tua azienda.
• Organizational Unit: lascia vuoto oppure inserisci un’etichetta breve come IT (l’attributo è deprecato per i certificati pubblici).
• City or Locality: il nome completo della città, ad esempio Seattle.
• State or Province: il nome completo dello stato, ad esempio Washington.
• Country: il codice ISO a due lettere, ad esempio US.
• Rivedi i dettagli e fai clic su Continue. Domino crea il file key ring.
• Scegli Create Certificate Request. Sotto Method, scegli Paste into form on CA’s site. Domino visualizza il testo della CSR.
• Copia l’intero blocco CSR (incluse le righe BEGIN ed END) e incollalo nel modulo d’ordine della tua CA.

I file key ring classici non supportano voci SAN tramite questa finestra di dialogo. Se hai bisogno di un certificato multi-nome, passa a Certificate Manager (Metodo A) o genera la CSR fuori dal server.

Domande frequenti