Cloud HSM-Schlüssel mit OpenSSL verwenden

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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"

Wenn Sie die Umgebungsvariable dauerhaft festlegen möchten, fügen Sie export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" mit dem folgenden Befehl zu /etc/profile hinzu:

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

Mit OpenSSL und pkcs11-Tool verschlüsseln und entschlüsseln

Voraussetzung

  1. Erstellen Sie einen Cloud-HSM-Schlüssel und laden Sie den öffentlichen Schlüssel herunter.

  2. Erstellen Sie eine Eingabedatei mit etwas Text.

    echo Hello World! >> input.txt
    

Verschlüsseln

Führen Sie den folgenden Befehl aus, um eine Textdatei zu verschlüsseln:

openssl pkeyutl -in INPUT_TEXT_FILE_PATH -encrypt -pubin \
    -inkey PUBLIC_KEY \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256 > ENCRYPTED_TEXT_FILE_PATH

Dabei gilt:

  • INPUT_TEXT_FILE_PATH: Der Pfad zur Eingabedatei, die Sie verschlüsseln möchten.
  • PUBLIC_KEY: Der Pfad zum öffentlichen Schlüssel.
  • ENCRYPTED_TEXT_FILE_PATH: Der Pfad, unter dem die verschlüsselte Textdatei gespeichert werden soll.

Decrypt

Führen Sie den folgenden Befehl aus, um eine Textdatei zu entschlüsseln:

pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so \
    --decrypt --mechanism RSA-PKCS-OAEP --slot 0 --hash-algorithm=sha256 \
    --mgf MGF1-SHA256 --label HSM_KEY_NAME --type privkey \
    -i ENCRYPTED_TEXT_FILE_PATH \
    -o OUTPUT_TEXT_FILE_PATH

Dabei gilt:

  • HSM_KEY_NAME: Der Name des HSM-Schlüssels, der dem öffentlichen Schlüssel entspricht, der zum Verschlüsseln der Textdatei verwendet wurde.
  • ENCRYPTED_TEXT_FILE_PATH: Der Pfad zur Datei, die Sie entschlüsseln möchten.
  • OUTPUT_TEXT_FILE_PATH: Der Pfad, unter dem die entschlüsselte Ausgabe gespeichert werden soll.

Fehlerbehebung mit PKCS #11 Spion

PKCS #11 Spy ist ein Open-Source-Tool, das den Inhalt von Interaktionen über eine PKCS #11-Schnittstelle protokolliert. Dazu werden zwischen der Anwendung und der PKCS #11-Bibliothek sitzend und alle getätigten Aufrufe protokolliert. Dies kann bei der Fehlerbehebung hilfreich sein.

Wenn Sie PKCS #11 Spion verwenden möchten, muss das Paket opensc 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

Legen Sie dann die Umgebungsvariable PKCS11_MODULE_PATH so fest, dass OpenSSL auf die PKCS #11-Spy-Bibliothek verweist. Führen Sie dazu den folgenden Befehl aus:

export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so

Abschließend weisen Sie PKCS #11 Spion mit dem Verweis auf die Cloud HSM PKCS #11-Bibliothek an, indem Sie die Umgebungsvariablen PKCS11SPY und PKCS11SPY_OUTPUT festlegen. 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"