Securosys integrationsguide

Förutsättningar

För att PKCS#11-motorn ska fungera smidigt med din Securosys Primus HSM och Encryption Consultings CodeSign Secure behöver du några viktiga saker. Här är stegen för att installera de resurser som är viktiga för att konfigurera Windows-miljön:

1. Securosys PKCS#11-leverantör

Securosys PKCS#11-providern (PrimusAPI PKCS#11) krävs för att samverka med Primus HSM. Detta bibliotek möjliggör kommunikation mellan dina applikationer och HSM via PKCS#11-standarden.

Installationssteg:

  1. Hämta nedladdningslänken

    Gå till Securosys supportportal för att hämta PrimusAPI_PKCS11-DownloadLink-v#.txt filen, som innehåller nedladdningsuppgifter och versionsinformation. Du behöver ett konto på Securosys supportportal. Om du inte har ett konto, kontakta Securosys support för att få åtkomst.

  2. Ladda ner leverantören

    • Använd kommandot curl för att ladda ner providerpaketet. Öppna en kommandotolk och kör följande kommandon: 

      sätt ANVÄNDARE=support.läsare.p11
      sätt CRED=

      Ersätta med värdet från textfilen. 

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

    • Alternativt kan du ladda ner ZIP-filen direkt från Securosys JFrog Artifactory med hjälp av en webbläsare. här.

      • Användarnamn: support.reader.p11
      • Lösenord: Hämta värdet från filen PrimusAPI_PKCS11-DownloadLink-v#.txt.
  3. Installera leverantören
    • Extrahera den nedladdade ZIP-filen och leta reda på MSI-installationsprogrammet (t.ex. PrimusAPI_PKCS11--win64.msi) i den extraherade mappen.
    • Dubbelklicka på MSI-filen för att köra installationsprogrammet och följ anvisningarna för att installera. Se till att du installerar på standardplatsen (C:\Program Files\Securosys\Primus P11) om inget annat anges.

      • Obs: Säkerhetskopiera alla befintliga konfigurationsfiler primus.cfg och .secrets.cfg i installationskatalogen, eftersom installationsprogrammet kan skriva över dem.

  4. Konfigurera miljövariabel

    Lägg till katalogplatsen för de installerade filerna i systemets sökväg (PATH) för enklare åtkomst. 

    C:\Program Files\Securosys\Primus P11
  5. Verifiering

    Öppna en ny kommandotolk och kör följande kommando för att testa de installerade verktygen: 

    ppin -v

2. OpenSSL 3.x

OpenSSL 3.x krävs för kryptografiska operationer och för att utnyttja PKCS#11-providern med Securosys HSM.

Installationssteg:

  1. Ladda ner OpenSSL

    Ladda ner den senaste 64-bitars OpenSSL 3.x-installationsversionen för Windows med hjälp av den här länk.

  2. Installera OpenSSL
    • Kör det nedladdade installationsprogrammet med administratörsbehörighet.
    • Välj standardinstallationskatalogen (C:\Program Files\OpenSSL-Win64) om du inte har specifika krav.
  3. Konfigurera miljövariabel

    Lägg till OpenSSL-binärkatalogen i systemets PATH:

    C:\Programfiler\OpenSSL-Win64\bin
  4. Verifiering

    Öppna en ny kommandotolk och kör följande kommando för att testa openssl-installationen. 

    openssl version

3. OpenSC PKCS11-verktyget

OpenSC PKCS#11-verktyget tillhandahåller verktyg som pkcs11-tool för att hantera nycklar och utföra operationer på HSM via PKCS#11-gränssnittet.

Installationssteg:

  1. Ladda ner OpenSC

    Ladda ner det senaste OpenSC Windows-installationsprogrammet från OpenSC GitHub-versionssidan här..

  2. Installera OpenSC

    Kör MSI-installationsprogrammet som administratör till standardplatsen (C:\Program Files\OpenSC Project\OpenSC).

  3. Konfigurera miljövariabel

    Lägg till OpenSC-verktygskatalogen i systemets PATH:

    C:\Programfiler\OpenSC-projekt\OpenSC\verktyg\
  4. Verifiering

    Öppna en ny kommandotolk och kör följande kommando för att testa pkcs11-tool 

    pkcs11-verktyg --version

4. Microsoft Visual Studio-byggverktyg

Microsoft Visual Studio Build Tools krävs för att kompilera OpenSC PKCS#11 Wrapper Library (libp11) i Windows.

Installationssteg:

  1. Ladda ner Visual Studio-byggverktyg

    Ladda ner Microsoft Build Tools för Visual Studio 2022 med hjälp av detta länk.

  2. Installera byggverktyg

    Kör installationsprogrammet (vs_buildtools.exe) med administratörsbehörighet.

  3. Verifiera installationen

    Öppna kommandotolken "x64 Native Tools" från Start-menyn och kör 

    nmake /?

    Detta bör visa hjälpen för nmake-verktyget, vilket bekräftar att byggverktygen är installerade.

    OBS: ”x64 Native Tools Command Prompt” borde finnas i C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2022\Visual Studio Tools\VC

5. OpenSC PKCS#11 Wrapper-bibliotek

OpenSC PKCS#11 Wrapper Library (libp11) tillhandahåller PKCS#11-motorpluginet (pkcs11.dll) för att OpenSSL ska kunna interagera med HSM.

Installationssteg:

  1. Ladda ner källkoden
    • Klona OpenSC/libp11-arkivet från GitHub eller ladda ner det som en ZIP-fil.
    • Klona med Git (om installerat):
      • git-klon https://github.com/OpenSC/libp11.git C:\Användare\ \source\repos\libp11
    • Eller ladda ner ZIP-filen från detta länk och extrahera den till C:\Användare\ \source\repos\libp11.
  2. Kompilera biblioteket
    • Öppna kommandotolken "x64 Native Tools".
    • Navigera till libp11-katalogen
      • cd “C:\Användare\\källa\repos\libp11”
    • Kör nmake-kommandot för att bygga biblioteket
      • nmake /f Makefile.mak OPENSSL_DIR="C:\Programfiler\OpenSSL-Win64" BYGG_FÖR=WIN64

      OBS: Se till att OPENSSL_DIR pekar till din OpenSSL-installationskatalog.

  3. Verifiera kompilering

    Leta efter filen pkcs11.dll i mappen libp11\src. Detta är OpenSC PKCS#11 Engine Plugin.

  4. Kopiera SRC-mappen

    Kopiera src-mappen som du just skapade till din OpenSSL bin-katalog, dvs. C:\Program Files\OpenSSL-Win64\bin

konfiguration

Efter att du har installerat förutsättningarna måste du konfigurera Securosys PKCS#11 Provider, OpenSSL och OpenSC PKCS#11 Wrapper Library för att möjliggöra kommunikation med din Securosys Primus HSM.

1. Konfigurera Securosys PKCS#11-leverantören

Securosys PKCS#11-providern kräver konfigurationsfiler (primus.cfg och .secrets.cfg) för att ange HSM-anslutningsdetaljer, såsom IP-adress, port, hemligheter och logginställningar.

Steg:

  1. Leta reda på konfigurationsfilen (primus.cfg)

    Navigera till installationskatalogen för Securosys PKCS#11 Provider, vanligtvis: 

    C:\Program Files\Securosys\Primus P11
  2. Redigera HSM-KONFIGURATIONSAVSNITTET med HSM-detaljer
    • Öppna primus.cfg i en textredigerare med administratörsbehörighet.
    • Lägg till eller uppdatera följande konfiguration i "HSM-KONFIGURATIONSAVSNITTET" och ersätt platshållare med dina HSM-uppgifter: 
      • hsm0: { host = "HSM VÄRDNAMN (som a-api.cloudshsm.com)"; port = "HSM PORT (som 2310)"; slots: { slot0: { client_id = "Client_ID1 (som Client_0)"; user_name = "PARTITION_NAME1"; proxy_user = "SERVICE_USER"; /* eller ta bort om ingen proxy behövs */ id = 1; }; /* end slot0 */ slot1: { client_id = "Client_ID2"; user_name = "PARTITION_NAME2"; proxy_user = "SERVICE_USER"; /* eller ta bort om ingen proxy behövs */ id = 2; }; /* end slot1 */ }; /* end slots */ }; /* end hsm0 */
  3. Redigera LOGGKONFIGURATIONSAVSNITTET med loggningsdetaljer

    Lägg till eller uppdatera följande konfiguration i "LOGGKONFIGURATIONSAVSNITTET" och ersätt platshållare med dina loggningsuppgifter: 

    log : { file = "C:\Program Files\Securosys\Primus P11\primus.log"; /* valfritt 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 loggnivådetaljer */ }; /* slut på logg */
  4. Konfigurera permanent hemlighet i .secrets.cfg-filen
    • Öppna en kommandotolk och navigera till Primus P11-katalogen (om den inte är angiven i miljövariabelns sökväg) med hjälp av kommandot nedan: 
      • cd C:\Program Files\Securosys\Primus P11
    • Ersätt platshållarvärdet med HSM-användarnamnsvärdet som du har angett i filen primus.cfg och kör följande kommando: 
      • ppin -a -e

      Konfigurera PKCS11_PIN för nämnda HSM_USERNAME

      OBS: Se till att du har läs- och skrivbehörighet för att ändra .secrets.cfg-filen med en permanent hemlighet.

  5. Verifiera anslutningen med HSM
    • Öppna en kommandotolk och navigera till Primus P11-katalogen (om den inte är angiven i miljövariabelns sökväg) med hjälp av kommandot nedan: 
      • cd C:\Program Files\Securosys\Primus P11
    • Kör ppin-verktyget för att testa HSM-anslutningen:
      • ppin -t

2. Konfigurera OpenSSL för att använda PKCS#11-motorn

OpenSSL måste konfigureras för att ladda Securosys PKCS#11 Provider (primusP11.dll) och OpenSC PKCS#11 Engine Plugin (pkcs11.dll) för att utföra kryptografiska operationer med HSM.

Steg:

  1. Leta reda på OpenSSL-konfigurationsfilen (openssl.cfg)

    Hitta OpenSSL-konfigurationsfilen:

    C:\Programfiler\Delade filer\SSL
  2. Redigera OpenSSL-konfigurationen
    • Öppna openssl.cfg i en textredigerare med administratörsbehörighet.
    • Lägg till följande högst upp i filen för att aktivera dynamisk motorbelastning: 
      • openssl_conf = openssl_init
    • Lägg till följande i slutet av filen för att konfigurera PKCS#11-motorn: 
      • [openssl_init] engines = engine_section [engine_section] pkcs11 = pkcs11_section [pkcs11_section] engine_id = pkcs11 dynamic_path = "C:\\Program Files\\OpenSSL-Win64\\src\\pkcs11.dll" MODULE_PATH = "C:\\Program Files\\Securosys\\Primus P11\\primusP11.dll" PIN = "PKCS11_PIN" init = 0

      Dynamisk_sökväg: Sökväg till OpenSC PKCS#11 Engine Plugin (pkcs11.dll) som kompilerats i förutsättningarna.

      MODUL_SÖKVÄG: Sökväg till Securosys PKCS#11 Provider-DLL:n.

      STIFT: PKCS11_PIN-värde för det obligatoriska HSM-användarnamnet/partitionen som anges under de permanenta hemliga stegen.

  3. Verifiera OpenSSL-konfiguration och anslutning
    • Öppna en kommandotolk och kör:
      • openssl-motor pkcs11 -t

    • Förväntad utdata bekräftar att PKCS#11-motorn är tillgänglig:

      (pkcs11) PKCS#11-motor

      [ tillgänglig ]

3. Testa PKCS#11-gränssnittet med pkcs11-tool

Använd OpenSC pkcs11-verktyget för att verifiera att PKCS#11-gränssnittet kan kommunicera med HSM.

Steg:

  1. Kör pkcs11-verktyget
    • Öppna en kommandotolk och navigera till OpenSC-verktygskatalogen, om den inte är angiven i miljövariabelns sökväg: 
      • cd “C:\Programfiler\OpenSC-projekt\OpenSC\verktyg”
    • Kör följande kommando för att lista tillgängliga platser på HSM: 
      • pkcs11-verktyg --modul "C:\Program\Securosys\Primus P11\primusP11.dll" --list-slots

4. Konfigurera CodeSign Secure

CodeSign Secure kräver konfiguration för att ansluta till Securosys Primus HSM för säkra kodsigneringsåtgärder. Filen app-config.properties anger de olika detaljerna för en lyckad anslutning till Securosys Primus HSM.

Steg:

  1. Leta reda på filen app-config.properties

    Navigera till mappen CertificateManagement i installationskatalogen för CodeSign Secure och leta reda på filen app-config.properties, vanligtvis: 

    C:\CodeSignSecure\src\CertificateManagement
  2. Uppdatera HSM-detaljfälten
    • Öppna app-config.properties i en textredigerare med administratörsbehörighet.
    • Uppdatera följande fält och ersätt platshållarna med dina HSM-anslutningsuppgifter: 
      • HSM_LIB_PATH_SECUROSYS= 
HSM_PIN_SECUROSYS= 
HSM_TOKEN_SECUROSYS= 
HSM_SLOT_SECUROSYS=
    • Spara filen med de ändrade uppgifterna.