Wie man mit Java Keytool eine CSR für ein Code Signing-Zertifikat generiert

Das keytool-Dienstprogramm, das mit dem Java Development Kit (JDK) ausgeliefert wird, erstellt ein Schlüsselpaar innerhalb eines Java-Keystores und wandelt es in einen CSR (Certificate Signing Request) um, den kodierten Block, den eine Certificate Authority (CA) liest, um Sie zu identifizieren, bevor sie ein Zertifikat ausstellt. Für die Codesignierung hat sich am 1. Juni 2023 geändert, wofür keytool rechtmäßig verwendet werden darf. Diese Anleitung nennt zunächst die Regel und geht dann die keytool-Befehle durch, die weiterhin korrekt sind: gegen einen Software-Keystore für die interne Signierung und gegen ein Hardware-Token oder HSM über PKCS#11.

Codesignierungsschlüssel müssen auf Hardware generiert werden

Seit dem 1. Juni 2023 verlangen die CA/Browser Forum Code Signing Baseline Requirements, dass der private Schlüssel für jedes öffentlich vertrauenswürdige Codesignierungszertifikat in einem Hardware-Kryptomodul generiert und gespeichert wird, das FIPS 140-2 Level 2, Common Criteria EAL4+ oder einen gleichwertigen Standard erfüllt. Der Schlüssel muss nicht exportierbar sein. Dies gilt sowohl für Standardzertifikate (Organization Validation) als auch für Extended-Validation-Zertifikate. EV-Codesignierung erforderte schon immer Hardware; die Änderung von 2023 hat dieselbe Regel auf Standardzertifikate ausgeweitet. Dieselben Anforderungen legen für Codesignierungszertifikate eine Mindestschlüsselgröße von RSA 3072 fest, die seit dem 1. Juni 2021 in Kraft ist.

Die Konsequenz für diese Seite ist unmittelbar. Eine Keystore-Datei, die keytool auf Ihrem Laptop oder Server erstellt, sei es im PKCS12- oder im älteren JKS-Format, enthält einen Software-Schlüssel. Ein daraus erzeugter CSR wird von einer öffentlichen Certificate Authority für ein Codesignierungszertifikat nicht akzeptiert. Certificate Authorities unterstützen browserbasierte Schlüsselerzeugung und herunterladbare Schlüsseldateien für diese Produkte nicht mehr. Ihr Schlüssel entsteht nun an einem von zwei Orten:

• Ein vorkonfiguriertes Token, das die CA an Sie versendet. Die CA erzeugt das Schlüsselpaar und den CSR auf ihrer Seite auf einem zertifizierten USB-Token, lädt das ausgestellte Zertifikat darauf und schickt Ihnen das Token per Post. Sie müssen keinen CSR erstellen.
• Ihr eigenes HSM oder Token mit Schlüsselattestierung. Sie erzeugen den Schlüssel innerhalb des Geräts, erstellen daraus einen CSR und reichen eine Attestierungsdatei ein, die der CA belegt, dass der Schlüssel auf konformer Hardware erstellt wurde und nicht exportiert werden kann. Beide Teile sind erforderlich; ein CSR ohne gültige Attestierung wird abgelehnt.

Welcher Weg zutrifft, wird bei der Bestellung entschieden. Für den Vergleich siehe die Liefermethoden für Codesignierungszertifikate. Wenn Sie bereits über konforme Hardware verfügen, folgen Sie der Anleitung für Ihr Gerät: YubiKey 5 FIPS CSR-Erstellung und Attestierung oder der Anleitung Luna Network Attached HSM v7.x CSR und Attestierung.

Wo keytool weiterhin seinen Platz hat

Nichts von alledem macht keytool überflüssig. Es bleibt in drei Situationen das richtige Werkzeug, und nur die erste davon liefert einen CSR, den Sie an eine öffentliche CA senden können:

• Als PKCS#11-Frontend zu Ihrem Token oder HSM. keytool spricht PKCS#11 nativ. Verweisen Sie es auf die PKCS#11-Bibliothek Ihres Herstellers, dann verlässt der Schlüssel niemals das Gerät, während der vertraute Befehl -certreq weiterhin den CSR erzeugt. Die Befehle finden Sie im Hardware-Abschnitt weiter unten.
• Für interne oder unternehmensweite Signierung. Wenn Sie hausinterne Software mit der eigenen CA Ihrer Organisation signieren, bestimmt Ihre interne Richtlinie die Schlüsselspeicherung, nicht die öffentlichen Baseline Requirements. Ein Software-Keystore ist dort eine normale Wahl.
• Zum Üben. Den Subject-Namen beim ersten Versuch richtig hinzubekommen fällt leichter, wenn Sie die Eingabeaufforderungen einmal an einem Wegwerf-Keystore durchgespielt haben.

Eine Einschränkung, die Sie kennen sollten, bevor Sie beginnen: keytool erzeugt keine Schlüsselattestierung. Die Attestierung wird von der eigenen Software des Token- oder HSM-Herstellers erzeugt, sodass Sie selbst auf dem PKCS#11-Weg das Herstellerwerkzeug für diese Datei verwenden und keytool nur für den CSR.

Den CSR mit keytool erzeugen

Wenn Sie Ihren CSR bereits erstellt haben und die Certificate Authority das Zertifikat ausgestellt hat, springen Sie weiter zum Importieren der CA-Antwort, dem Schritt, der stillschweigend fehlschlägt, wenn der Alias nicht übereinstimmt.

keytool wird mit dem JDK ausgeliefert. Installieren Sie also zunächst ein aktuelles JDK, falls Sie noch keines haben. JDK 25 ist die aktuelle Long-Term-Support-Version und JDK 26 die aktuelle Short-Term-Version. Die folgenden Befehle laufen unter JDK 17 und neuer, und relevante Versionsunterschiede werden an den entsprechenden Stellen erwähnt. Prüfen Sie, ob das Werkzeug in Ihrem Pfad liegt:

java -version
keytool -help
jarsigner -version

Eine Java Runtime Environment allein reicht nicht aus, und ein funktionierendes keytool ist kein Beweis dafür, dass Sie ein JDK haben: Die alte Oracle JRE 8 liefert keytool, aber nicht jarsigner mit. Führen Sie jetzt alle drei Befehle aus. Wenn die ersten beiden antworten und der dritte nicht, befinden Sie sich auf einer JRE, und die Installation eines JDK ist zu diesem Zeitpunkt einfacher, als es erst beim Signieren zu entdecken.

Schritt 1: Keystore und Schlüsselpaar erstellen

Führen Sie dies in einem Terminal aus, oder unter Windows in der Eingabeaufforderung oder PowerShell, im Verzeichnis, in dem die Keystore-Datei liegen soll:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12

Vier Details in diesem Befehl unterscheiden sich von älteren Anleitungen, und jedes davon ist wichtig:

• -genkeypair, nicht -genkey. Die alte Schreibweise -genkey funktioniert weiterhin und keytool gibt keine Warnung dazu aus, aber sie wird im Quellcode nur noch als veralteter Alias geführt und taucht in der JDK-Dokumentation nirgends mehr auf. Schreiben Sie -genkeypair.
• -storetype PKCS12, nicht JKS. JKS ist das proprietäre Keystore-Format von Oracle. PKCS12 ist der Industriestandard und ist seit Java 9 der JDK-Standard. Wenn Sie trotzdem einen JKS-Keystore erstellen, warnt keytool bei jedem Befehl, der ihn betrifft: „The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format.“
• Der Dateiname bestimmt nicht das Format. Eine Datei keystore.jks zu nennen macht sie nicht zu einem JKS-Keystore. keytool entnimmt den Typ aus -storetype oder, wenn Sie diese Option weglassen, aus der Eigenschaft keystore.type in der Sicherheitsdatei des JDK. Ab JDK 9 lautet diese Eigenschaft pkcs12, sodass ein Befehl, der ohne -storetype nach keystore.jks schreibt, stillschweigend eine PKCS12-Datei mit irreführendem Namen erzeugt.
• -keysize 3072, nicht 2048. Die Baseline Requirements legen RSA 3072 als Mindestwert für die Codesignierung fest, sodass eine 2048-Bit-Anfrage abgelehnt wird. Aktuelle JDKs verwenden standardmäßig 3072 für RSA, aber JDK 17 und früher verwenden standardmäßig 2048, geben Sie die Option also explizit an, damit sich der Befehl überall gleich verhält.

Der Alias, im Beispiel codesign, ist die Bezeichnung für diesen Eintrag innerhalb des Keystores. Wählen Sie etwas Wiedererkennbares und notieren Sie es sich: Jeder spätere Befehl benötigt ihn, und eine Diskrepanz ist genau das, was den weiter unten beschriebenen Zertifikatsimport zum Scheitern bringt.

Ein ECDSA-Schlüssel ist ebenfalls zulässig. Ersetzen Sie die RSA-Optionen durch -keyalg EC -groupname secp256r1, wenn Sie P-256 bevorzugen, und bestätigen Sie bei Ihrer CA, dass das von Ihnen bestellte Produkt ECDSA unterstützt.

Schritt 2: Die Eingabeaufforderungen zum Aufbau Ihres Distinguished Name beantworten

keytool fragt zweimal nach einem Keystore-Passwort und stellt dann in genau dieser Reihenfolge sechs Fragen. Die Reihenfolge ist wichtig: Die zweite Eingabeaufforderung fragt nach der Organisationseinheit, nicht nach der Organisation, und ältere Anleitungen listen dies falsch auf, sodass Leser, die dort den Firmennamen eingeben, ihn in der falschen Komponente des Namens platzieren.

• Wie lauten Ihr Vor- und Nachname? Dies wird trotz der Formulierung zum Common Name (CN). Bei einem Codesignierungszertifikat ist der CN die Identität des Herausgebers, die Nutzer sehen werden, geben Sie also den genauen rechtlichen Namen Ihrer Organisation ein oder, bei einem individuellen Zertifikat, Ihren eigenen vollständigen rechtlichen Namen. Geben Sie hier keinen Domainnamen ein.
• Wie lautet der Name Ihrer Organisationseinheit? Die Abteilung, zum Beispiel IT. Drücken Sie nicht einfach die Eingabetaste, um dies zu überspringen: keytool schreibt dann den wörtlichen Wert Unknown in den Namen, und OU=Unknown landet in Ihrem CSR. Wenn Sie gar keine Organisationseinheit möchten, verwenden Sie die unten beschriebene -dname-Form und lassen Sie die OU-Komponente aus der Zeichenkette weg.
• Wie lautet der Name Ihrer Organisation? Der eingetragene rechtliche Name, geschrieben wie in offiziellen Registern angegeben. Die CA prüft dies gegen öffentliche Register.
• Wie lautet der Name Ihrer Stadt oder Ihres Ortes? Die Registrierungsstadt, vollständig ausgeschrieben.
• Wie lautet der Name Ihres Bundesstaats oder Ihrer Provinz? Der vollständige Name, keine Abkürzung.
• Wie lautet der zweistellige Ländercode für diese Einheit? Der ISO-Code, zum Beispiel US.

keytool gibt dann den zusammengesetzten Namen aus und bittet Sie um Bestätigung:

Is CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US correct?
  [no]:

Die Standardantwort ist no, sodass das Drücken der Eingabetaste Sie zurück durch alle sechs Fragen schickt. Geben Sie yes ein, um zu akzeptieren. Lesen Sie die Zeile zuerst sorgfältig: Dies ist der gesamte Distinguished Name, nicht nur der Common Name, und jede seiner Komponenten fließt in den CSR ein.

Bei einem PKCS12-Keystore gibt es kein separates Schlüsselpasswort. Ältere Anleitungen beenden diesen Schritt mit „Geben Sie ein Passwort für den Schlüssel ein“, was JKS-Verhalten ist. Bei einem PKCS12-Keystore entspricht das Schlüsselpasswort dem Store-Passwort, und wenn Sie -keypass mit einem abweichenden Wert übergeben, weist keytool Sie darauf hin: „Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.“

Um die Eingabeaufforderungen ganz zu überspringen, übergeben Sie den vollständigen Namen mit -dname. Setzen Sie den Wert in ein Paar gerader Anführungszeichen:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12 -dname "CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US"

Lassen Sie -storepass in der Befehlszeile weg und lassen Sie keytool danach fragen. Ein Passwort als Argument zu übergeben, schreibt es in Ihren Shell-Verlauf und macht es für jeden zugänglich, der laufende Prozesse auflisten kann.

Schritt 3: Den CSR erstellen

Der Keystore enthält nun einen privaten Schlüssel und ein temporäres selbstsigniertes Zertifikat. Wandeln Sie diesen Eintrag in eine Zertifikatsanfrage um:

keytool -certreq -alias codesign -keystore codesign.p12 -file codesign.csr

Geben Sie bei Aufforderung das Keystore-Passwort ein. -storetype benötigen Sie hier nicht: keytool erkennt das Format einer bereits vorhandenen Keystore-Datei. Der Alias muss der aus Schritt 1 sein, da der CSR mit dem privaten Schlüssel dieses Eintrags signiert wird.

Dieser Befehl erzeugt keinen privaten Schlüssel. Der Schlüssel wurde in Schritt 1 erstellt und bleibt im Keystore, weshalb die Keystore-Datei und ihr Passwort nun ebenso sensibel sind wie der Schlüssel selbst. Wer beides besitzt, kann Software in Ihrem Namen signieren.

Schritt 4: Den CSR vor dem Versand überprüfen

Ein abgelehnter CSR kostet einen Validierungszyklus, decodieren und lesen Sie ihn also nach:

keytool -printcertreq -file codesign.csr

Bestätigen Sie drei Dinge in der Ausgabe. Die Zeile Subject sollte Ihre Angaben in den richtigen Komponenten auflisten, mit dem rechtlichen Organisationsnamen in O und der Herausgeberidentität in CN. Die Zeile für den öffentlichen Schlüssel sollte 3072-bit RSA key oder größer angeben. Der Signaturalgorithmus sollte ein SHA-2-Algorithmus sein: Aktuelle JDKs signieren eine 3072-Bit-RSA-Anfrage mit SHA384withRSA, ältere verwenden SHA256withRSA, beides ist in Ordnung. Dieser Algorithmus beweist nur, dass Sie den privaten Schlüssel besitzen, und ist nicht der Algorithmus, mit dem die CA Ihr Zertifikat signieren wird.

Sie können die Anfrage auch in unseren CSR-Decoder einfügen, um dieselben Felder in einem Browser zu lesen.

Wenn Sie die Anfrage einreichen, öffnen Sie die Datei in einem reinen Texteditor und kopieren Sie alles, einschließlich der ersten und letzten Zeile. keytool schreibt diese genauen Markierungen mit jeweils fünf Bindestrichen auf beiden Seiten:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIID3TCCAkUCAQAwaDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExDjAM
...base64 encoded request...
-----END NEW CERTIFICATE REQUEST-----

Die Formulierung NEW CERTIFICATE REQUEST ist bei keytool-Ausgaben normal und wird von Registrierungsformularen akzeptiert. Wenn Ihr Editor eine Folge von Bindestrichen durch einen langen Gedankenstrich ersetzt hat, wird die Anfrage abgelehnt: Tippen Sie die Markierungen als einfache Bindestriche neu ein oder kopieren Sie die Datei stattdessen mit einem Code-Editor.

Den CSR auf einem Token oder HSM mit keytool erzeugen

Dies ist der Weg, der einen CSR liefert, mit dem eine öffentliche CA arbeiten kann. keytool kommuniziert über den SunPKCS11-Provider mit einem Hardware-Token, sodass das Schlüsselpaar innerhalb des Geräts erzeugt wird und niemals als Datei existiert. Beginnen Sie damit, eine kleine Konfigurationsdatei zu schreiben, zum Beispiel token.cfg, die Ihr Token benennt und auf die von Ihrem Hersteller installierte PKCS#11-Bibliothek verweist:

name = token
library = /usr/local/lib/libeToken.so

Diese beiden Zeilen, name und library, sind die einzigen erforderlichen. Der Bibliothekspfad ist herstellerspezifisch und unterscheidet sich je nach Betriebssystem, entnehmen Sie ihn also Ihrer Token-Dokumentation und nicht diesem Beispiel. Unter Windows ist es eine DLL im Systemverzeichnis. Ohne Slot-Zeile hängt sich der Provider an den ersten vom Gerät gemeldeten Slot an, was genau richtig ist, wenn ein einzelnes Token eingesteckt ist. Wenn Sie mehr als einen Leser oder ein Token haben, fügen Sie entweder slotListIndex mit der Position in dieser Liste, beginnend bei null, oder slot mit der numerischen Slot-ID hinzu, die Ihr Hersteller-Tool ausgibt. Nur eines der beiden darf in der Datei erscheinen, und eine Slot-ID ist nicht dieselbe Zahl wie eine Listenposition, raten Sie also nicht einfach slot = 0.

Listen Sie auf, was sich auf dem Gerät befindet. Das Token liefert den Alias, daher benötigen Sie dies vor allem anderen:

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg

-keystore NONE ist immer dann erforderlich, wenn der Keystore keine Datei ist, und die Passwortabfrage fragt nach der Token-PIN. keytool akzeptiert auch -addprovider SunPKCS11 -providerarg token.cfg anstelle des Paares -providerClass und -providerArg; beide Formen funktionieren, und die Dokumentation der Certificate Authority zeigt üblicherweise die ältere.

Mit dem Alias in der Hand erzeugen Sie den Schlüssel auf dem Gerät und fordern dann den CSR dafür an:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -dname "CN=Example LLC, O=Example LLC, L=Miami, ST=Florida, C=US"

keytool -certreq -alias codesign -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -file codesign.csr

Zwei Vorbehalte gelten. Manche Token erlauben keine Schlüsselerzeugung über PKCS#11 und erwarten, dass Sie das eigene Werkzeug des Herstellers verwenden, was in Ordnung ist: keytool kann dennoch den CSR gegen einen Schlüssel erstellen, den das Herstellertool erzeugt hat. Und keytool kann die Attestierungsdatei, nach der Ihre CA fragen wird, nicht erzeugen, erstellen Sie diese also zeitgleich mit dem Schlüssel mit der Herstellersoftware, gemäß der Anleitung für YubiKey oder Luna HSM.

Die CA-Antwort in denselben Alias importieren

Wenn das Zertifikat ankommt, muss es in denselben Eintrag zurück, der den CSR erzeugt hat. Importieren Sie es woanders hin, meldet keytool trotzdem Erfolg, erzeugt dabei aber einen Keystore, der nicht signieren kann, lesen Sie diesen Abschnitt also, bevor Sie irgendetwas ausführen.

Importieren Sie zunächst das Root-Zertifikat der CA und alle Zwischenzertifikate, jeweils unter einem eigenen Alias:

keytool -importcert -trustcacerts -alias caroot -file root.crt -keystore codesign.p12

keytool zeigt das Zertifikat an, das gespeichert werden soll, und fragt Trust this certificate? mit no als Standardwert, geben Sie also yes ein. Prüfen Sie den Fingerabdruck gegen den von Ihrer Certificate Authority veröffentlichten, bevor Sie antworten.

Überspringen Sie den Root-Import, schlägt der nächste Befehl mit einer Meldung fehl, die keinen Hinweis auf die Ursache gibt:

keytool error: java.lang.Exception: Failed to establish chain from reply

Importieren Sie nun Ihr ausgestelltes Zertifikat mit demselben Alias, den Sie in Schritt 1 verwendet haben:

keytool -importcert -alias codesign -file codesign.crt -keystore codesign.p12

Die Meldung, die Sie sehen wollen, lautet Certificate reply was installed in keystore. Das bedeutet, keytool hat einen bestehenden privaten Schlüssel unter diesem Alias erkannt und das ausgestellte Zertifikat samt Kette daran angehängt.

Wenn Sie stattdessen einen neuen Alias erfinden, akzeptiert keytool die Datei und gibt Certificate was added to keystore aus. Das sieht nach Erfolg aus, ist es aber nicht. keytool hat das Zertifikat als eigenständigen vertrauenswürdigen Eintrag ohne dahinterstehenden privaten Schlüssel gespeichert, und dieser Eintrag kann niemals etwas signieren. Der ursprüngliche Alias enthält währenddessen weiterhin das temporäre selbstsignierte Zertifikat aus Schritt 1. Prüfen Sie, welchen der beiden Sie haben:

keytool -list -keystore codesign.p12

Ihr Signierungs-Alias muss als PrivateKeyEntry aufgeführt sein. Ein als trustedCertEntry angezeigter Alias ist der oben beschriebene Fehler. Löschen Sie ihn mit keytool -delete -alias wrongalias -keystore codesign.p12 und wiederholen Sie den Import mit dem richtigen Alias. Fügen Sie -v zum Listenbefehl hinzu, um zu bestätigen, dass der Eintrag nun eine vollständige Zertifikatskette anstelle eines einzelnen selbstsignierten Zertifikats trägt.

Bei einem Hardware-Token gibt es in den meisten Fällen nichts zu importieren, da die CA das Zertifikat bereits vor dem Versand auf das Gerät lädt. Wenn Ihre CA Ihnen eine Zertifikatsdatei für einen Schlüssel sendet, den Sie auf Ihrem eigenen HSM erzeugt haben, verwenden Sie denselben -importcert-Befehl mit den PKCS#11-Optionen aus dem vorherigen Abschnitt.

Eine JAR-Datei mit dem Zertifikat signieren

Der Sinn, ein Codesignierungszertifikat in einem Java-Keystore zu haben, liegt darin, JAR-Dateien mit jarsigner zu signieren, das ebenfalls mit dem JDK ausgeliefert wird. Mit dem unter dem korrekten Alias installierten Zertifikat:

jarsigner -keystore codesign.p12 -tsa https://your-ca-timestamp-url application.jar codesign

Übergeben Sie immer -tsa mit der von Ihrer Certificate Authority veröffentlichten Zeitstempel-URL. Ein Zeitstempel dokumentiert, dass die JAR-Datei signiert wurde, während das Zertifikat noch gültig war, sodass die Signatur auch nach Ablauf des Zertifikats weiter funktioniert. Ohne einen solchen hört jede Kopie Ihrer Software an dem Tag auf, gültig zu erscheinen, an dem das Zertifikat abläuft.

Wenn der Schlüssel auf einem Token liegt, verweisen Sie jarsigner genau wie keytool auf PKCS#11:

jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -tsa https://your-ca-timestamp-url application.jar codesign

Wenn das Token zu wenig Platz für die vollständige Zertifikatskette hat, geben Sie diese separat mit -certchain an. Überprüfen Sie das Ergebnis anschließend:

jarsigner -verify -verbose -certs application.jar

Ein erfolgreicher Durchlauf gibt jar verified zusammen mit dem Distinguished Name des Unterzeichners und den Zeitstempeldetails aus. Aktuelle JDKs verwenden standardmäßig SHA-384 als Digest-Algorithmus, sodass Sie -digestalg oder -sigalg nur selten manuell setzen müssen.

Andere Möglichkeiten, diese Anfrage zu erstellen, werden in den Anleitungen zu OpenSSL, CertReq, Microsoft Management Console und macOS-Schlüsselbundverwaltung behandelt, und für alle gilt dieselbe Hardware-Regel. Siehe auch unsere vollständige Sammlung an Anleitungen zur Codesignierung und den Überblick zur CSR-Erstellung für Codesignierungszertifikate. Wenn Sie einen keytool-CSR für ein Website-Zertifikat anstelle eines Codesignierungszertifikats benötigen, folgen Sie stattdessen der Anleitung für Tomcat oder JBoss.

Häufig gestellte Fragen