Securosys-Integrationshandbuch

Voraussetzungen:

Damit die PKCS#11-Engine reibungslos mit Ihrem Securosys Primus HSM und CodeSign Secure von Encryption Consulting funktioniert, benötigen Sie einige wichtige Dinge. Hier sind die Schritte zur Installation der Ressourcen, die für die Einrichtung der Windows-Umgebung unerlässlich sind:

1. Securosys PKCS#11-Anbieter

Für die Schnittstelle zum Primus HSM wird der Securosys PKCS#11 Provider (PrimusAPI PKCS#11) benötigt. Diese Bibliothek ermöglicht die Kommunikation zwischen Ihren Anwendungen und dem HSM über den PKCS#11-Standard.

Installationsschritte:

  1. Download-Link erhalten

    Greifen Sie auf das Securosys-Supportportal zu, um die PrimusAPI_PKCS11-DownloadLink-v#.txt Datei, die die Download-Anmeldeinformationen und Versionsdetails enthält. Sie benötigen ein Konto im Securosys-Supportportal. Wenn Sie noch kein Konto haben, wenden Sie sich an den Securosys-Support, um Zugriff zu erhalten.

  2. Laden Sie den Anbieter herunter

    • Verwenden Sie den Befehl „curl“, um das Anbieterpaket herunterzuladen. Öffnen Sie eine Eingabeaufforderung und führen Sie die folgenden Befehle aus: 

      setze USER=support.reader.p11
      setze CRED=

      Ersetzen mit dem Wert aus der Textdatei. 

      setze VERSION=v2.3.4
      curl -L -o "PrimusAPI_PKCS11-%VERSION%.zip" https://%USER%:%CRED%@securosys.jfrog.io/artifactory/p11/PrimusAPI_PKCS11-%VERSION%.zip

    • Alternativ können Sie die ZIP-Datei direkt von der Securosys JFrog Artifactory über einen Browser herunterladen werden auf dieser Seite erläutert

      • Benutzername: support.reader.p11
      • Passwort: Übernehmen Sie den Wert aus der Datei PrimusAPI_PKCS11-DownloadLink-v#.txt.
  3. Installieren des Anbieters
    • Extrahieren Sie die heruntergeladene ZIP-Datei und suchen Sie das MSI-Installationsprogramm (z. B. PrimusAPI_PKCS11--win64.msi) im extrahierten Ordner.
    • Doppelklicken Sie auf die MSI-Datei, um das Installationsprogramm auszuführen, und folgen Sie den Anweisungen zur Installation. Stellen Sie sicher, dass Sie die Installation am Standardspeicherort (C:\Programme\Securosys\Primus P11) durchführen, sofern nicht anders erforderlich.

      • Hinweis: Sichern Sie alle vorhandenen Konfigurationsdateien primus.cfg und .secrets.cfg im Installationsverzeichnis, da das Installationsprogramm diese möglicherweise überschreibt.

  4. Umgebungsvariable konfigurieren

    Fügen Sie den Verzeichnisspeicherort der installierten Dateien zum Systempfad hinzu, um den Zugriff zu erleichtern. 

    C:\Programme\Securosys\Primus P11
  5. Verification

    Öffnen Sie eine neue Eingabeaufforderung und führen Sie den folgenden Befehl aus, um die installierten Tools zu testen: 

    ppin -v

2. OpenSSL 3.x

OpenSSL 3.x ist für kryptografische Vorgänge und zur Nutzung des PKCS#11-Anbieters mit dem Securosys HSM erforderlich.

Installationsschritte:

  1. OpenSSL herunterladen

    Laden Sie das neueste 64-Bit-OpenSSL 3.x-Installationsprogramm für Windows herunter. Link.

  2. Installieren Sie OpenSSL
    • Führen Sie das heruntergeladene Installationsprogramm mit Administratorrechten aus.
    • Wählen Sie das Standardinstallationsverzeichnis (C:\Programme\OpenSSL-Win64), sofern Sie keine besonderen Anforderungen haben.
  3. Umgebungsvariable konfigurieren

    Fügen Sie das OpenSSL-Binärverzeichnis zum Systempfad hinzu:

    C:\Programme\OpenSSL-Win64\bin
  4. Verification

    Öffnen Sie eine neue Eingabeaufforderung und führen Sie den folgenden Befehl aus, um die OpenSSL-Installation zu testen. 

    Openssl-Version

3. OpenSC PKCS11-Tool

Das OpenSC PKCS#11-Tool bietet Dienstprogramme wie pkcs11-tool zum Verwalten von Schlüsseln und Ausführen von Vorgängen auf dem HSM über die PKCS#11-Schnittstelle.

Installationsschritte:

  1. OpenSC herunterladen

    Laden Sie das neueste OpenSC Windows-Installationsprogramm von der OpenSC GitHub-Releases-Seite herunter werden auf dieser Seite erläutert.

  2. Installieren Sie OpenSC

    Führen Sie das MSI-Installationsprogramm als Administrator am Standardspeicherort (C:\Programme\OpenSC Project\OpenSC) aus.

  3. Umgebungsvariable konfigurieren

    Fügen Sie das OpenSC-Tools-Verzeichnis zum Systempfad hinzu:

    C:\Programme\OpenSC-Projekt\OpenSC\tools\
  4. Verification

    Öffnen Sie eine neue Eingabeaufforderung und führen Sie den folgenden Befehl aus, um pkcs11-tool zu testen 

    pkcs11-tool --version

4. Microsoft Visual Studio Build Tools

Zum Kompilieren der OpenSC PKCS#11 Wrapper Library (libp11) unter Windows sind Microsoft Visual Studio Build Tools erforderlich.

Installationsschritte:

  1. Laden Sie Visual Studio Build Tools herunter

    Laden Sie die Microsoft Build Tools für Visual Studio 2022 mit diesem herunter Link.

  2. Build-Tools installieren

    Führen Sie das Installationsprogramm (vs_buildtools.exe) mit Administratorrechten aus.

  3. Überprüfen Sie die Installation

    Öffnen Sie die Eingabeaufforderung „x64 Native Tools“ über das Startmenü und führen Sie 

    nmake /?

    Dadurch sollte die Hilfe für das Dienstprogramm nmake angezeigt werden, um zu bestätigen, dass die Build-Tools installiert sind.

    Anmerkungen: „x64 Native Tools Command Prompt“ sollte in C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2022\Visual Studio Tools\VC vorhanden sein

5. OpenSC PKCS#11 Wrapper-Bibliothek

Die OpenSC PKCS#11 Wrapper Library (libp11) stellt das PKCS#11-Engine-Plugin (pkcs11.dll) für OpenSSL zur Interaktion mit dem HSM bereit.

Installationsschritte:

  1. Laden Sie den Quellcode herunter
    • Klonen Sie das OpenSC/libp11-Repository von GitHub oder laden Sie es als ZIP-Datei herunter.
    • Klonen mit Git (falls installiert):
      • Git-Klon https://github.com/OpenSC/libp11.git C:\Benutzer\ \Quelle\Repositorys\libp11
    • Oder laden Sie die ZIP-Datei von diesem Link und extrahieren Sie es nach C:\Benutzer\ \source\repos\libp11.
  2. Kompilieren der Bibliothek
    • Öffnen Sie die „x64 Native Tools-Eingabeaufforderung“.
    • Navigieren Sie zum Verzeichnis libp11
      • cd „C:\Benutzer\\source\repos\libp11“
    • Führen Sie den Befehl nmake aus, um die Bibliothek zu erstellen
      • nmake /f Makefile.mak OPENSSL_DIR="C:\Programme\OpenSSL-Win64" BUILD_FOR=WIN64

      Anmerkungen: Stellen Sie sicher, dass OPENSSL_DIR auf Ihr OpenSSL-Installationsverzeichnis verweist.

  3. Kompilierung überprüfen

    Suchen Sie im Ordner libp11\src nach der Datei pkcs11.dll. Dies ist das OpenSC PKCS#11 Engine Plugin.

  4. Kopieren Sie den SRC-Ordner

    Kopieren Sie den soeben erstellten src-Ordner in Ihr OpenSSL-Bin-Verzeichnis, z. B. C:\Programme\OpenSSL-Win64\bin

Konfiguration

Nach der Installation der Voraussetzungen müssen Sie den Securosys PKCS#11 Provider, OpenSSL und die OpenSC PKCS#11 Wrapper Library konfigurieren, um die Kommunikation mit Ihrem Securosys Primus HSM zu ermöglichen.

1. Konfigurieren Sie den Securosys PKCS#11-Anbieter

Der Securosys PKCS#11 Provider benötigt Konfigurationsdateien (primus.cfg und .secrets.cfg), um die HSM-Verbindungsdetails wie IP-Adresse, Port, Geheimnisse und Protokollierungseinstellungen anzugeben.

Schritte:

  1. Suchen Sie die Konfigurationsdatei (primus.cfg)

    Navigieren Sie zum Installationsverzeichnis des Securosys PKCS#11-Providers, normalerweise: 

    C:\Programme\Securosys\Primus P11
  2. Bearbeiten Sie den HSM-Konfigurationsabschnitt mit HSM-Details
    • Öffnen Sie primus.cfg in einem Texteditor mit Administratorrechten.
    • Fügen Sie im Abschnitt „HSM-KONFIGURATION“ die folgende Konfiguration hinzu oder aktualisieren Sie sie. Ersetzen Sie dabei die Platzhalter durch Ihre HSM-Details: 
      • hsm0: {Host = "HSM-Hostname (wie a-api.cloudshsm.com)"; Port = "HSM-Port (wie 2310)"; Slots: {Slot0: {Client-ID = "Client-ID1 (wie Client_0)"; Benutzername = "Partitionsname1"; Proxy-Benutzer = "Dienstbenutzer"; /* oder entfernen, wenn kein Proxy benötigt wird */ ID = 1; }; /* Ende Slot0 */ Slot1: {Client-ID = "Client-ID2"; Benutzername = "Partitionsname2"; Proxy-Benutzer = "Dienstbenutzer"; /* oder entfernen, wenn kein Proxy benötigt wird */ ID = 2; }; /* Ende Slot1 */ }; /* Ende Slots */ }; /* Ende hsm0 */
  3. Bearbeiten Sie den Abschnitt „Protokollkonfiguration“ mit Protokollierungsdetails

    Fügen Sie die folgende Konfiguration im Abschnitt „Protokollkonfiguration“ hinzu oder aktualisieren Sie sie, und ersetzen Sie dabei die Platzhalter durch Ihre Protokolldetails: 

    log : { file = "C:\Programme\Securosys\Primus P11\primus.log"; /* optional für Windows */ trace_linenumber = false; trace_timestamp = true; trace_function = true; trace_inout = false; trace_pid = true; trace_filename = false; trace_mask = 0x01; trace_level = 6; /* 0-7 Protokollebenendetails */ }; /* Protokollende */
  4. Einrichten eines permanenten Geheimnisses in der Datei .secrets.cfg
    • Öffnen Sie eine Eingabeaufforderung und navigieren Sie mit dem folgenden Befehl zum Primus P11-Verzeichnis (sofern nicht im Umgebungsvariablenpfad festgelegt): 
      • cd C:\Programme\Securosys\Primus P11
    • Ersetzen Sie den Platzhalterwert durch den HSM-Benutzernamenwert, den Sie in der Datei primus.cfg festgelegt haben, und führen Sie den folgenden Befehl aus: 
      • ppin -a -e

      Richten Sie die PKCS11_PIN für den genannten HSM_USERNAME ein

      Anmerkungen: Stellen Sie sicher, dass Sie über Lese- und Schreibberechtigungen verfügen, um die Datei .secrets.cfg mit einem permanenten Geheimnis zu ändern.

  5. Überprüfen der Verbindung mit HSM
    • Öffnen Sie eine Eingabeaufforderung und navigieren Sie mit dem folgenden Befehl zum Primus P11-Verzeichnis (sofern nicht im Umgebungsvariablenpfad festgelegt): 
      • cd C:\Programme\Securosys\Primus P11
    • Führen Sie das Tool ppin aus, um die HSM-Verbindung zu testen:
      • ppin -t

2. Konfigurieren Sie OpenSSL für die Verwendung der PKCS#11-Engine

OpenSSL muss so konfiguriert werden, dass der Securosys PKCS#11 Provider (primusP11.dll) und das OpenSC PKCS#11 Engine Plugin (pkcs11.dll) geladen werden, um kryptografische Operationen mit dem HSM durchzuführen.

Schritte:

  1. Suchen Sie die OpenSSL-Konfigurationsdatei (openssl.cfg).

    Suchen Sie die OpenSSL-Konfigurationsdatei:

    C:\Programme\Gemeinsame Dateien\SSL
  2. Bearbeiten der OpenSSL-Konfiguration
    • Öffnen Sie openssl.cfg in einem Texteditor mit Administratorrechten.
    • Fügen Sie oben in der Datei Folgendes hinzu, um das dynamische Laden der Engine zu aktivieren: 
      • openssl_conf = openssl_init
    • Fügen Sie am Ende der Datei Folgendes hinzu, um die PKCS#11-Engine zu konfigurieren: 
      • [openssl_init] Engines = Engine-Abschnitt [Engine-Abschnitt] pkcs11 = pkcs11-Abschnitt [pkcs11-Abschnitt] Engine-ID = pkcs11 dynamischer Pfad = "C:\\Programme\\OpenSSL-Win64\\src\\pkcs11.dll" MODULE_PATH = "C:\\Programme\\Securosys\\Primus P11\\primusP11.dll" PIN = "PKCS11_PIN" init = 0

      Dynamischer_Pfad: Pfad zum in den Voraussetzungen kompilierten OpenSC PKCS#11 Engine Plugin (pkcs11.dll).

      MODULPFAD: Pfad zur Securosys PKCS#11 Provider DLL.

      PIN: PKCS11_PIN-Wert für den erforderlichen HSM-Benutzernamen/die erforderliche HSM-Partition, die während der Schritte zum permanenten Geheimnis festgelegt wurde.

  3. Überprüfen der OpenSSL-Konfiguration und -Verbindung
    • Öffnen Sie eine Eingabeaufforderung und führen Sie Folgendes aus:
      • OpenSSL-Engine pkcs11 -t

    • Die erwartete Ausgabe bestätigt, dass die PKCS#11-Engine verfügbar ist:

      (pkcs11) PKCS#11-Engine

      [ verfügbar ]

3. Testen Sie die PKCS#11-Schnittstelle mit pkcs11-tool

Verwenden Sie das OpenSC pkcs11-Tool, um zu überprüfen, ob die PKCS#11-Schnittstelle mit dem HSM kommunizieren kann.

Schritte:

  1. Führen Sie pkcs11-tool aus
    • Öffnen Sie eine Eingabeaufforderung und navigieren Sie zum OpenSC-Tools-Verzeichnis, falls dies nicht im Umgebungsvariablenpfad festgelegt ist: 
      • cd „C:\Programme\OpenSC-Projekt\OpenSC\tools“
    • Führen Sie den folgenden Befehl aus, um die verfügbaren Steckplätze auf dem HSM aufzulisten: 
      • pkcs11-tool --module "C:\Programme\Securosys\Primus P11\primusP11.dll" --list-slots

4. Konfigurieren Sie CodeSign Secure

CodeSign Secure erfordert eine Konfiguration für die Verbindung mit dem Securosys Primus HSM für sichere Code-Signaturvorgänge. Die Datei app-config.properties gibt die verschiedenen Details für eine erfolgreiche Verbindung mit dem Securosys Primus HSM an.

Schritte:

  1. Suchen Sie die Datei app-config.properties

    Navigieren Sie zum Ordner CertificateManagement im Installationsverzeichnis von CodeSign Secure und suchen Sie die Datei app-config.properties, normalerweise: 

    C:\CodeSignSecure\src\CertificateManagement
  2. Aktualisieren der HSM-Detailfelder
    • Öffnen Sie app-config.properties in einem Texteditor mit Administratorrechten.
    • Aktualisieren Sie die folgenden Felder und ersetzen Sie Platzhalter durch Ihre HSM-Verbindungsdetails: 
      • HSM_LIB_PATH_SECUROSYS= 
HSM_PIN_SECUROSYS= 
HSM_TOKEN_SECUROSYS= 
HSM_SLOT_SECUROSYS=
    • Speichern Sie die Datei mit den geänderten Angaben.