Cloud HSM-Schlüssel mit OpenSSL verwenden

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. Ein Nutzerhandbuch steht zur Beratung zur Verfügung.

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"
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee /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 /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