Wie man einen CSR auf GlassFish generiert

Dieses Tutorial zeigt Ihnen wie Sie einen CSR (Certificate Signing Request) für GlassFish generieren (heute Eclipse GlassFish) mit dem Java-keytool-Werkzeug.

GlassFish ist auf hilfreiche Weise ungewöhnlich: Eine frische Installation liefert bereits einen Keystore mit (keystore.p12 bei Eclipse GlassFish 7.1 und neuer, oder keystore.jks bei älteren Versionen) sowie einen Standard-Zertifikatseintrag unter dem Alias s1as. Sie können den CSR direkt aus diesem vorhandenen Schlüssel erzeugen oder ihn durch einen neuen Schlüssel unter demselben Alias ersetzen. In beiden Fällen wird derselbe Alias beim Import des signierten Zertifikats wiederverwendet, sodass der Schlüssel, der CSR und das ausgestellte Zertifikat alle an einem Ort liegen.

Was Sie benötigen

• Eine funktionierende GlassFish- (oder Eclipse GlassFish-) Installation. Der Standard-Keystore befindet sich im config-Verzeichnis der Domain, zum Beispiel glassfish/domains/domain1/config/keystore.p12 bei Eclipse GlassFish 7.1 und neuer, oder keystore.jks bei älteren Versionen.
• Eine Java-Installation, damit der Befehl keytool verfügbar ist. GlassFish wird mit einem JDK ausgeliefert, daher ist keytool normalerweise bereits im Pfad. Prüfen Sie dies mit keytool -help.
• Shell- oder Terminalzugriff auf den GlassFish-Server. Der private Schlüssel muss auf diesem Server verbleiben.
• Den genauen vollqualifizierten Domainnamen (FQDN), den Sie absichern möchten, zum Beispiel www.ihredomain.de, sowie alle zusätzlichen Hostnamen für das SAN-Feld.
• Die rechtlichen Angaben Ihrer Organisation (Land, Bundesland/Kanton, Ort, Organisationsname) für den Distinguished Name des CSR.
• Das GlassFish-Master-Passwort für die Domain. Der werkseitige Standardwert ist changeit; ändern Sie ihn auf Produktivsystemen mit asadmin change-master-password.

Zwei Wege, um den CSR zu generieren

Wenn Sie Ihren CSR bereits generiert haben, springen Sie direkt zu CSR einreichen und anschließend zu SSL-Zertifikat auf GlassFish installieren.

Es gibt zwei gängige keytool-Abläufe auf GlassFish. Wählen Sie den, der zu Ihrer Situation passt:

• Option A: CSR aus dem vorhandenen s1as-Schlüssel generieren (empfohlen). Eine neue GlassFish-Domain verfügt bereits über einen privaten Schlüssel unter dem Alias s1as im Standard-Keystore (keystore.p12 bei 7.1+, keystore.jks bei älteren Versionen). Der schnellste und risikoärmste Weg besteht darin, diesen Schlüssel unverändert zu lassen und lediglich einen CSR daraus zu exportieren. Springen Sie zu Option A.
• Option B: Den Standard-s1as-Schlüssel durch einen neuen Schlüssel ersetzen und anschließend den CSR generieren. Nutzen Sie dies, wenn Sie eine bekannte, aktuelle Schlüsselgröße und einen bestimmten DN wünschen, oder wenn Sie vermuten, dass der Standardschlüssel bereits verwendet oder offengelegt wurde. Springen Sie zu Option B.

Unabhängig davon, welche Option Sie wählen, muss der Alias s1as bleiben (oder, falls Sie ihn ändern, müssen Sie auch domain.xml entsprechend anpassen). Der HTTPS-Listener von GlassFish sucht das Zertifikat anhand des Alias, sodass ein abweichender Alias dazu führt, dass GlassFish den Schlüssel nicht findet und TLS nicht startet.

Option A: CSR aus dem vorhandenen s1as-Schlüssel generieren

Schritt 1: In das GlassFish-config-Verzeichnis wechseln

Öffnen Sie ein Terminal und wechseln Sie in das Verzeichnis, das den Keystore für Ihre Domain enthält. Bei einer Standardinstallation ist das der config-Ordner von domain1:

cd /opt/glassfish7/glassfish/domains/domain1/config

Passen Sie den Pfad an den Ort an, an dem Sie GlassFish installiert haben (ältere GlassFish-4-Versionen verschachteln die Installation unter einem übergeordneten glassfish4/-Ordner; Eclipse GlassFish 6, 7 und 8 werden typischerweise unter glassfish7/, glassfish8/ oder ähnlichem installiert). Wenn Sie eine eigene Domain erstellt haben, ersetzen Sie domain1 durch den Namen dieser Domain. Führen Sie in diesem Verzeichnis ls *.p12 *.jks aus, um den Keystore-Dateinamen zu bestätigen: Bei Eclipse GlassFish 7.1 und neuer sehen Sie keystore.p12; bei älteren Versionen sehen Sie keystore.jks. Ersetzen Sie diesen Dateinamen überall dort, wo die folgenden Befehle keystore.jks zeigen.

Schritt 2: Vorhandensein des s1as-Eintrags bestätigen

Listen Sie den Inhalt des Keystores auf und prüfen Sie, ob s1as vorhanden und ein PrivateKeyEntry ist:

keytool -list -v -keystore keystore.jks -alias s1as

Geben Sie das Keystore-Passwort ein (werkseitiger Standardwert changeit; auf einem Produktivserver sollte es dem Master-Passwort Ihrer Domain entsprechen). Die Ausgabe sollte die Zeile Entry type: PrivateKeyEntry enthalten. Erhalten Sie stattdessen die Meldung Alias <s1as> does not exist, wechseln Sie zu Option B und erstellen Sie einen neuen Eintrag.

Schritt 3: CSR mit SAN exportieren

Moderne Browser und TLS-Clients validieren Zertifikate anhand der Erweiterung Subject Alternative Name (SAN), nicht allein anhand des Common Name. Fordern Sie die SANs direkt im CSR an, damit die CA sie in das ausgestellte Zertifikat aufnimmt:

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Was die Optionen bedeuten:

• -alias s1as: der vorhandene GlassFish-Zertifikatsalias. Der private Schlüssel unter diesem Alias signiert die Anfrage.
• -keystore keystore.jks: die Standard-Keystore-Datei von GlassFish. Eclipse GlassFish 7.1 und neuer liefern einen PKCS12-Keystore namens keystore.p12; ältere Versionen verwenden einen JKS-Keystore namens keystore.jks. Verwenden Sie den Dateinamen, der tatsächlich in diesem Verzeichnis vorhanden ist. Der Befehl selbst ist in beiden Fällen identisch; keytool erkennt das Format automatisch.
• -file glassfish.csr: der Ausgabedateiname für den CSR. Wählen Sie einen beliebigen Namen.
• -ext san=dns:…: die Erweiterung Subject Alternative Name. Listen Sie jeden Hostnamen auf, den das Zertifikat abdecken muss, einschließlich sowohl der reinen Apex-Domain (yourdomain.com) als auch der www-Subdomain. Fügen Sie weitere Einträge kommagetrennt hinzu, zum Beispiel dns:api.yourdomain.com.

keytool fragt nach dem Keystore-Passwort und schreibt den CSR in glassfish.csr im aktuellen Verzeichnis. Der Subject (Distinguished Name) des CSR wird aus dem übernommen, was im s1as-Eintrag gespeichert ist; bei einer frischen GlassFish-Installation ist das das automatisch generierte selbstsignierte Zertifikat, sodass der DN nicht Ihrem Unternehmen entspricht. Die meisten CAs prüfen nur den Common Name und die SAN-Liste und lassen Sie den Rest des DN im Bestellformular überschreiben. Wenn Sie jedoch einen CSR benötigen, dessen DN bereits Ihre rechtlichen Unternehmensangaben enthält, verwenden Sie Option B.

Option B: Den Standard-s1as-Schlüssel durch einen neuen ersetzen

Verwenden Sie diese Option, wenn Sie die volle Kontrolle über Schlüsselgröße und DN wünschen, oder wenn Sie den werkseitig generierten Schlüssel lieber nicht weiterverwenden möchten. Der Ablauf ist: den Standard-s1as-Eintrag löschen, einen neuen Schlüssel unter demselben Alias erstellen und dann den CSR exportieren. Wenn Sie den Alias als s1as beibehalten, müssen Sie domain.xml anschließend nicht anfassen.

Schritt 1: Keystore sichern

Bevor Sie irgendetwas löschen, kopieren Sie den aktuellen Keystore, damit Sie bei Bedarf zurückkehren können. Aus dem config-Verzeichnis der Domain:

cp keystore.jks keystore.jks.bak

Schritt 2: Standard-s1as-Eintrag löschen

keytool -delete -alias s1as -keystore keystore.jks

Geben Sie bei Aufforderung das Keystore-Passwort ein.

Schritt 3: Neuen privaten Schlüssel unter demselben Alias erstellen

Generieren Sie einen neuen 2048-Bit-RSA-Schlüssel unter dem Alias s1as und übergeben Sie den DN direkt inline, damit der Befehl nicht interaktiv ist:

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

Was die Optionen bedeuten:

• -alias s1as: verwendet den Standard-GlassFish-Alias erneut, sodass domain.xml nicht geändert werden muss.
• -keyalg RSA -keysize 2048: ein 2048-Bit-RSA-Schlüssel ist derzeit das öffentliche Minimum. Für neue Schlüssel, die Sie mehrere Jahre lang behalten möchten, ist 3072 Bit ein sinnvolles Upgrade. Die meisten öffentlichen CAs akzeptieren auch ECDSA (-keyalg EC -groupname secp256r1) für einen kleineren, schnelleren Schlüssel.
• -keystore keystore.jks: der Standard-Keystore von GlassFish. Ersetzen Sie dies durch keystore.p12 bei Eclipse GlassFish 7.1 und neuer. keytool behält das vorhandene Keystore-Format bei (JKS bei älteren Installationen, PKCS12 bei 7.1+); beides ist hier in Ordnung.
• -dname „CN=…“: die Distinguished-Name-Felder, die in den CSR geschrieben werden. Verwenden Sie Ihre genauen, rechtsgültigen Unternehmensangaben:

• CN: der genaue FQDN, den Sie absichern, zum Beispiel www.ihredomain.de, oder ein Wildcard wie *.ihredomain.de. Geben Sie keinen Personennamen ein, auch wenn der interaktive Modus von keytool dies suggeriert.
• O: der vollständige rechtliche Name Ihres Unternehmens.
• L: der vollständige Ortsname (nicht abkürzen).
• ST: der vollständige Name des Bundeslands oder der Provinz (kein zweistelliger Code verwenden).
• C: der zweistellige ISO-Ländercode, zum Beispiel US, GB, DE.
• OU (Organizational Unit): dieses Feld wird von öffentlichen CAs nicht mehr ausgestellt. Lassen Sie es im DN weg.

keytool fragt nach dem Keystore-Passwort und dem Schlüsselpasswort. Bei einer GlassFish-Domain müssen das Keystore-Passwort, das Schlüsselpasswort und das Master-Passwort der Domain übereinstimmen, andernfalls kann GlassFish den Schlüssel beim Start nicht entsperren und HTTPS funktioniert nicht. Drücken Sie bei der Aufforderung zum Schlüsselpasswort die Eingabetaste, um das Keystore-Passwort erneut zu verwenden.

Schritt 4: CSR mit SAN exportieren

Derselbe Befehl wie bei Option A, ausgeführt mit Ihrem neuen Schlüssel:

keytool -certreq 
  -alias s1as 
  -keystore keystore.jks 
  -file glassfish.csr 
  -ext san=dns:yourdomain.com,dns:www.yourdomain.com

Geben Sie das Keystore-Passwort ein. keytool schreibt den CSR in glassfish.csr im aktuellen Verzeichnis.

Wichtig: Alias als s1as beibehalten

Der häufigste keytool-Fehler bei GlassFish besteht darin, den Alias irgendwann im Verlauf zu ändern, sei es bei der Schlüsselerzeugung oder beim Import des signierten Zertifikats. Zwei Fehlerbilder treten dabei auf:

• Falscher Alias am Schlüssel. Der HTTPS-Listener von GlassFish ist in domain.xml fest mit s1as verknüpft. Erzeugen Sie einen Schlüssel unter einem anderen Alias, kann GlassFish ihn nicht finden und der Listener greift auf das standardmäßige selbstsignierte Zertifikat zurück (oder startet gar nicht). Wenn Sie wirklich einen anderen Alias verwenden möchten, müssen Sie jede s1as-Referenz in domain.xml entsprechend anpassen.
• Falscher Alias beim Import. Wenn die CA Ihr signiertes Zertifikat zurückgibt, müssen Sie es wieder in denselben Alias importieren, der den privaten Schlüssel enthält. Der Import unter einem völlig neuen Alias speichert das Zertifikat als eigenständigen vertrauenswürdigen Eintrag ohne zugehörigen privaten Schlüssel, und TLS funktioniert dann nicht.

Notieren Sie sich diese drei Werte, bevor Sie das Terminal schließen:

• Den Alias (Standard s1as; beibehalten).
• Den Keystore-Dateipfad, zum Beispiel glassfish/domains/domain1/config/keystore.p12 (oder keystore.jks bei älteren Versionen).
• Das Keystore-Passwort (das dem Master-Passwort der Domain entsprechen muss).

CSR vor dem Einreichen überprüfen

Entdecken Sie Tippfehler im DN oder fehlende SANs, bevor die CA sie validiert. Geben Sie den CSR mit keytool aus:

keytool -printcertreq -file glassfish.csr

Oder, falls OpenSSL installiert ist, verwenden Sie stattdessen dieses:

openssl req -noout -text -in glassfish.csr

Bestätigen Sie drei Dinge in der Ausgabe: Der Subject zeigt Ihren genauen DN, der Subject Alternative Name listet jeden benötigten Hostnamen auf, und die Public-Key-Größe entspricht dem, was Sie angefordert haben (2048-Bit-RSA oder was auch immer Sie gewählt haben). Sie können den CSR auch in unseren CSR-Decoder einfügen, um dieselbe Prüfung in einem Browser durchzuführen.

CSR bei Ihrer Zertifizierungsstelle einreichen

Öffnen Sie glassfish.csr in einem beliebigen Texteditor. Die Datei ist reiner Text, beginnend mit —–BEGIN CERTIFICATE REQUEST—– und endend mit —–END CERTIFICATE REQUEST—–. Kopieren Sie den gesamten Block, einschließlich dieser Kopf- und Fußzeilen, und fügen Sie ihn beim Bestellvorgang bei Ihrer CA in das CSR-Feld ein. Verwenden Sie unter Windows Strg + A und dann Strg + C, um den vollständigen Text zu erfassen; unter macOS verwenden Sie Cmd + A und dann Cmd + C.

Nachdem die CA Ihre Anfrage validiert und das Zertifikat ausgestellt hat, fahren Sie fort mit wie Sie Ihr SSL-Zertifikat auf GlassFish installieren. Sie importieren die CA-Kette als vertrauenswürdig, importieren dann das signierte Zertifikat zurück in den Alias s1as in der gleichen Keystore-Datei (keystore.p12 bei 7.1+, keystore.jks bei älteren Versionen) und richten schließlich den HTTPS-Listener auf diesen Alias aus.