In dieser Anleitung wird beschrieben, wie Sie OpenSSL einrichten, um einen Cloud HSM-Schlüssel unter Debian 11 (Bullseye) zu verwenden. Diese Anleitung gilt im Allgemeinen auch dann, wenn Sie ein anderes Betriebssystem oder eine andere Umgebung verwenden. Beachten Sie jedoch, dass es geringfügige Unterschiede geben kann.
Voraussetzungen
Laden Sie als Erstes eine Version der Bibliothek herunter. Weitere Informationen zur PKCS #11-Bibliothek finden Sie im Nutzerhandbuch.
Installieren Sie zuerst das Paket libengine-pkcs11-openssl.
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
Konfiguration
Umgebungsvariable PKCS11_MODULE_PATH festlegen.
Damit openssl unsere PKCS #11-Bibliothek verwenden kann, legen Sie die Umgebungsvariable PKCS11_MODULE_PATH fest:
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
Um die Umgebungsvariable dauerhaft festzulegen, fügen Sie
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" nach /etc/profile
indem Sie den folgenden Befehl ausführen:
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile
PKCS #11-Bibliothekskonfiguration
Die PKCS #11-Bibliothek erfordert eine YAML-Konfigurationsdatei, um Cloud KMS-Ressourcen zu finden. Die YAML-Datei muss mindestens ein einzelnes PKCS #11-Token konfigurieren.
Wenn Sie OpenSSL mit einem anderen Prozess verwenden, der eventuell eine Verzweigung verursacht, z. B. Apache oder Nginx, müssen Sie außerdem dafür sorgen, dass das Feld refresh_interval_secs nicht festgelegt oder auf 0 gesetzt ist.
Beispielkonfigurationsdatei:
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
Bei dieser Konfiguration sind alle asymmetrischen Signatur- und Entschlüsselungsschlüssel in my-keyring in der Bibliothek verfügbar.
Sie müssen die Berechtigungen für die Konfigurationsdatei so festlegen, dass sie nur vom Dateiinhaber geschrieben werden kann. Verweisen Sie KMS_PKCS11_CONFIG auf Ihre Konfigurationsdatei:
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
Sie können diese Einstellung auch dauerhaft festlegen, indem Sie sie zu /etc/profile hinzufügen.
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
OpenSSL-Befehle ausführen
Wenn die Engine und die Bibliothek ordnungsgemäß konfiguriert sind, können Sie die Engine jetzt in OpenSSL-Befehlen verwenden.
Beachten Sie beim Erstellen asymmetrischer Signaturen, dass Cloud KMS-Schlüssel auf die Verwendung eines einzelnen Digests beschränkt sind. Beispiel: Eine CryptoKeyVersion mit dem Algorithmus EC_SIGN_P256_SHA256 muss immer in Verbindung mit einem SHA-256-Digest verwendet werden. Dies entspricht dem Flag -sha256 in OpenSSL. Schlüssel, für die SHA-384- oder SHA-512-Digests erforderlich sind, sollten mit den Flags -sha384 oder -sha512 verwendet werden.
Neue Signatur erstellen
Wenn Ihr konfigurierter Schlüsselbund einen Schlüssel mit dem Namen foo enthält, erstellen Sie mit dem folgenden Befehl eine Signatur über bar.txt:
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt
Die Ausgabe dieses Befehls ist nicht formatiert.
Dieser Befehl setzt voraus, dass Sie einen Schlüssel verwenden, der einen SHA-256-Digest verwendet. Daher wurde das Argument -sha256 verwendet. Die Optionen -sha384 oder -sha512 wären für Cloud HSM-Schlüssel geeignet, die diese Digesttypen verwenden.
Verwenden Sie für einen RSA-PSS-Schlüssel die zuvor beschriebenen Optionen -sigopt.
Neue Zertifikatsignierungsanfrage erstellen
Sie können auch eine Anfrage für die Signierung des Zertifikats (Certificate Signing Request, CSR) für einen Cloud HSM-Signaturschlüssel generieren. Dies ist nützlich, wenn Ihre Zertifizierungsstelle eine CSR benötigt, um ein neues Zertifikat für die Codesignierung zu generieren oder TLS-Websitzungen zu schützen.
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
Neues signiertes Zertifikat generieren
Für die lokale Entwicklung und für Testzwecke können Sie ein selbst signiertes Zertifikat für einen Cloud HSM-Signaturschlüssel verwenden. Selbst signierte Zertifikate sind auch für die Signierung von SAML-Tokens nützlich.
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
Fehlerbehebung mit PKCS #11 Spy
PKCS #11 Spy ist ein Open-Source-Tool, das den Inhalt von Interaktionen über eine PKCS #11-Schnittstelle protokolliert. Dies geschieht, indem es zwischen der Anwendung und die PKCS #11-Bibliothek und protokolliert alle erfolgten Aufrufe. Das kann bei der Fehlerbehebung hilfreich sein.
Wenn Sie PKCS #11 Spy verwenden möchten, muss das opensc-Paket installiert sein. Das Paket opensc enthält PKCS #11 Spy. Führen Sie den folgenden Befehl aus, um zu prüfen, ob opensc installiert ist:
sudo apt-get install opensc
Stellen Sie dann die Umgebungsvariable PKCS11_MODULE_PATH so ein, dass OpenSSL auf das
PKCS #11-Spy-Bibliothek durch Ausführen des folgenden Befehls:
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Verweisen Sie abschließend PKCS #11 Spy auf die Cloud HSM PKCS #11-Bibliothek, indem Sie die
Umgebungsvariablen PKCS11SPY und PKCS11SPY_OUTPUT. Führen Sie die folgenden Befehle aus, um diese Umgebungsvariablen festzulegen:
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"